This post is auto-generated from RSS feed
The Rust Programming Language Forum - Latest topics . Source:
State of the ugly doubled TOC entries of mdbook?
I assume most readers of the official Rust tutorial book and of some other related online books suffer from the ugly duplicated TOC section entries, present due to latest mdbook updates since the end of last year?
That is, each section has a duplicated TOC entry, as in
https://doc.rust-lang.org/book/ch01-01-installation.html
with
1.1 Installation
Installation
Or does browsers or OSs exists that does not show this issue (I can' imagine that).
I have not added a screenshot of the issue here by intent, but if you can not see it in the official Rust book online version, you can find a screenshot at Fix #2995: Skip duplicate first header in sidebar header navigation by cobyfrombrooklyn-bot ยท Pull Request #3039 ยท rust-lang/mdBook ยท GitHub
This issue has been reported at the end of last year already, and there was even an attempt of an PR to fix that:
opened 09:12PM - 25 Dec 25 UTC
C-bug
### Problem
Dear Sir,
some weeks ago I updated my compact Rust beginner book tโฆ o your mdbook v0.5.1, and got issues about ugly duplicated TOC entries, see for example https://rust-for-c-programmers.com/ch5/5_1_keywords.html
Today I tried to fix that, testing with latest mdbook v0.5.2
My feeling is, that the reason for the duplication is, that I am using a CORRECT section header structure, starting with a chapter header starting with a single "#", following by sections starting with two "##" and so on. So the chapter header has the largest font size, the section headers are smaller, and so on. Like
```
stefan@hx90 ~/rust_for_c_programmers/src/ch5 $ cat chapter_5_common_programming_concepts.md
# Chapter 5: Common Programming Concepts
This chapter introduces fundamental programming concepts shared by most languages, illustrating how they function in Rust and drawing comparisons with C where relevant. We will cover **keywords**, **identifiers**, **expressions and statements**, core **data types** (including scalar types, tuples, and arrays), **variables** (focusing on mutability, constants, and statics), **operators**, **numeric literals**, **arithmetic overflow** behavior, performance aspects of numeric types, and **comments**.
While many concepts will feel familiar to C programmers, Rust's handling of types, mutability, and expressions often introduces stricter rules for enhanced safety and clarity. We defer detailed discussion of control flow (like `if` and loops) and functions until after covering memory management, as these constructs frequently interact with Rust's ownership model. Similarly, Rust's `struct` and powerful `enum` types, along with standard library collections like vectors and strings, will be detailed in dedicated later chapters.
---
stefan@hx90 ~/rust_for_c_programmers/src/ch5 $ cat 5_1_keywords.md
## 5.1 Keywords
Keywords are predefined, reserved words with special meanings in the Rust language. They form the building blocks of syntax and cannot be used as identifiers (like variable or function names) unless escaped using the **raw identifier** syntax (`r#keyword`). Many Rust keywords overlap with C/C++, but Rust adds several unique ones to support features like ownership, borrowing, pattern matching, and concurrency.
### 5.1.1 Raw Identifiers
```
Your own mdbook book seems to avoid this problem, by starting level 1 and level 2 headers both with a single "#", as in https://raw.githubusercontent.com/rust-lang/mdBook/refs/heads/master/guide/src/cli/init.md
```
# The init command
There is some minimal boilerplate that is the same for every new book. It's for
this purpose that mdBook includes an `init` command.
```
### Steps
1. Apply recent "mdbook build" on a mdproject with a correct section header structure.
2. Display it with "mdbook serve" or upload to a website
3. Inspect the TOC
### Possible Solution(s)
- Use an mdbook version < v0.5.0
- Use an incorrect headings structure, with level 1 and level 2 headings in same font size
- Try to disable the new extended TOC structure with detailed section listing
Best regards,
Dr. Stefan Salewski
### Notes
_No response_
### Version
```text
$ mdbook --version
mdbook v0.5.2
```
master โ cobyfrombrooklyn-bot:fix-issue-2995
opened 01:51AM - 25 Feb 26 UTC
## Problem
When a chapter's markdown file starts with a heading that matches thโฆ e chapter title from SUMMARY.md, the sidebar header navigation (introduced in v0.5.0) shows a duplicate entry. For example:
```markdown
- [5.1 Keywords](./5_1_keywords.md)
## 5.1 Keywords
Keywords are reserved words.
### 5.1.1 Raw Identifiers
...
```
The sidebar would show:
- **5.1 Keywords** (from SUMMARY.md, the chapter link)
- **5.1 Keywords** โ duplicate (from header nav scanning the h2)
- 5.1.1 Raw Identifiers
This is a common pattern when authors use proper heading hierarchy (`#` for chapter title, `##` for sections), as the reporter describes.
## Fix
Added deduplication logic in the sidebar header navigation JS (`toc.js.hbs`). After collecting page headers, it compares the first header's text against the active sidebar entry. If they match (after normalizing whitespace and stripping the section number prefix like "1.1."), the first header is skipped.
The comparison handles:
- Section number prefixes in the TOC (e.g., "1.1. 5.1 Keywords" โ extracts "5.1 Keywords")
- Whitespace normalization and case-insensitive matching
- Only affects the first header; all subsequent headers are always shown
## Test
Added `duplicate_toc_header_skipped` integration test with a minimal book that reproduces the issue (chapter title matching the first h2). Verifies the deduplication logic is present in the generated JS. Fails without the fix, passes with it.
Full test suite passes on macOS ARM (Apple Silicon): 270 tests, 0 failures.
But for some reason there is no progress.
3 posts - 3 participants
Read full topic
๐ท๏ธ Rust_feed
