fix(html): reserve toc.md and document toc.html

crates/mdbook-html/src/html_handlebars/hbs_renderer.rs

@@ -38,8 +38,8 @@ impl HtmlHandlebars {
         let ch = chapter_tree.chapter;
 
         let path = ch.path.as_ref().unwrap();
-        // "print.html" is used for the print page.
-        if path == Path::new("print.md") {
+        // "print.html" and "toc.html" are used for special output pages.
+        if path == Path::new("print.md") || path == Path::new("toc.md") {
             bail!("{} is reserved for internal use", path.display());
         };
 

guide/src/format/configuration/renderers.md

@@ -173,6 +173,16 @@ The following configuration options are available:
 
 [custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site
 
+#### `toc.html` and `toc.md`
+
+mdBook writes **`toc.html`** to the book output directory.
+It contains the table of contents for environments that do not run JavaScript (including some crawlers).
+
+**`toc.md` is reserved** for internal use.
+Do not create `src/toc.md` or add it to `SUMMARY.md`.
+A chapter named `toc.md` would be rendered to `toc.html` and overwrite the generated table of contents.
+If you try, the build fails with the error `toc.md is reserved for internal use`.
+
 ### `[output.html.print]`
 
 The `[output.html.print]` table provides options for controlling the printable output.
@@ -188,6 +198,16 @@ page-break = true # insert page-break after each chapter
   rendered. Defaults to `true`.
 - **page-break:** Insert page breaks between chapters. Defaults to `true`.
 
+#### `print.html` and `print.md`
+
+When print support is enabled, mdBook writes **`print.html`** to the book output directory.
+This file contains the entire book on a single page.
+The print icon in the menu bar (see [Reading a book](../../guide/reading.md)) opens this file for printing.
+
+**`print.md` is reserved** for internal use.
+Do not create `src/print.md` or add it to `SUMMARY.md`.
+If you do, the build fails with the error `print.md is reserved for internal use`.
+
 ### `[output.html.fold]`
 
 The `[output.html.fold]` table provides options for controlling folding of the chapter listing in the navigation sidebar.

tests/testsuite/build.rs

@@ -55,6 +55,19 @@ ERROR Rendering failed
     });
 }
 
+#[test]
+fn no_reserved_toc_filename() {
+    BookTest::from_dir("build/no_reserved_toc_filename").run("build", |cmd| {
+        cmd.expect_failure().expect_stderr(str![[r#"
+ INFO Book building has started
+ INFO Running the html backend
+ERROR Rendering failed
+[TAB]Caused by: toc.md is reserved for internal use
+
+"#]]);
+    });
+}
+
 // Build without book.toml should be OK.
 #[test]
 fn book_toml_isnt_required() {

tests/testsuite/build/no_reserved_toc_filename/book.toml

@@ -0,0 +1,2 @@
+[book]
+title = "no_reserved_toc_filename"

tests/testsuite/build/no_reserved_toc_filename/src/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+- [TOC](toc.md)

tests/testsuite/build/no_reserved_toc_filename/src/toc.md

@@ -0,0 +1,3 @@
+# TOC
+
+This should not be allowed.