Skip to content

feat: reserve toc.md and document reserved source filenames#3094

Open
ChrisJr404 wants to merge 1 commit into
rust-lang:masterfrom
ChrisJr404:reserve-toc-md-and-document-special-files
Open

feat: reserve toc.md and document reserved source filenames#3094
ChrisJr404 wants to merge 1 commit into
rust-lang:masterfrom
ChrisJr404:reserve-toc-md-and-document-special-files

Conversation

@ChrisJr404
Copy link
Copy Markdown

Summary

Two related issues filed by szabgab on the same day, addressed together because they share the same underlying behavior:

The HTML renderer already rejects print.md with print.md is reserved for internal use, because print.html is generated from the book's chapters and would otherwise be silently overwritten. The same situation applies to toc.html: it is the no-JavaScript table of contents fallback, generated from SUMMARY.md. Today, naming a chapter toc.md and referencing it from SUMMARY.md silently replaces the generated toc.html, which is confusing behavior (see issue #3090 for the original report and #3047 for the broader discussion).

Changes

  1. crates/mdbook-html/src/html_handlebars/hbs_renderer.rs: extend the existing reserved-filename check so toc.md is rejected the same way print.md is. The error message reuses the same template, so callers get toc.md is reserved for internal use.

  2. guide/src/guide/creating.md: add a "Reserved file names" subsection under "Source files" that documents both print.md / print.html and toc.md / toc.html, with a brief explanation of what each generated file is for. Links to the existing [output.html.print] config section for cross-reference.

  3. guide/src/format/summary.md: add a short "Reserved file names" subsection so users searching the SUMMARY.md reference page also find the constraint.

  4. tests/testsuite/build.rs + fixture tests/testsuite/build/no_reserved_filename_toc/: new test no_reserved_filename_toc that mirrors the existing no_reserved_filename test for print.md. Creates src/toc.md, references it from SUMMARY.md, and asserts the build fails with toc.md is reserved for internal use.

Test plan

  • cargo test --test testsuite no_reserved_filename passes (no_reserved_filename and the new no_reserved_filename_toc both green).
  • Full cargo test passes other than two preexisting environmental failures in preprocessor::nop_preprocessor / preprocessor::failing_preprocessor, which need a workspace Cargo.toml discoverable from the test's tmp dir (unrelated to this change; CI environment should not hit them).
  • Guide pages render without broken links: the new cross-reference to #outputhtmlprint matches the existing ### [output.html.print] anchor in guide/src/format/configuration/renderers.md.

The HTML renderer already rejects `print.md` because `print.html` is
generated from the book's chapters. The same situation applies to
`toc.md`: `toc.html` is the no-JavaScript table of contents fallback,
generated from `SUMMARY.md`. If a user names a chapter `toc.md` it
silently overwrites the generated `toc.html`, which is confusing.

Treat `toc.md` the same way `print.md` is treated and document both
file names in the user guide so they're discoverable when searching
for `print.md`, `print.html`, `toc.md`, or `toc.html`.

Closes rust-lang#3090
Closes rust-lang#3088

Signed-off-by: ChrisJr404 <[email protected]>
@rustbot rustbot added the S-waiting-on-review Status: waiting on a review label May 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-review Status: waiting on a review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document toc.md and toc.html and make toc.md a reserved file Update documentation to include print.md and print.html

2 participants