rust-lang / rust-lang/mdBook

Duplicated TOC entries for mdbook >= v0.5.0

Open
#2,995 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

Dear Sir,

some weeks ago I updated my compact Rust beginner book to 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
$ mdbook --version
mdbook v0.5.2

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the reported mdBook v0.5.2 reproduction: build and serve a book containing the shown #, ##, and ### heading structure, then inspect its TOC. Compare the duplicated entries with the expected hierarchy and verify that the corrected behavior still represents all sections without duplication.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.