Merge pull request #2629 from ehuss/bump-version

Update to 0.4.48

.eslintrc.json

@@ -0,0 +1,95 @@
+{
+    "env": {
+        "browser": true,
+        "node": true,
+        "es6": true
+    },
+    "extends": "eslint:recommended",
+    "globals": {
+        "module": "readonly",
+        "require": "readonly"
+    },
+    "parserOptions": {
+        "ecmaVersion": 2021,
+        "requireConfigFile": false,
+        "sourceType": "module"
+    },
+    "ignorePatterns": ["**min.js", "**/highlight.js", "**/playground_editor/*"],
+    "rules": {
+        "indent": [
+            "error",
+            4
+        ],
+        "linebreak-style": [
+            "error",
+            "unix"
+        ],
+        "quotes": [
+            "error",
+            "single"
+        ],
+        "semi": [
+            "error",
+            "always"
+        ],
+        "brace-style": [
+            "error",
+            "1tbs",
+            { "allowSingleLine": false }
+        ],
+        "curly": "error",
+        "no-trailing-spaces": "error",
+        "no-multi-spaces": "error",
+        "keyword-spacing": [
+            "error",
+            { "before": true, "after": true }
+        ],
+        "comma-spacing": [
+            "error",
+            { "before": false, "after": true }
+        ],
+        "arrow-spacing": [
+            "error",
+            { "before": true, "after": true }
+        ],
+        "key-spacing": [
+            "error",
+            { "beforeColon": false, "afterColon": true, "mode": "strict" }
+        ],
+        "func-call-spacing": ["error", "never"],
+        "space-infix-ops": "error",
+        "space-before-function-paren": ["error", "never"],
+        "space-before-blocks": "error",
+        "no-console": [
+            "error",
+            { "allow": ["warn", "error"] }
+        ],
+        "comma-dangle": ["error", "always-multiline"],
+        "comma-style": ["error", "last"],
+        "max-len": ["error", { "code": 100, "tabWidth": 2 }],
+        "eol-last": ["error", "always"],
+        "no-extra-parens": "error",
+        "arrow-parens": ["error", "as-needed"],
+        "no-unused-vars": [
+            "error",
+            {
+                "argsIgnorePattern": "^_",
+                "varsIgnorePattern": "^_"
+            }
+        ],
+        "prefer-const": ["error"],
+        "no-var": "error",
+        "eqeqeq": "error"
+    },
+    "overrides": [
+        {
+            "files": [
+                "tests/**/*.js"
+            ],
+            "env": {
+                "jest": true,
+                "node": true
+            }
+        }
+    ]
+}

.github/workflows/deploy.yml

@@ -17,13 +17,15 @@ jobs:
       matrix:
         include:
           - target: aarch64-unknown-linux-musl
-            os: ubuntu-20.04
+            os: ubuntu-22.04
           - target: x86_64-unknown-linux-gnu
-            os: ubuntu-20.04
+            os: ubuntu-22.04
           - target: x86_64-unknown-linux-musl
-            os: ubuntu-20.04
+            os: ubuntu-22.04
           - target: x86_64-apple-darwin
             os: macos-latest
+          - target: aarch64-apple-darwin
+            os: macos-latest
           - target: x86_64-pc-windows-msvc
             os: windows-latest
     name: Deploy ${{ matrix.target }}
@@ -46,7 +48,7 @@ jobs:
       run: rustup update stable --no-self-update && rustup default stable
     - name: Build book
       run: cargo run -- build guide
-    - name: Deploy to GitHub
+    - name: Deploy the User Guide to GitHub Pages using the gh-pages branch
       env:
         GITHUB_DEPLOY_KEY: ${{ secrets.GITHUB_DEPLOY_KEY }}
       run: |

.github/workflows/main.yml

@@ -22,7 +22,7 @@ jobs:
             rust: nightly
             target: x86_64-unknown-linux-gnu
           - name: stable x86_64-unknown-linux-musl
-            os: ubuntu-20.04
+            os: ubuntu-22.04
             rust: stable
             target: x86_64-unknown-linux-musl
           - name: stable x86_64 macos
@@ -38,9 +38,9 @@ jobs:
             rust: stable
             target: x86_64-pc-windows-msvc
           - name: msrv
-            os: ubuntu-20.04
+            os: ubuntu-22.04
             # sync MSRV with docs: guide/src/guide/installation.md and Cargo.toml
-            rust: 1.74.0
+            rust: 1.77.0
             target: x86_64-unknown-linux-gnu
     name: ${{ matrix.name }}
     steps:
@@ -53,7 +53,7 @@ jobs:
       run: cargo test --no-default-features --target ${{ matrix.target }}
 
   aarch64-cross-builds:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
     - name: Install Rust
@@ -70,6 +70,24 @@ jobs:
       run: rustup update stable && rustup default stable && rustup component add rustfmt
     - run: cargo fmt --check
 
+  gui:
+    name: GUI tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu
+      - name: Install npm
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - name: Install browser-ui-test
+        run: npm install
+      - name: Run eslint
+        run: npm run lint
+      - name: Build and run tests (+ GUI)
+        run: cargo test --locked --target x86_64-unknown-linux-gnu --test gui
+
   # The success job is here to consolidate the total success/failure state of
   # all other jobs. This job is then included in the GitHub branch protection
   # rule which prevents merges unless all other jobs are passing. This makes

.gitignore

@@ -16,3 +16,8 @@ test_book/book/
 # Ignore Vim temporary and swap files.
 *.sw?
 *~
+
+# GUI tests
+node_modules
+package-lock.json
+package.json

CHANGELOG.md

@@ -1,8 +1,117 @@
 # Changelog
 
+## mdBook 0.4.48
+[v0.4.47...v0.4.48](https://github.com/rust-lang/mdBook/compare/v0.4.47...v0.4.48)
+
+### Added
+
+- Footnotes now have back-reference links. These links bring the reader back to the original location. As part of this change, footnotes are now only rendered at the bottom of the page. This also includes some styling updates and fixes for footnote rendering.
+  [#2626](https://github.com/rust-lang/mdBook/pull/2626)
+- Added an "Auto" theme selection option which will default to the system-preferred mode. This will also automatically switch when the system changes the preferred mode.
+  [#2576](https://github.com/rust-lang/mdBook/pull/2576)
+
+### Changed
+
+- The `searchindex.json` file has been removed; only the `searchindex.js` file will be generated.
+  [#2552](https://github.com/rust-lang/mdBook/pull/2552)
+- Updated Javascript code to use eslint.
+  [#2554](https://github.com/rust-lang/mdBook/pull/2554)
+- An error is generated if there are duplicate files in `SUMMARY.md`.
+  [#2613](https://github.com/rust-lang/mdBook/pull/2613)
+
+## mdBook 0.4.47
+[v0.4.46...v0.4.47](https://github.com/rust-lang/mdBook/compare/v0.4.46...v0.4.47)
+
+### Fixed
+
+- Fixed search not showing up in sub-directories.
+  [#2586](https://github.com/rust-lang/mdBook/pull/2586)
+
+## mdBook 0.4.46
+[v0.4.45...v0.4.46](https://github.com/rust-lang/mdBook/compare/v0.4.45...v0.4.46)
+
+### Changed
+
+- The `output.html.hash-files` config option has been added to add hashes to static filenames to bust any caches when a book is updated. `{{resource}}` template tags have been added so that links can be properly generated to those files.
+  [#1368](https://github.com/rust-lang/mdBook/pull/1368)
+
+### Fixed
+
+- Playground links for Rust 2024 now set the edition correctly.
+  [#2557](https://github.com/rust-lang/mdBook/pull/2557)
+
+## mdBook 0.4.45
+[v0.4.44...v0.4.45](https://github.com/rust-lang/mdBook/compare/v0.4.44...v0.4.45)
+
+### Changed
+
+- Added context to error message when rustdoc is not found.
+  [#2545](https://github.com/rust-lang/mdBook/pull/2545)
+- Slightly changed the styling rules around margins of footnotes.
+  [#2524](https://github.com/rust-lang/mdBook/pull/2524)
+
+### Fixed
+
+- Fixed an issue where it would panic if a source_path is not set.
+  [#2550](https://github.com/rust-lang/mdBook/pull/2550)
+
+## mdBook 0.4.44
+[v0.4.43...v0.4.44](https://github.com/rust-lang/mdBook/compare/v0.4.43...v0.4.44)
+
+### Added
+
+- Added pre-built aarch64-apple-darwin binaries to the releases.
+  [#2500](https://github.com/rust-lang/mdBook/pull/2500)
+- `mdbook clean` now shows a summary of what it did.
+  [#2458](https://github.com/rust-lang/mdBook/pull/2458)
+- Added the `output.html.search.chapter` config setting to disable search indexing of individual chapters.
+  [#2533](https://github.com/rust-lang/mdBook/pull/2533)
+
+### Fixed
+
+- Fixed auto-scrolling the side-bar when loading a page with a `#` fragment URL.
+  [#2517](https://github.com/rust-lang/mdBook/pull/2517)
+- Fixed display of sidebar when javascript is disabled.
+  [#2529](https://github.com/rust-lang/mdBook/pull/2529)
+- Fixed the sidebar visibility getting out of sync with the button.
+  [#2532](https://github.com/rust-lang/mdBook/pull/2532)
+
+### Changed
+
+- ❗ Rust code block hidden lines now follow the same logic as rustdoc. This requires a space after the `#` symbol.
+  [#2530](https://github.com/rust-lang/mdBook/pull/2530)
+- ❗ Updated the Linux pre-built binaries which requires a newer version of glibc (2.34).
+  [#2523](https://github.com/rust-lang/mdBook/pull/2523)
+- Updated dependencies
+  [#2538](https://github.com/rust-lang/mdBook/pull/2538)
+  [#2539](https://github.com/rust-lang/mdBook/pull/2539)
+
+## mdBook 0.4.43
+[v0.4.42...v0.4.43](https://github.com/rust-lang/mdBook/compare/v0.4.42...v0.4.43)
+
+### Fixed
+
+- Fixed setting the title in `mdbook init` when no git user is configured.
+  [#2486](https://github.com/rust-lang/mdBook/pull/2486)
+
+### Changed
+
+- The Rust 2024 edition no longer needs `-Zunstable-options`.
+  [#2495](https://github.com/rust-lang/mdBook/pull/2495)
+
+## mdBook 0.4.42
+[v0.4.41...v0.4.42](https://github.com/rust-lang/mdBook/compare/v0.4.41...v0.4.42)
+
+### Fixed
+
+- Fixed chapter list folding.
+  [#2473](https://github.com/rust-lang/mdBook/pull/2473)
+
 ## mdBook 0.4.41
 [v0.4.40...v0.4.41](https://github.com/rust-lang/mdBook/compare/v0.4.40...v0.4.41)
 
+**Note:** If you have a custom `index.hbs` theme file, you will need to update it to the latest version.
+
 ### Added
 
 - Added preliminary support for Rust 2024 edition.

CONTRIBUTING.md

@@ -138,8 +138,45 @@ We generally strive to keep mdBook compatible with a relatively recent browser o
 That is, supporting Chrome, Safari, Firefox, Edge on Windows, macOS, Linux, iOS, and Android.
 If possible, do your best to avoid breaking older browser releases.
 
-Any change to the HTML or styling is encouraged to manually check on as many browsers and platforms that you can.
-Unfortunately at this time we don't have any automated UI or browser testing, so your assistance in testing is appreciated.
+GUI tests are checked with the GUI testsuite. To run it, you need to install `npm` first. Then run:
+
+```
+cargo test --test gui
+```
+
+If you want to only run some tests, you can filter them by passing (part of) their name:
+
+```
+cargo test --test gui -- search
+```
+
+The first time, it'll fail and ask you to install the `browser-ui-test` package. Install it with the provided
+command then re-run the tests.
+
+If you want to disable the headless mode, use the `--disable-headless-test` option:
+
+```
+cargo test --test gui -- --disable-headless-test
+```
+
+The GUI tests are in the directory `tests/gui` in text files with the `.goml` extension. These tests are run
+using a `node.js` framework called `browser-ui-test`. You can find documentation for this language on its
+[repository](https://github.com/GuillaumeGomez/browser-UI-test/blob/master/goml-script.md).
+
+### Checking changes in `.js` files
+
+The `.js` files source code is checked using [`eslint`](https://eslint.org/). This is a linter (just like `clippy` in Rust)
+for the Javascript language. You can install it with `npm` by running the following command:
+
+```
+npm install
+```
+
+Then you can run it using:
+
+```
+npm run lint
+```
 
 ## Updating highlight.js
 

Cargo.toml

@@ -3,7 +3,7 @@ members = [".", "examples/remove-emphasis/mdbook-remove-emphasis"]
 
 [package]
 name = "mdbook"
-version = "0.4.41"
+version = "0.4.48"
 authors = [
     "Mathieu David <mathieudavid@mathieudavid.org>",
     "Michael-F-Bryan <michaelfbryan@gmail.com>",
@@ -17,7 +17,7 @@ license = "MPL-2.0"
 readme = "README.md"
 repository = "https://github.com/rust-lang/mdBook"
 description = "Creates a book from markdown files"
-rust-version = "1.74"
+rust-version = "1.77" # Keep in sync with installation.md and .github/workflows/main.yml
 
 [dependencies]
 anyhow = "1.0.71"
@@ -27,6 +27,7 @@ clap_complete = "4.3.2"
 once_cell = "1.17.1"
 env_logger = "0.11.1"
 handlebars = "6.0"
+hex = "0.4.3"
 log = "0.4.17"
 memchr = "2.5.0"
 opener = "0.7.0"
@@ -34,14 +35,15 @@ pulldown-cmark = { version = "0.10.0", default-features = false, features = ["ht
 regex = "1.8.1"
 serde = { version = "1.0.163", features = ["derive"] }
 serde_json = "1.0.96"
+sha2 = "0.10.8"
 shlex = "1.3.0"
 tempfile = "3.4.0"
 toml = "0.5.11" # Do not update, see https://github.com/rust-lang/mdBook/issues/2037
 topological-sort = "0.2.2"
 
 # Watch feature
-notify = { version = "6.1.1", optional = true }
-notify-debouncer-mini = { version = "0.4.1", optional = true }
+notify = { version = "8.0.0", optional = true }
+notify-debouncer-mini = { version = "0.6.0", optional = true }
 ignore = { version = "0.4.20", optional = true }
 pathdiff = { version = "0.2.1", optional = true }
 walkdir = { version = "2.3.3", optional = true }
@@ -82,3 +84,10 @@ name = "remove-emphasis"
 path = "examples/remove-emphasis/test.rs"
 crate-type = ["lib"]
 test = true
+
+[[test]]
+harness = false
+test = false
+name = "gui"
+path = "tests/gui/runner.rs"
+crate-type = ["bin"]

README.md

@@ -1,6 +1,6 @@
 # mdBook
 
-[![Build Status](https://github.com/rust-lang/mdBook/workflows/CI/badge.svg?event=push)](https://github.com/rust-lang/mdBook/actions?workflow=CI)
+[![CI Status](https://github.com/rust-lang/mdBook/actions/workflows/main.yml/badge.svg)](https://github.com/rust-lang/mdBook/actions/workflows/main.yml)
 [![crates.io](https://img.shields.io/crates/v/mdbook.svg)](https://crates.io/crates/mdbook)
 [![LICENSE](https://img.shields.io/github/license/rust-lang/mdBook.svg)](LICENSE)
 

guide/book.toml

@@ -13,6 +13,7 @@ mathjax-support = true
 site-url = "/mdBook/"
 git-repository-url = "https://github.com/rust-lang/mdBook/tree/master/guide"
 edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
+hash-files = true
 
 [output.html.playground]
 editable = true

guide/src/continuous-integration.md

@@ -21,7 +21,7 @@ A simple approach would be to use the popular `curl` CLI tool to download the ex
 
 ```sh
 mkdir bin
-curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.41/mdbook-v0.4.41-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.48/mdbook-v0.4.48-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
 bin/mdbook build
 ```
 

guide/src/format/configuration/renderers.md

@@ -168,6 +168,12 @@ The following configuration options are available:
   This string will be written to a file named CNAME in the root of your site, as
   required by GitHub Pages (see [*Managing a custom domain for your GitHub Pages
   site*][custom domain]).
+- **hash-files:** Include a cryptographic "fingerprint" of the files' contents in static asset filenames,
+  so that if the contents of the file are changed, the name of the file will also change.
+  For example, `css/chrome.css` may become `css/chrome-9b8f428e.css`.
+  Chapter HTML files are not renamed.
+  Static CSS and JS files can reference each other using `{{ resource "filename" }}` directives.
+  Defaults to `false` (in a future release, this may change to `true`).
 
 [custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site
 
@@ -281,6 +287,20 @@ copy-js = true           # include Javascript code for search
 - **copy-js:** Copy JavaScript files for the search implementation to the output
   directory. Defaults to `true`.
 
+#### `[output.html.search.chapter]`
+
+The [`output.html.search.chapter`] table provides the ability to modify search settings per chapter or directory. Each key is the path to the chapter source file or directory, and the value is a table of settings to apply to that path. This will merge recursively, with more specific paths taking precedence.
+
+```toml
+[output.html.search.chapter]
+# Disables search indexing for all chapters in the `appendix` directory.
+"appendix" = { enable = false }
+# Enables search indexing for just this one appendix chapter.
+"appendix/glossary.md" = { enable = true }
+```
+
+- **enable:** Enables or disables search indexing for the given chapters. Defaults to `true`. This does not override the overall `output.html.search.enable` setting; that must be `true` for any search functionality to be enabled. Be cautious when disabling indexing for chapters because that can potentially lead to user confusion when they search for terms and expect them to be found. This should only be used in exceptional circumstances where keeping the chapter in the index will cause issues with the quality of the search results.
+
 ### `[output.html.redirect]`
 
 The `[output.html.redirect]` table provides a way to add redirects.

guide/src/format/mdbook.md

@@ -4,7 +4,8 @@
 
 There is a feature in mdBook that lets you hide code lines by prepending them with a specific prefix.
 
-For the Rust language, you can use the `#` character as a prefix which will hide lines [like you would with Rustdoc][rustdoc-hide].
+For the Rust language, you can prefix lines with `# ` (`#` followed by a space) to hide them [like you would with Rustdoc][rustdoc-hide].
+This prefix can be escaped with `##` to prevent the hiding of a line that should begin with the literal string `# ` (see [Rustdoc's docs][rustdoc-hide] for more details)
 
 [rustdoc-hide]: https://doc.rust-lang.org/stable/rustdoc/write-documentation/documentation-tests.html#hiding-portions-of-the-example
 

guide/src/format/theme/editor.md

@@ -9,8 +9,8 @@ be added to the ***book.toml***:
 editable = true
 ```
 
-To make a specific block available for editing, the attribute `editable` needs
-to be added to it:
+After enabling editable code blocks, the `editable` attribute must be added to a
+code block to make it editable:
 
 ~~~markdown
 ```rust,editable

guide/src/format/theme/index-hbs.md

@@ -99,3 +99,13 @@ Of course the inner html can be changed to your liking.
 
 *If you would like other properties or helpers exposed, please [create a new
 issue](https://github.com/rust-lang/mdBook/issues)*
+
+### 3. resource
+
+The path to a static file.
+It implicitly includes `path_to_root`,
+and accounts for files that are renamed with a hash in their filename.
+
+```handlebars
+<link rel="stylesheet" href="{{ resource "css/chrome.css" }}">
+```

guide/src/guide/installation.md

@@ -20,7 +20,7 @@ To make it easier to run, put the path to the binary into your `PATH`.
 
 To build the `mdbook` executable from source, you will first need to install Rust and Cargo.
 Follow the instructions on the [Rust installation page].
-mdBook currently requires at least Rust version 1.74.
+mdBook currently requires at least Rust version 1.77.
 
 Once you have installed Rust, the following command can be used to build and install mdBook:
 

package.json

@@ -0,0 +1,10 @@
+{
+  "dependencies": {
+    "browser-ui-test": "0.19.0",
+    "eslint": "^8.57.1"
+  },
+  "scripts": {
+    "lint": "eslint src/front-end/*js src/front-end/**/*js",
+    "lint-fix": "eslint --fix src/front-end/*js src/front-end/**/*js"
+  }  
+}

src/book/book.rs

@@ -173,7 +173,8 @@ pub struct Chapter {
     /// `index.md` via the [`Chapter::path`] field. The `source_path` field
     /// exists if you need access to the true file path.
     ///
-    /// This is `None` for a draft chapter.
+    /// This is `None` for a draft chapter, or a synthetically generated
+    /// chapter that has no file on disk.
     pub source_path: Option<PathBuf>,
     /// An ordered list of the names of each chapter above this one in the hierarchy.
     pub parent_names: Vec<String>,
@@ -646,4 +647,19 @@ And here is some \
         let got = load_book_from_disk(&summary, temp.path());
         assert!(got.is_err());
     }
+
+    #[test]
+    fn cant_open_summary_md() {
+        let cfg = BuildConfig::default();
+        let temp_dir = TempFileBuilder::new().prefix("book").tempdir().unwrap();
+
+        let got = load_book(&temp_dir, &cfg);
+        assert!(got.is_err());
+        let error_message = got.err().unwrap().to_string();
+        let expeceted = format!(
+            r#"Couldn't open SUMMARY.md in {:?} directory"#,
+            temp_dir.path()
+        );
+        assert_eq!(error_message, expeceted);
+    }
 }

src/book/mod.rs

@@ -346,7 +346,7 @@ impl MDBook {
                             cmd.args(["--edition", "2021"]);
                         }
                         RustEdition::E2024 => {
-                            cmd.args(["--edition", "2024", "-Zunstable-options"]);
+                            cmd.args(["--edition", "2024"]);
                         }
                     }
                 }
@@ -356,7 +356,9 @@ impl MDBook {
                 }
 
                 debug!("running {:?}", cmd);
-                let output = cmd.output()?;
+                let output = cmd
+                    .output()
+                    .with_context(|| "failed to execute `rustdoc`")?;
 
                 if !output.status.success() {
                     failed = true;

src/book/summary.rs

@@ -3,6 +3,7 @@ use log::{debug, trace, warn};
 use memchr::Memchr;
 use pulldown_cmark::{DefaultBrokenLinkCallback, Event, HeadingLevel, Tag, TagEnd};
 use serde::{Deserialize, Serialize};
+use std::collections::HashSet;
 use std::fmt::{self, Display, Formatter};
 use std::ops::{Deref, DerefMut};
 use std::path::{Path, PathBuf};
@@ -245,6 +246,11 @@ impl<'a> SummaryParser<'a> {
             .parse_affix(false)
             .with_context(|| "There was an error parsing the suffix chapters")?;
 
+        let mut files = HashSet::new();
+        for part in [&prefix_chapters, &numbered_chapters, &suffix_chapters] {
+            self.check_for_duplicates(&part, &mut files)?;
+        }
+
         Ok(Summary {
             title,
             prefix_chapters,
@@ -253,6 +259,29 @@ impl<'a> SummaryParser<'a> {
         })
     }
 
+    /// Recursively check for duplicate files in the summary items.
+    fn check_for_duplicates<'b>(
+        &self,
+        items: &'b [SummaryItem],
+        files: &mut HashSet<&'b PathBuf>,
+    ) -> Result<()> {
+        for item in items {
+            if let SummaryItem::Link(link) = item {
+                if let Some(location) = &link.location {
+                    if !files.insert(location) {
+                        bail!(anyhow::anyhow!(
+                            "Duplicate file in SUMMARY.md: {:?}",
+                            location
+                        ));
+                    }
+                }
+                // Recursively check nested items
+                self.check_for_duplicates(&link.nested_items, files)?;
+            }
+        }
+        Ok(())
+    }
+
     /// Parse the affix chapters.
     fn parse_affix(&mut self, is_prefix: bool) -> Result<Vec<SummaryItem>> {
         let mut items = Vec::new();
@@ -747,6 +776,20 @@ mod tests {
         let got = parser.parse_affix(false);
 
         assert!(got.is_err());
+        let error_message = got.err().unwrap().to_string();
+        assert_eq!(error_message, "failed to parse SUMMARY.md line 2, column 1: Suffix chapters cannot be followed by a list");
+    }
+
+    #[test]
+    fn expected_a_start_of_a_link() {
+        let src = "- Title\n";
+        let mut parser = SummaryParser::new(src);
+
+        let got = parser.parse_affix(false);
+
+        assert!(got.is_err());
+        let error_message = got.err().unwrap().to_string();
+        assert_eq!(error_message, "failed to parse SUMMARY.md line 1, column 0: Suffix chapters cannot be followed by a list");
     }
 
     #[test]
@@ -1113,4 +1156,83 @@ mod tests {
         let got = parser.parse_affix(false).unwrap();
         assert_eq!(got, should_be);
     }
+
+    #[test]
+    fn duplicate_entries_1() {
+        let src = r#"
+# Summary
+- [A](./a.md)
+- [A](./a.md)
+"#;
+
+        let res = parse_summary(src);
+        assert!(res.is_err());
+        let error_message = res.err().unwrap().to_string();
+        assert_eq!(error_message, r#"Duplicate file in SUMMARY.md: "./a.md""#);
+    }
+
+    #[test]
+    fn duplicate_entries_2() {
+        let src = r#"
+# Summary
+- [A](./a.md)
+  - [A](./a.md)
+"#;
+
+        let res = parse_summary(src);
+        assert!(res.is_err());
+        let error_message = res.err().unwrap().to_string();
+        assert_eq!(error_message, r#"Duplicate file in SUMMARY.md: "./a.md""#);
+    }
+    #[test]
+    fn duplicate_entries_3() {
+        let src = r#"
+# Summary
+- [A](./a.md)
+- [B](./b.md)
+  - [A](./a.md)
+"#;
+
+        let res = parse_summary(src);
+        assert!(res.is_err());
+        let error_message = res.err().unwrap().to_string();
+        assert_eq!(error_message, r#"Duplicate file in SUMMARY.md: "./a.md""#);
+    }
+
+    #[test]
+    fn duplicate_entries_4() {
+        let src = r#"
+# Summary
+[A](./a.md)
+- [B](./b.md)
+- [A](./a.md)
+"#;
+
+        let res = parse_summary(src);
+        assert!(res.is_err());
+        let error_message = res.err().unwrap().to_string();
+        assert_eq!(error_message, r#"Duplicate file in SUMMARY.md: "./a.md""#);
+    }
+
+    #[test]
+    fn duplicate_entries_5() {
+        let src = r#"
+# Summary
+[A](./a.md)
+
+# hi
+- [B](./b.md)
+
+# bye
+
+---
+
+[A](./a.md)
+"#;
+
+        let res = parse_summary(src);
+        assert!(res.is_err());
+        let error_message = res.err().unwrap().to_string();
+        assert_eq!(error_message, r#"Duplicate file in SUMMARY.md: "./a.md""#);
+    }
 }

src/cmd/clean.rs

@@ -2,8 +2,9 @@ use super::command_prelude::*;
 use crate::get_book_dir;
 use anyhow::Context;
 use mdbook::MDBook;
-use std::fs;
+use std::mem::take;
 use std::path::PathBuf;
+use std::{fmt, fs};
 
 // Create clap subcommand arguments
 pub fn make_subcommand() -> Command {
@@ -23,10 +24,88 @@ pub fn execute(args: &ArgMatches) -> mdbook::errors::Result<()> {
         None => book.root.join(&book.config.build.build_dir),
     };
 
-    if dir_to_remove.exists() {
-        fs::remove_dir_all(&dir_to_remove)
-            .with_context(|| "Unable to remove the build directory")?;
-    }
+    let removed = Clean::new(&dir_to_remove)?;
+    println!("{removed}");
 
     Ok(())
 }
+
+/// Formats a number of bytes into a human readable SI-prefixed size.
+/// Returns a tuple of `(quantity, units)`.
+pub fn human_readable_bytes(bytes: u64) -> (f32, &'static str) {
+    static UNITS: [&str; 7] = ["B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"];
+    let bytes = bytes as f32;
+    let i = ((bytes.log2() / 10.0) as usize).min(UNITS.len() - 1);
+    (bytes / 1024_f32.powi(i as i32), UNITS[i])
+}
+
+#[derive(Debug)]
+pub struct Clean {
+    num_files_removed: u64,
+    num_dirs_removed: u64,
+    total_bytes_removed: u64,
+}
+
+impl Clean {
+    fn new(dir: &PathBuf) -> mdbook::errors::Result<Clean> {
+        let mut files = vec![dir.clone()];
+        let mut children = Vec::new();
+        let mut num_files_removed = 0;
+        let mut num_dirs_removed = 0;
+        let mut total_bytes_removed = 0;
+
+        if dir.exists() {
+            while !files.is_empty() {
+                for file in files {
+                    if let Ok(meta) = file.metadata() {
+                        // Note: This can over-count bytes removed for hard-linked
+                        // files. It also under-counts since it only counts the exact
+                        // byte sizes and not the block sizes.
+                        total_bytes_removed += meta.len();
+                    }
+                    if file.is_file() {
+                        num_files_removed += 1;
+                    } else if file.is_dir() {
+                        num_dirs_removed += 1;
+                        for entry in fs::read_dir(file)? {
+                            children.push(entry?.path());
+                        }
+                    }
+                }
+                files = take(&mut children);
+            }
+            fs::remove_dir_all(&dir).with_context(|| "Unable to remove the build directory")?;
+        }
+
+        Ok(Clean {
+            num_files_removed,
+            num_dirs_removed,
+            total_bytes_removed,
+        })
+    }
+}
+
+impl fmt::Display for Clean {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Removed ")?;
+        match (self.num_files_removed, self.num_dirs_removed) {
+            (0, 0) => write!(f, "0 files")?,
+            (0, 1) => write!(f, "1 directory")?,
+            (0, 2..) => write!(f, "{} directories", self.num_dirs_removed)?,
+            (1, _) => write!(f, "1 file")?,
+            (2.., _) => write!(f, "{} files", self.num_files_removed)?,
+        }
+
+        if self.total_bytes_removed == 0 {
+            Ok(())
+        } else {
+            // Don't show a fractional number of bytes.
+            if self.total_bytes_removed < 1024 {
+                write!(f, ", {}B total", self.total_bytes_removed)
+            } else {
+                let (bytes, unit) = human_readable_bytes(self.total_bytes_removed);
+                write!(f, ", {bytes:.2}{unit} total")
+            }
+        }
+    }
+}

src/cmd/init.rs

@@ -74,9 +74,9 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
     if let Some(author) = get_author_name() {
         debug!("Obtained user name from gitconfig: {:?}", author);
         config.book.authors.push(author);
-        builder.with_config(config);
     }
 
+    builder.with_config(config);
     builder.build()?;
     println!("\nAll done, no errors...");
 

src/config.rs

@@ -587,6 +587,9 @@ pub struct HtmlConfig {
     /// The mapping from old pages to new pages/URLs to use when generating
     /// redirects.
     pub redirect: HashMap<String, String>,
+    /// If this option is turned on, "cache bust" static files by adding
+    /// hashes to their file names.
+    pub hash_files: bool,
 }
 
 impl Default for HtmlConfig {
@@ -616,6 +619,7 @@ impl Default for HtmlConfig {
             cname: None,
             live_reload_endpoint: None,
             redirect: HashMap::new(),
+            hash_files: false,
         }
     }
 }
@@ -735,6 +739,11 @@ pub struct Search {
     /// Copy JavaScript files for the search functionality to the output directory?
     /// Default: `true`.
     pub copy_js: bool,
+    /// Specifies search settings for the given path.
+    ///
+    /// The path can be for a specific chapter, or a directory. This will
+    /// merge recursively, with more specific paths taking precedence.
+    pub chapter: HashMap<String, SearchChapterSettings>,
 }
 
 impl Default for Search {
@@ -751,10 +760,19 @@ impl Default for Search {
             expand: true,
             heading_split_level: 3,
             copy_js: true,
+            chapter: HashMap::new(),
         }
     }
 }
 
+/// Search options for chapters (or paths).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
+#[serde(default, rename_all = "kebab-case")]
+pub struct SearchChapterSettings {
+    /// Whether or not indexing is enabled, default `true`.
+    pub enable: Option<bool>,
+}
+
 /// Allows you to "update" any arbitrary field in a struct by round-tripping via
 /// a `toml::Value`.
 ///

src/front-end/css/chrome.css

@@ -421,11 +421,14 @@ ul#searchresults span.teaser em {
     color: var(--sidebar-fg);
 }
 .sidebar-iframe-inner {
+    --padding: 10px;
+
     background-color: var(--sidebar-bg);
-    color: var(--sidebar-fg);
-    padding: 10px 10px;
+    padding: var(--padding);
     margin: 0;
     font-size: 1.4rem;
+    color: var(--sidebar-fg);
+    min-height: calc(100vh - var(--padding) * 2);
 }
 .sidebar-iframe-outer {
     border: none;

src/front-end/css/general.css

@@ -200,16 +200,53 @@ sup {
     line-height: 0;
 }
 
-:not(.footnote-definition) + .footnote-definition,
-.footnote-definition + :not(.footnote-definition) {
-    margin-block-start: 2em;
-}
 .footnote-definition {
     font-size: 0.9em;
-    margin: 0.5em 0;
 }
-.footnote-definition p {
-    display: inline;
+/* The default spacing for a list is a little too large. */
+.footnote-definition ul,
+.footnote-definition ol {
+    padding-left: 20px;
+}
+.footnote-definition > li {
+    /* Required to position the ::before target */
+    position: relative;
+}
+.footnote-definition > li:target {
+    scroll-margin-top: 50vh;
+}
+.footnote-reference:target {
+    scroll-margin-top: 50vh;
+}
+/* Draws a border around the footnote (including the marker) when it is selected.
+   TODO: If there are multiple linkbacks, highlight which one you just came
+   from so you know which one to click.
+*/
+.footnote-definition > li:target::before {
+    border: 2px solid var(--footnote-highlight);
+    border-radius: 6px;
+    position: absolute;
+    top: -8px;
+    right: -8px;
+    bottom: -8px;
+    left: -32px;
+    pointer-events: none;
+    content: "";
+}
+/* Pulses the footnote reference so you can quickly see where you left off reading.
+   This could use some improvement.
+*/
+@media not (prefers-reduced-motion) {
+    .footnote-reference:target  {
+        animation: fn-highlight 0.8s;
+        border-radius: 2px;
+    }
+
+    @keyframes fn-highlight {
+        from {
+            background-color: var(--footnote-highlight);
+        }
+    }
 }
 
 .tooltiptext {

src/front-end/css/variables.css

@@ -9,7 +9,7 @@
     --content-max-width: 750px;
     --menu-bar-height: 50px;
     --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace;
-    --code-font-size: 0.875em /* please adjust the ace font size accordingly in editor.js */
+    --code-font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */
 }
 
 /* Themes */
@@ -61,6 +61,8 @@
     --copy-button-filter: invert(45%) sepia(6%) saturate(621%) hue-rotate(198deg) brightness(99%) contrast(85%);
     /* Same as `--sidebar-active` */
     --copy-button-filter-hover: invert(68%) sepia(55%) saturate(531%) hue-rotate(341deg) brightness(104%) contrast(101%);
+
+    --footnote-highlight: #2668a6;
 }
 
 .coal {
@@ -110,6 +112,8 @@
     --copy-button-filter: invert(26%) sepia(8%) saturate(575%) hue-rotate(169deg) brightness(87%) contrast(82%);
     /* Same as `--sidebar-active` */
     --copy-button-filter-hover: invert(36%) sepia(70%) saturate(503%) hue-rotate(167deg) brightness(98%) contrast(89%);
+
+    --footnote-highlight: #4079ae;
 }
 
 .light, html:not(.js) {
@@ -159,6 +163,8 @@
     --copy-button-filter: invert(45.49%);
     /* Same as `--sidebar-active` */
     --copy-button-filter-hover: invert(14%) sepia(93%) saturate(4250%) hue-rotate(243deg) brightness(99%) contrast(130%);
+
+    --footnote-highlight: #7e7eff;
 }
 
 .navy {
@@ -208,6 +214,8 @@
     --copy-button-filter: invert(51%) sepia(10%) saturate(393%) hue-rotate(198deg) brightness(86%) contrast(87%);
     /* Same as `--sidebar-active` */
     --copy-button-filter-hover: invert(46%) sepia(20%) saturate(1537%) hue-rotate(156deg) brightness(85%) contrast(90%);
+
+    --footnote-highlight: #4079ae;
 }
 
 .rust {
@@ -255,6 +263,8 @@
     --copy-button-filter: invert(51%) sepia(10%) saturate(393%) hue-rotate(198deg) brightness(86%) contrast(87%);
     /* Same as `--sidebar-active` */
     --copy-button-filter-hover: invert(77%) sepia(16%) saturate(1798%) hue-rotate(328deg) brightness(98%) contrast(83%);
+
+    --footnote-highlight: #d3a17a;
 }
 
 @media (prefers-color-scheme: dark) {

src/front-end/fonts/fonts.css

@@ -7,7 +7,7 @@
   font-style: normal;
   font-weight: 300;
   src: local('Open Sans Light'), local('OpenSans-Light'),
-       url('open-sans-v17-all-charsets-300.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-300.woff2" }}') format('woff2');
 }
 
 /* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -16,7 +16,7 @@
   font-style: italic;
   font-weight: 300;
   src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'),
-       url('open-sans-v17-all-charsets-300italic.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-300italic.woff2" }}') format('woff2');
 }
 
 /* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -25,7 +25,7 @@
   font-style: normal;
   font-weight: 400;
   src: local('Open Sans Regular'), local('OpenSans-Regular'),
-       url('open-sans-v17-all-charsets-regular.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-regular.woff2" }}') format('woff2');
 }
 
 /* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -34,7 +34,7 @@
   font-style: italic;
   font-weight: 400;
   src: local('Open Sans Italic'), local('OpenSans-Italic'),
-       url('open-sans-v17-all-charsets-italic.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-italic.woff2" }}') format('woff2');
 }
 
 /* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -43,7 +43,7 @@
   font-style: normal;
   font-weight: 600;
   src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'),
-       url('open-sans-v17-all-charsets-600.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-600.woff2" }}') format('woff2');
 }
 
 /* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -52,7 +52,7 @@
   font-style: italic;
   font-weight: 600;
   src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'),
-       url('open-sans-v17-all-charsets-600italic.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-600italic.woff2" }}') format('woff2');
 }
 
 /* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -61,7 +61,7 @@
   font-style: normal;
   font-weight: 700;
   src: local('Open Sans Bold'), local('OpenSans-Bold'),
-       url('open-sans-v17-all-charsets-700.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-700.woff2" }}') format('woff2');
 }
 
 /* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -70,7 +70,7 @@
   font-style: italic;
   font-weight: 700;
   src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'),
-       url('open-sans-v17-all-charsets-700italic.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-700italic.woff2" }}') format('woff2');
 }
 
 /* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -79,7 +79,7 @@
   font-style: normal;
   font-weight: 800;
   src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'),
-       url('open-sans-v17-all-charsets-800.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-800.woff2" }}') format('woff2');
 }
 
 /* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@@ -88,7 +88,7 @@
   font-style: italic;
   font-weight: 800;
   src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'),
-       url('open-sans-v17-all-charsets-800italic.woff2') format('woff2');
+       url('{{ resource "fonts/open-sans-v17-all-charsets-800italic.woff2" }}') format('woff2');
 }
 
 /* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */
@@ -96,5 +96,5 @@
   font-family: 'Source Code Pro';
   font-style: normal;
   font-weight: 500;
-  src: url('source-code-pro-v11-all-charsets-500.woff2') format('woff2');
+  src: url('{{ resource "fonts/source-code-pro-v11-all-charsets-500.woff2" }}') format('woff2');
 }

src/front-end/js/book.js

@@ -1,14 +1,16 @@
-"use strict";
+'use strict';
+
+/* global default_theme, default_dark_theme, default_light_theme, hljs, ClipboardJS */
 
 // Fix back button cache problem
-window.onunload = function () { };
+window.onunload = function() { };
 
 // Global variable, shared between modules
 function playground_text(playground, hidden = true) {
-    let code_block = playground.querySelector("code");
+    const code_block = playground.querySelector('code');
 
-    if (window.ace && code_block.classList.contains("editable")) {
-        let editor = window.ace.edit(code_block);
+    if (window.ace && code_block.classList.contains('editable')) {
+        const editor = window.ace.edit(code_block);
         return editor.getValue();
     } else if (hidden) {
         return code_block.textContent;
@@ -21,25 +23,25 @@ function playground_text(playground, hidden = true) {
     function fetch_with_timeout(url, options, timeout = 6000) {
         return Promise.race([
             fetch(url, options),
-            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout))
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout)),
         ]);
     }
 
-    var playgrounds = Array.from(document.querySelectorAll(".playground"));
+    const playgrounds = Array.from(document.querySelectorAll('.playground'));
     if (playgrounds.length > 0) {
-        fetch_with_timeout("https://play.rust-lang.org/meta/crates", {
+        fetch_with_timeout('https://play.rust-lang.org/meta/crates', {
             headers: {
-                'Content-Type': "application/json",
+                'Content-Type': 'application/json',
             },
             method: 'POST',
             mode: 'cors',
         })
-        .then(response => response.json())
-        .then(response => {
+            .then(response => response.json())
+            .then(response => {
             // get list of crates available in the rust playground
-            let playground_crates = response.crates.map(item => item["id"]);
-            playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
-        });
+                const playground_crates = response.crates.map(item => item['id']);
+                playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
+            });
     }
 
     function handle_crate_list_update(playground_block, playground_crates) {
@@ -48,20 +50,20 @@ function playground_text(playground, hidden = true) {
 
         // and install on change listener to dynamically update ACE editors
         if (window.ace) {
-            let code_block = playground_block.querySelector("code");
-            if (code_block.classList.contains("editable")) {
-                let editor = window.ace.edit(code_block);
-                editor.addEventListener("change", function (e) {
+            const code_block = playground_block.querySelector('code');
+            if (code_block.classList.contains('editable')) {
+                const editor = window.ace.edit(code_block);
+                editor.addEventListener('change', () => {
                     update_play_button(playground_block, playground_crates);
                 });
                 // add Ctrl-Enter command to execute rust code
                 editor.commands.addCommand({
-                    name: "run",
+                    name: 'run',
                     bindKey: {
-                        win: "Ctrl-Enter",
-                        mac: "Ctrl-Enter"
+                        win: 'Ctrl-Enter',
+                        mac: 'Ctrl-Enter',
                     },
-                    exec: _editor => run_rust_code(playground_block)
+                    exec: _editor => run_rust_code(playground_block),
                 });
             }
         }
@@ -70,37 +72,38 @@ function playground_text(playground, hidden = true) {
     // updates the visibility of play button based on `no_run` class and
     // used crates vs ones available on https://play.rust-lang.org
     function update_play_button(pre_block, playground_crates) {
-        var play_button = pre_block.querySelector(".play-button");
+        const play_button = pre_block.querySelector('.play-button');
 
         // skip if code is `no_run`
-        if (pre_block.querySelector('code').classList.contains("no_run")) {
-            play_button.classList.add("hidden");
+        if (pre_block.querySelector('code').classList.contains('no_run')) {
+            play_button.classList.add('hidden');
             return;
         }
 
         // get list of `extern crate`'s from snippet
-        var txt = playground_text(pre_block);
-        var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
-        var snippet_crates = [];
-        var item;
+        const txt = playground_text(pre_block);
+        const re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
+        const snippet_crates = [];
+        let item;
+        // eslint-disable-next-line no-cond-assign
         while (item = re.exec(txt)) {
             snippet_crates.push(item[1]);
         }
 
         // check if all used crates are available on play.rust-lang.org
-        var all_available = snippet_crates.every(function (elem) {
+        const all_available = snippet_crates.every(function(elem) {
             return playground_crates.indexOf(elem) > -1;
         });
 
         if (all_available) {
-            play_button.classList.remove("hidden");
+            play_button.classList.remove('hidden');
         } else {
-            play_button.classList.add("hidden");
+            play_button.classList.add('hidden');
         }
     }
 
     function run_rust_code(code_block) {
-        var result_block = code_block.querySelector(".result");
+        let result_block = code_block.querySelector('.result');
         if (!result_block) {
             result_block = document.createElement('code');
             result_block.className = 'result hljs language-bash';
@@ -108,93 +111,110 @@ function playground_text(playground, hidden = true) {
             code_block.append(result_block);
         }
 
-        let text = playground_text(code_block);
-        let classes = code_block.querySelector('code').classList;
-        let edition = "2015";
-        if(classes.contains("edition2018")) {
-            edition = "2018";
-        } else if(classes.contains("edition2021")) {
-            edition = "2021";
-        }
-        var params = {
-            version: "stable",
-            optimize: "0",
+        const text = playground_text(code_block);
+        const classes = code_block.querySelector('code').classList;
+        let edition = '2015';
+        classes.forEach(className => {
+            if (className.startsWith('edition')) {
+                edition = className.slice(7);
+            }
+        });
+        const params = {
+            version: 'stable',
+            optimize: '0',
             code: text,
-            edition: edition
+            edition: edition,
         };
 
-        if (text.indexOf("#![feature") !== -1) {
-            params.version = "nightly";
+        if (text.indexOf('#![feature') !== -1) {
+            params.version = 'nightly';
         }
 
-        result_block.innerText = "Running...";
+        result_block.innerText = 'Running...';
 
-        fetch_with_timeout("https://play.rust-lang.org/evaluate.json", {
+        fetch_with_timeout('https://play.rust-lang.org/evaluate.json', {
             headers: {
-                'Content-Type': "application/json",
+                'Content-Type': 'application/json',
             },
             method: 'POST',
             mode: 'cors',
-            body: JSON.stringify(params)
+            body: JSON.stringify(params),
         })
-        .then(response => response.json())
-        .then(response => {
-            if (response.result.trim() === '') {
-                result_block.innerText = "No output";
-                result_block.classList.add("result-no-output");
-            } else {
-                result_block.innerText = response.result;
-                result_block.classList.remove("result-no-output");
-            }
-        })
-        .catch(error => result_block.innerText = "Playground Communication: " + error.message);
+            .then(response => response.json())
+            .then(response => {
+                if (response.result.trim() === '') {
+                    result_block.innerText = 'No output';
+                    result_block.classList.add('result-no-output');
+                } else {
+                    result_block.innerText = response.result;
+                    result_block.classList.remove('result-no-output');
+                }
+            })
+            .catch(error => result_block.innerText = 'Playground Communication: ' + error.message);
     }
 
     // Syntax highlighting Configuration
     hljs.configure({
         tabReplace: '    ', // 4 spaces
-        languages: [],      // Languages used for auto-detection
+        languages: [], // Languages used for auto-detection
     });
 
-    let code_nodes = Array
+    const code_nodes = Array
         .from(document.querySelectorAll('code'))
         // Don't highlight `inline code` blocks in headers.
-        .filter(function (node) {return !node.parentElement.classList.contains("header"); });
+        .filter(function(node) {
+            return !node.parentElement.classList.contains('header');
+        });
 
     if (window.ace) {
         // language-rust class needs to be removed for editable
         // blocks or highlightjs will capture events
         code_nodes
-            .filter(function (node) {return node.classList.contains("editable"); })
-            .forEach(function (block) { block.classList.remove('language-rust'); });
+            .filter(function(node) {
+                return node.classList.contains('editable');
+            })
+            .forEach(function(block) {
+                block.classList.remove('language-rust');
+            });
 
         code_nodes
-            .filter(function (node) {return !node.classList.contains("editable"); })
-            .forEach(function (block) { hljs.highlightBlock(block); });
+            .filter(function(node) {
+                return !node.classList.contains('editable');
+            })
+            .forEach(function(block) {
+                hljs.highlightBlock(block);
+            });
     } else {
-        code_nodes.forEach(function (block) { hljs.highlightBlock(block); });
+        code_nodes.forEach(function(block) {
+            hljs.highlightBlock(block);
+        });
     }
 
     // Adding the hljs class gives code blocks the color css
     // even if highlighting doesn't apply
-    code_nodes.forEach(function (block) { block.classList.add('hljs'); });
+    code_nodes.forEach(function(block) {
+        block.classList.add('hljs');
+    });
 
-    Array.from(document.querySelectorAll("code.hljs")).forEach(function (block) {
+    Array.from(document.querySelectorAll('code.hljs')).forEach(function(block) {
 
-        var lines = Array.from(block.querySelectorAll('.boring'));
+        const lines = Array.from(block.querySelectorAll('.boring'));
         // If no lines were hidden, return
-        if (!lines.length) { return; }
-        block.classList.add("hide-boring");
+        if (!lines.length) {
+            return;
+        }
+        block.classList.add('hide-boring');
 
-        var buttons = document.createElement('div');
+        const buttons = document.createElement('div');
         buttons.className = 'buttons';
-        buttons.innerHTML = "<button class=\"fa fa-eye\" title=\"Show hidden lines\" aria-label=\"Show hidden lines\"></button>";
+        buttons.innerHTML = '<button class="fa fa-eye" title="Show hidden lines" \
+aria-label="Show hidden lines"></button>';
 
         // add expand button
-        var pre_block = block.parentNode;
+        const pre_block = block.parentNode;
         pre_block.insertBefore(buttons, pre_block.firstChild);
 
-        pre_block.querySelector('.buttons').addEventListener('click', function (e) {
+        pre_block.querySelector('.buttons').addEventListener('click', function(e) {
             if (e.target.classList.contains('fa-eye')) {
                 e.target.classList.remove('fa-eye');
                 e.target.classList.add('fa-eye-slash');
@@ -214,21 +234,21 @@ function playground_text(playground, hidden = true) {
     });
 
     if (window.playground_copyable) {
-        Array.from(document.querySelectorAll('pre code')).forEach(function (block) {
-            var pre_block = block.parentNode;
+        Array.from(document.querySelectorAll('pre code')).forEach(function(block) {
+            const pre_block = block.parentNode;
             if (!pre_block.classList.contains('playground')) {
-                var buttons = pre_block.querySelector(".buttons");
+                let buttons = pre_block.querySelector('.buttons');
                 if (!buttons) {
                     buttons = document.createElement('div');
                     buttons.className = 'buttons';
                     pre_block.insertBefore(buttons, pre_block.firstChild);
                 }
 
-                var clipButton = document.createElement('button');
+                const clipButton = document.createElement('button');
                 clipButton.className = 'clip-button';
                 clipButton.title = 'Copy to clipboard';
                 clipButton.setAttribute('aria-label', clipButton.title);
-                clipButton.innerHTML = '<i class=\"tooltiptext\"></i>';
+                clipButton.innerHTML = '<i class="tooltiptext"></i>';
 
                 buttons.insertBefore(clipButton, buttons.firstChild);
             }
@@ -236,28 +256,28 @@ function playground_text(playground, hidden = true) {
     }
 
     // Process playground code blocks
-    Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) {
+    Array.from(document.querySelectorAll('.playground')).forEach(function(pre_block) {
         // Add play button
-        var buttons = pre_block.querySelector(".buttons");
+        let buttons = pre_block.querySelector('.buttons');
         if (!buttons) {
             buttons = document.createElement('div');
             buttons.className = 'buttons';
             pre_block.insertBefore(buttons, pre_block.firstChild);
         }
 
-        var runCodeButton = document.createElement('button');
+        const runCodeButton = document.createElement('button');
         runCodeButton.className = 'fa fa-play play-button';
         runCodeButton.hidden = true;
         runCodeButton.title = 'Run this code';
         runCodeButton.setAttribute('aria-label', runCodeButton.title);
 
         buttons.insertBefore(runCodeButton, buttons.firstChild);
-        runCodeButton.addEventListener('click', function (e) {
+        runCodeButton.addEventListener('click', () => {
             run_rust_code(pre_block);
         });
 
         if (window.playground_copyable) {
-            var copyCodeClipboardButton = document.createElement('button');
+            const copyCodeClipboardButton = document.createElement('button');
             copyCodeClipboardButton.className = 'clip-button';
             copyCodeClipboardButton.innerHTML = '<i class="tooltiptext"></i>';
             copyCodeClipboardButton.title = 'Copy to clipboard';
@@ -266,17 +286,17 @@ function playground_text(playground, hidden = true) {
             buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
         }
 
-        let code_block = pre_block.querySelector("code");
-        if (window.ace && code_block.classList.contains("editable")) {
-            var undoChangesButton = document.createElement('button');
+        const code_block = pre_block.querySelector('code');
+        if (window.ace && code_block.classList.contains('editable')) {
+            const undoChangesButton = document.createElement('button');
             undoChangesButton.className = 'fa fa-history reset-button';
             undoChangesButton.title = 'Undo changes';
             undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
 
             buttons.insertBefore(undoChangesButton, buttons.firstChild);
 
-            undoChangesButton.addEventListener('click', function () {
-                let editor = window.ace.edit(code_block);
+            undoChangesButton.addEventListener('click', function() {
+                const editor = window.ace.edit(code_block);
                 editor.setValue(editor.originalCode);
                 editor.clearSelection();
             });
@@ -285,31 +305,37 @@ function playground_text(playground, hidden = true) {
 })();
 
 (function themes() {
-    var html = document.querySelector('html');
-    var themeToggleButton = document.getElementById('theme-toggle');
-    var themePopup = document.getElementById('theme-list');
-    var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
-    var themeIds = [];
-    themePopup.querySelectorAll('button.theme').forEach(function (el) {
+    const html = document.querySelector('html');
+    const themeToggleButton = document.getElementById('theme-toggle');
+    const themePopup = document.getElementById('theme-list');
+    const themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
+    const themeIds = [];
+    themePopup.querySelectorAll('button.theme').forEach(function(el) {
         themeIds.push(el.id);
     });
-    var stylesheets = {
-        ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"),
-        tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"),
-        highlight: document.querySelector("[href$='highlight.css']"),
+    const stylesheets = {
+        ayuHighlight: document.querySelector('#ayu-highlight-css'),
+        tomorrowNight: document.querySelector('#tomorrow-night-css'),
+        highlight: document.querySelector('#highlight-css'),
     };
 
     function showThemes() {
         themePopup.style.display = 'block';
         themeToggleButton.setAttribute('aria-expanded', true);
-        themePopup.querySelector("button#" + get_theme()).focus();
+        themePopup.querySelector('button#' + get_theme()).focus();
     }
 
     function updateThemeSelected() {
-        themePopup.querySelectorAll('.theme-selected').forEach(function (el) {
+        themePopup.querySelectorAll('.theme-selected').forEach(function(el) {
             el.classList.remove('theme-selected');
         });
-        themePopup.querySelector("button#" + get_theme()).classList.add('theme-selected');
+        const selected = get_saved_theme() ?? 'default_theme';
+        let element = themePopup.querySelector('button#' + selected);
+        if (element === null) {
+            // Fall back in case there is no "Default" item.
+            element = themePopup.querySelector('button#' + get_theme());
+        }
+        element.classList.add('theme-selected');
     }
 
     function hideThemes() {
@@ -318,64 +344,91 @@ function playground_text(playground, hidden = true) {
         themeToggleButton.focus();
     }
 
+    function get_saved_theme() {
+        let theme = null;
+        try {
+            theme = localStorage.getItem('mdbook-theme');
+        } catch (e) {
+            // ignore error.
+        }
+        return theme;
+    }
+
+    function delete_saved_theme() {
+        localStorage.removeItem('mdbook-theme');
+    }
+
     function get_theme() {
-        var theme;
-        try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { }
+        const theme = get_saved_theme();
         if (theme === null || theme === undefined || !themeIds.includes(theme)) {
-            return default_theme;
+            if (typeof default_dark_theme === 'undefined') {
+                // A customized index.hbs might not define this, so fall back to
+                // old behavior of determining the default on page load.
+                return default_theme;
+            }
+            return window.matchMedia('(prefers-color-scheme: dark)').matches
+                ? default_dark_theme
+                : default_light_theme;
         } else {
             return theme;
         }
     }
 
+    let previousTheme = default_theme;
     function set_theme(theme, store = true) {
         let ace_theme;
 
-        if (theme == 'coal' || theme == 'navy') {
+        if (theme === 'coal' || theme === 'navy') {
             stylesheets.ayuHighlight.disabled = true;
             stylesheets.tomorrowNight.disabled = false;
             stylesheets.highlight.disabled = true;
 
-            ace_theme = "ace/theme/tomorrow_night";
-        } else if (theme == 'ayu') {
+            ace_theme = 'ace/theme/tomorrow_night';
+        } else if (theme === 'ayu') {
             stylesheets.ayuHighlight.disabled = false;
             stylesheets.tomorrowNight.disabled = true;
             stylesheets.highlight.disabled = true;
-            ace_theme = "ace/theme/tomorrow_night";
+            ace_theme = 'ace/theme/tomorrow_night';
         } else {
             stylesheets.ayuHighlight.disabled = true;
             stylesheets.tomorrowNight.disabled = true;
             stylesheets.highlight.disabled = false;
-            ace_theme = "ace/theme/dawn";
+            ace_theme = 'ace/theme/dawn';
         }
 
-        setTimeout(function () {
+        setTimeout(function() {
             themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor;
         }, 1);
 
         if (window.ace && window.editors) {
-            window.editors.forEach(function (editor) {
+            window.editors.forEach(function(editor) {
                 editor.setTheme(ace_theme);
             });
         }
 
-        var previousTheme = get_theme();
-
         if (store) {
-            try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
+            try {
+                localStorage.setItem('mdbook-theme', theme);
+            } catch (e) {
+                // ignore error.
+            }
         }
 
         html.classList.remove(previousTheme);
         html.classList.add(theme);
+        previousTheme = theme;
         updateThemeSelected();
     }
 
-    // Set theme
-    var theme = get_theme();
+    const query = window.matchMedia('(prefers-color-scheme: dark)');
+    query.onchange = function() {
+        set_theme(get_theme(), false);
+    };
 
-    set_theme(theme, false);
+    // Set theme.
+    set_theme(get_theme(), false);
 
-    themeToggleButton.addEventListener('click', function () {
+    themeToggleButton.addEventListener('click', function() {
         if (themePopup.style.display === 'block') {
             hideThemes();
         } else {
@@ -383,141 +436,150 @@ function playground_text(playground, hidden = true) {
         }
     });
 
-    themePopup.addEventListener('click', function (e) {
-        var theme;
-        if (e.target.className === "theme") {
+    themePopup.addEventListener('click', function(e) {
+        let theme;
+        if (e.target.className === 'theme') {
             theme = e.target.id;
-        } else if (e.target.parentElement.className === "theme") {
+        } else if (e.target.parentElement.className === 'theme') {
             theme = e.target.parentElement.id;
         } else {
             return;
         }
-        set_theme(theme);
+        if (theme === 'default_theme' || theme === null) {
+            delete_saved_theme();
+            set_theme(get_theme(), false);
+        } else {
+            set_theme(theme);
+        }
     });
 
     themePopup.addEventListener('focusout', function(e) {
         // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
-        if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) {
+        if (!!e.relatedTarget &&
+            !themeToggleButton.contains(e.relatedTarget) &&
+            !themePopup.contains(e.relatedTarget)
+        ) {
             hideThemes();
         }
     });
 
-    // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628
+    // Should not be needed, but it works around an issue on macOS & iOS:
+    // https://github.com/rust-lang/mdBook/issues/628
     document.addEventListener('click', function(e) {
-        if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
+        if (themePopup.style.display === 'block' &&
+            !themeToggleButton.contains(e.target) &&
+            !themePopup.contains(e.target)
+        ) {
             hideThemes();
         }
     });
 
-    document.addEventListener('keydown', function (e) {
-        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
-        if (!themePopup.contains(e.target)) { return; }
+    document.addEventListener('keydown', function(e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) {
+            return;
+        }
+        if (!themePopup.contains(e.target)) {
+            return;
+        }
 
+        let li;
         switch (e.key) {
-            case 'Escape':
-                e.preventDefault();
-                hideThemes();
-                break;
-            case 'ArrowUp':
-                e.preventDefault();
-                var li = document.activeElement.parentElement;
-                if (li && li.previousElementSibling) {
-                    li.previousElementSibling.querySelector('button').focus();
-                }
-                break;
-            case 'ArrowDown':
-                e.preventDefault();
-                var li = document.activeElement.parentElement;
-                if (li && li.nextElementSibling) {
-                    li.nextElementSibling.querySelector('button').focus();
-                }
-                break;
-            case 'Home':
-                e.preventDefault();
-                themePopup.querySelector('li:first-child button').focus();
-                break;
-            case 'End':
-                e.preventDefault();
-                themePopup.querySelector('li:last-child button').focus();
-                break;
+        case 'Escape':
+            e.preventDefault();
+            hideThemes();
+            break;
+        case 'ArrowUp':
+            e.preventDefault();
+            li = document.activeElement.parentElement;
+            if (li && li.previousElementSibling) {
+                li.previousElementSibling.querySelector('button').focus();
+            }
+            break;
+        case 'ArrowDown':
+            e.preventDefault();
+            li = document.activeElement.parentElement;
+            if (li && li.nextElementSibling) {
+                li.nextElementSibling.querySelector('button').focus();
+            }
+            break;
+        case 'Home':
+            e.preventDefault();
+            themePopup.querySelector('li:first-child button').focus();
+            break;
+        case 'End':
+            e.preventDefault();
+            themePopup.querySelector('li:last-child button').focus();
+            break;
         }
     });
 })();
 
 (function sidebar() {
-    var body = document.querySelector("body");
-    var sidebar = document.getElementById("sidebar");
-    var sidebarLinks = document.querySelectorAll('#sidebar a');
-    var sidebarToggleButton = document.getElementById("sidebar-toggle");
-    var sidebarResizeHandle = document.getElementById("sidebar-resize-handle");
-    var firstContact = null;
+    const body = document.querySelector('body');
+    const sidebar = document.getElementById('sidebar');
+    const sidebarLinks = document.querySelectorAll('#sidebar a');
+    const sidebarToggleButton = document.getElementById('sidebar-toggle');
+    const sidebarToggleAnchor = document.getElementById('sidebar-toggle-anchor');
+    const sidebarResizeHandle = document.getElementById('sidebar-resize-handle');
+    let firstContact = null;
 
     function showSidebar() {
-        body.classList.remove('sidebar-hidden')
+        body.classList.remove('sidebar-hidden');
         body.classList.add('sidebar-visible');
-        Array.from(sidebarLinks).forEach(function (link) {
+        Array.from(sidebarLinks).forEach(function(link) {
             link.setAttribute('tabIndex', 0);
         });
         sidebarToggleButton.setAttribute('aria-expanded', true);
         sidebar.setAttribute('aria-hidden', false);
-        try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
+        try {
+            localStorage.setItem('mdbook-sidebar', 'visible');
+        } catch (e) {
+            // Ignore error.
+        }
     }
 
-
-    var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle');
-
-    function toggleSection(ev) {
-        ev.currentTarget.parentElement.classList.toggle('expanded');
-    }
-
-    Array.from(sidebarAnchorToggles).forEach(function (el) {
-        el.addEventListener('click', toggleSection);
-    });
-
     function hideSidebar() {
-        body.classList.remove('sidebar-visible')
+        body.classList.remove('sidebar-visible');
         body.classList.add('sidebar-hidden');
-        Array.from(sidebarLinks).forEach(function (link) {
+        Array.from(sidebarLinks).forEach(function(link) {
             link.setAttribute('tabIndex', -1);
         });
         sidebarToggleButton.setAttribute('aria-expanded', false);
         sidebar.setAttribute('aria-hidden', true);
-        try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
+        try {
+            localStorage.setItem('mdbook-sidebar', 'hidden');
+        } catch (e) {
+            // Ignore error.
+        }
     }
 
     // Toggle sidebar
-    sidebarToggleButton.addEventListener('click', function sidebarToggle() {
-        if (body.classList.contains("sidebar-hidden")) {
-            var current_width = parseInt(
+    sidebarToggleAnchor.addEventListener('change', function sidebarToggle() {
+        if (sidebarToggleAnchor.checked) {
+            const current_width = parseInt(
                 document.documentElement.style.getPropertyValue('--sidebar-width'), 10);
             if (current_width < 150) {
                 document.documentElement.style.setProperty('--sidebar-width', '150px');
             }
             showSidebar();
-        } else if (body.classList.contains("sidebar-visible")) {
-            hideSidebar();
         } else {
-            if (getComputedStyle(sidebar)['transform'] === 'none') {
-                hideSidebar();
-            } else {
-                showSidebar();
-            }
+            hideSidebar();
         }
     });
 
     sidebarResizeHandle.addEventListener('mousedown', initResize, false);
 
-    function initResize(e) {
+    function initResize() {
         window.addEventListener('mousemove', resize, false);
         window.addEventListener('mouseup', stopResize, false);
         body.classList.add('sidebar-resizing');
     }
     function resize(e) {
-        var pos = (e.clientX - sidebar.offsetLeft);
+        let pos = e.clientX - sidebar.offsetLeft;
         if (pos < 20) {
             hideSidebar();
         } else {
-            if (body.classList.contains("sidebar-hidden")) {
+            if (body.classList.contains('sidebar-hidden')) {
                 showSidebar();
             }
             pos = Math.min(pos, window.innerWidth - 100);
@@ -525,32 +587,34 @@ function playground_text(playground, hidden = true) {
         }
     }
     //on mouseup remove windows functions mousemove & mouseup
-    function stopResize(e) {
+    function stopResize() {
         body.classList.remove('sidebar-resizing');
         window.removeEventListener('mousemove', resize, false);
         window.removeEventListener('mouseup', stopResize, false);
     }
 
-    document.addEventListener('touchstart', function (e) {
+    document.addEventListener('touchstart', function(e) {
         firstContact = {
             x: e.touches[0].clientX,
-            time: Date.now()
+            time: Date.now(),
         };
     }, { passive: true });
 
-    document.addEventListener('touchmove', function (e) {
-        if (!firstContact)
+    document.addEventListener('touchmove', function(e) {
+        if (!firstContact) {
             return;
+        }
 
-        var curX = e.touches[0].clientX;
-        var xDiff = curX - firstContact.x,
+        const curX = e.touches[0].clientX;
+        const xDiff = curX - firstContact.x,
             tDiff = Date.now() - firstContact.time;
 
         if (tDiff < 250 && Math.abs(xDiff) >= 150) {
-            if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
+            if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300)) {
                 showSidebar();
-            else if (xDiff < 0 && curX < 300)
+            } else if (xDiff < 0 && curX < 300) {
                 hideSidebar();
+            }
 
             firstContact = null;
         }
@@ -558,49 +622,53 @@ function playground_text(playground, hidden = true) {
 })();
 
 (function chapterNavigation() {
-    document.addEventListener('keydown', function (e) {
-        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
-        if (window.search && window.search.hasFocus()) { return; }
-        var html = document.querySelector('html');
+    document.addEventListener('keydown', function(e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) {
+            return;
+        }
+        if (window.search && window.search.hasFocus()) {
+            return;
+        }
+        const html = document.querySelector('html');
 
         function next() {
-            var nextButton = document.querySelector('.nav-chapters.next');
+            const nextButton = document.querySelector('.nav-chapters.next');
             if (nextButton) {
                 window.location.href = nextButton.href;
             }
         }
         function prev() {
-            var previousButton = document.querySelector('.nav-chapters.previous');
+            const previousButton = document.querySelector('.nav-chapters.previous');
             if (previousButton) {
                 window.location.href = previousButton.href;
             }
         }
         switch (e.key) {
-            case 'ArrowRight':
-                e.preventDefault();
-                if (html.dir == 'rtl') {
-                    prev();
-                } else {
-                    next();
-                }
-                break;
-            case 'ArrowLeft':
-                e.preventDefault();
-                if (html.dir == 'rtl') {
-                    next();
-                } else {
-                    prev();
-                }
-                break;
+        case 'ArrowRight':
+            e.preventDefault();
+            if (html.dir === 'rtl') {
+                prev();
+            } else {
+                next();
+            }
+            break;
+        case 'ArrowLeft':
+            e.preventDefault();
+            if (html.dir === 'rtl') {
+                next();
+            } else {
+                prev();
+            }
+            break;
         }
     });
 })();
 
 (function clipboard() {
-    var clipButtons = document.querySelectorAll('.clip-button');
+    const clipButtons = document.querySelectorAll('.clip-button');
 
     function hideTooltip(elem) {
-        elem.firstChild.innerText = "";
+        elem.firstChild.innerText = '';
         elem.className = 'clip-button';
     }
 
@@ -609,58 +677,58 @@ function playground_text(playground, hidden = true) {
         elem.className = 'clip-button tooltipped';
     }
 
-    var clipboardSnippets = new ClipboardJS('.clip-button', {
-        text: function (trigger) {
+    const clipboardSnippets = new ClipboardJS('.clip-button', {
+        text: function(trigger) {
             hideTooltip(trigger);
-            let playground = trigger.closest("pre");
+            const playground = trigger.closest('pre');
             return playground_text(playground, false);
-        }
+        },
     });
 
-    Array.from(clipButtons).forEach(function (clipButton) {
-        clipButton.addEventListener('mouseout', function (e) {
+    Array.from(clipButtons).forEach(function(clipButton) {
+        clipButton.addEventListener('mouseout', function(e) {
             hideTooltip(e.currentTarget);
         });
     });
 
-    clipboardSnippets.on('success', function (e) {
+    clipboardSnippets.on('success', function(e) {
         e.clearSelection();
-        showTooltip(e.trigger, "Copied!");
+        showTooltip(e.trigger, 'Copied!');
     });
 
-    clipboardSnippets.on('error', function (e) {
-        showTooltip(e.trigger, "Clipboard error!");
+    clipboardSnippets.on('error', function(e) {
+        showTooltip(e.trigger, 'Clipboard error!');
     });
 })();
 
-(function scrollToTop () {
-    var menuTitle = document.querySelector('.menu-title');
+(function scrollToTop() {
+    const menuTitle = document.querySelector('.menu-title');
 
-    menuTitle.addEventListener('click', function () {
+    menuTitle.addEventListener('click', function() {
         document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
     });
 })();
 
 (function controllMenu() {
-    var menu = document.getElementById('menu-bar');
+    const menu = document.getElementById('menu-bar');
 
     (function controllPosition() {
-        var scrollTop = document.scrollingElement.scrollTop;
-        var prevScrollTop = scrollTop;
-        var minMenuY = -menu.clientHeight - 50;
+        let scrollTop = document.scrollingElement.scrollTop;
+        let prevScrollTop = scrollTop;
+        const minMenuY = -menu.clientHeight - 50;
         // When the script loads, the page can be at any scroll (e.g. if you reforesh it).
         menu.style.top = scrollTop + 'px';
         // Same as parseInt(menu.style.top.slice(0, -2), but faster
-        var topCache = menu.style.top.slice(0, -2);
+        let topCache = menu.style.top.slice(0, -2);
         menu.classList.remove('sticky');
-        var stickyCache = false; // Same as menu.classList.contains('sticky'), but faster
-        document.addEventListener('scroll', function () {
+        let stickyCache = false; // Same as menu.classList.contains('sticky'), but faster
+        document.addEventListener('scroll', function() {
             scrollTop = Math.max(document.scrollingElement.scrollTop, 0);
             // `null` means that it doesn't need to be updated
-            var nextSticky = null;
-            var nextTop = null;
-            var scrollDown = scrollTop > prevScrollTop;
-            var menuPosAbsoluteY = topCache - scrollTop;
+            let nextSticky = null;
+            let nextTop = null;
+            const scrollDown = scrollTop > prevScrollTop;
+            const menuPosAbsoluteY = topCache - scrollTop;
             if (scrollDown) {
                 nextSticky = false;
                 if (menuPosAbsoluteY > 0) {

src/front-end/mod.rs

@@ -13,32 +13,31 @@ use std::path::{Path, PathBuf};
 
 use crate::errors::*;
 use log::warn;
-pub static INDEX: &[u8] = include_bytes!("index.hbs");
-pub static HEAD: &[u8] = include_bytes!("head.hbs");
-pub static REDIRECT: &[u8] = include_bytes!("redirect.hbs");
-pub static HEADER: &[u8] = include_bytes!("header.hbs");
-pub static TOC_JS: &[u8] = include_bytes!("toc.js.hbs");
-pub static TOC_HTML: &[u8] = include_bytes!("toc.html.hbs");
+pub static INDEX: &[u8] = include_bytes!("templates/index.hbs");
+pub static HEAD: &[u8] = include_bytes!("templates/head.hbs");
+pub static REDIRECT: &[u8] = include_bytes!("templates/redirect.hbs");
+pub static HEADER: &[u8] = include_bytes!("templates/header.hbs");
+pub static TOC_JS: &[u8] = include_bytes!("templates/toc.js.hbs");
+pub static TOC_HTML: &[u8] = include_bytes!("templates/toc.html.hbs");
 pub static CHROME_CSS: &[u8] = include_bytes!("css/chrome.css");
 pub static GENERAL_CSS: &[u8] = include_bytes!("css/general.css");
 pub static PRINT_CSS: &[u8] = include_bytes!("css/print.css");
 pub static VARIABLES_CSS: &[u8] = include_bytes!("css/variables.css");
-pub static FAVICON_PNG: &[u8] = include_bytes!("favicon.png");
-pub static FAVICON_SVG: &[u8] = include_bytes!("favicon.svg");
-pub static JS: &[u8] = include_bytes!("book.js");
-pub static HIGHLIGHT_JS: &[u8] = include_bytes!("highlight.js");
-pub static TOMORROW_NIGHT_CSS: &[u8] = include_bytes!("tomorrow-night.css");
-pub static HIGHLIGHT_CSS: &[u8] = include_bytes!("highlight.css");
-pub static AYU_HIGHLIGHT_CSS: &[u8] = include_bytes!("ayu-highlight.css");
-pub static CLIPBOARD_JS: &[u8] = include_bytes!("clipboard.min.js");
-pub static FONT_AWESOME: &[u8] = include_bytes!("FontAwesome/css/font-awesome.min.css");
-pub static FONT_AWESOME_EOT: &[u8] = include_bytes!("FontAwesome/fonts/fontawesome-webfont.eot");
-pub static FONT_AWESOME_SVG: &[u8] = include_bytes!("FontAwesome/fonts/fontawesome-webfont.svg");
-pub static FONT_AWESOME_TTF: &[u8] = include_bytes!("FontAwesome/fonts/fontawesome-webfont.ttf");
-pub static FONT_AWESOME_WOFF: &[u8] = include_bytes!("FontAwesome/fonts/fontawesome-webfont.woff");
-pub static FONT_AWESOME_WOFF2: &[u8] =
-    include_bytes!("FontAwesome/fonts/fontawesome-webfont.woff2");
-pub static FONT_AWESOME_OTF: &[u8] = include_bytes!("FontAwesome/fonts/FontAwesome.otf");
+pub static FAVICON_PNG: &[u8] = include_bytes!("images/favicon.png");
+pub static FAVICON_SVG: &[u8] = include_bytes!("images/favicon.svg");
+pub static JS: &[u8] = include_bytes!("js/book.js");
+pub static HIGHLIGHT_JS: &[u8] = include_bytes!("js/highlight.js");
+pub static TOMORROW_NIGHT_CSS: &[u8] = include_bytes!("css/tomorrow-night.css");
+pub static HIGHLIGHT_CSS: &[u8] = include_bytes!("css/highlight.css");
+pub static AYU_HIGHLIGHT_CSS: &[u8] = include_bytes!("css/ayu-highlight.css");
+pub static CLIPBOARD_JS: &[u8] = include_bytes!("js/clipboard.min.js");
+pub static FONT_AWESOME: &[u8] = include_bytes!("css/font-awesome.min.css");
+pub static FONT_AWESOME_EOT: &[u8] = include_bytes!("fonts/fontawesome-webfont.eot");
+pub static FONT_AWESOME_SVG: &[u8] = include_bytes!("fonts/fontawesome-webfont.svg");
+pub static FONT_AWESOME_TTF: &[u8] = include_bytes!("fonts/fontawesome-webfont.ttf");
+pub static FONT_AWESOME_WOFF: &[u8] = include_bytes!("fonts/fontawesome-webfont.woff");
+pub static FONT_AWESOME_WOFF2: &[u8] = include_bytes!("fonts/fontawesome-webfont.woff2");
+pub static FONT_AWESOME_OTF: &[u8] = include_bytes!("fonts/FontAwesome.otf");
 
 /// The `Theme` struct should be used instead of the static variables because
 /// the `new()` method will look if the user has a theme directory in their

src/front-end/searcher/searcher.js

@@ -1,4 +1,7 @@
-"use strict";
+'use strict';
+
+/* global Mark, elasticlunr, path_to_root */
+
 window.search = window.search || {};
 (function search(search) {
     // Search functionality
@@ -10,43 +13,26 @@ window.search = window.search || {};
         return;
     }
 
-    //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+    // eslint-disable-next-line max-len
+    // IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
     if (!String.prototype.startsWith) {
         String.prototype.startsWith = function(search, pos) {
             return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
         };
     }
 
-    var search_wrap = document.getElementById('search-wrapper'),
+    const search_wrap = document.getElementById('search-wrapper'),
         searchbar = document.getElementById('searchbar'),
-        searchbar_outer = document.getElementById('searchbar-outer'),
         searchresults = document.getElementById('searchresults'),
         searchresults_outer = document.getElementById('searchresults-outer'),
         searchresults_header = document.getElementById('searchresults-header'),
         searchicon = document.getElementById('search-toggle'),
         content = document.getElementById('content'),
 
-        searchindex = null,
-        doc_urls = [],
-        results_options = {
-            teaser_word_count: 30,
-            limit_results: 30,
-        },
-        search_options = {
-            bool: "AND",
-            expand: true,
-            fields: {
-                title: {boost: 1},
-                body: {boost: 1},
-                breadcrumbs: {boost: 0}
-            }
-        },
         mark_exclude = [],
         marker = new Mark(content),
-        current_searchterm = "",
         URL_SEARCH_PARAM = 'search',
         URL_MARK_PARAM = 'highlight',
-        teaser_count = 0,
 
         SEARCH_HOTKEY_KEYCODE = 83,
         ESCAPE_KEYCODE = 27,
@@ -54,6 +40,24 @@ window.search = window.search || {};
         UP_KEYCODE = 38,
         SELECT_KEYCODE = 13;
 
+    let current_searchterm = '',
+        doc_urls = [],
+        search_options = {
+            bool: 'AND',
+            expand: true,
+            fields: {
+                title: {boost: 1},
+                body: {boost: 1},
+                breadcrumbs: {boost: 0},
+            },
+        },
+        searchindex = null,
+        results_options = {
+            teaser_word_count: 30,
+            limit_results: 30,
+        },
+        teaser_count = 0;
+
     function hasFocus() {
         return searchbar === document.activeElement;
     }
@@ -66,96 +70,99 @@ window.search = window.search || {};
 
     // Helper to parse a url into its building blocks.
     function parseURL(url) {
-        var a =  document.createElement('a');
+        const a = document.createElement('a');
         a.href = url;
         return {
             source: url,
-            protocol: a.protocol.replace(':',''),
+            protocol: a.protocol.replace(':', ''),
             host: a.hostname,
             port: a.port,
-            params: (function(){
-                var ret = {};
-                var seg = a.search.replace(/^\?/,'').split('&');
-                var len = seg.length, i = 0, s;
-                for (;i<len;i++) {
-                    if (!seg[i]) { continue; }
-                    s = seg[i].split('=');
+            params: (function() {
+                const ret = {};
+                const seg = a.search.replace(/^\?/, '').split('&');
+                for (const part of seg) {
+                    if (!part) {
+                        continue;
+                    }
+                    const s = part.split('=');
                     ret[s[0]] = s[1];
                 }
                 return ret;
             })(),
-            file: (a.pathname.match(/\/([^/?#]+)$/i) || [,''])[1],
-            hash: a.hash.replace('#',''),
-            path: a.pathname.replace(/^([^/])/,'/$1')
+            file: (a.pathname.match(/\/([^/?#]+)$/i) || ['', ''])[1],
+            hash: a.hash.replace('#', ''),
+            path: a.pathname.replace(/^([^/])/, '/$1'),
         };
     }
-    
+
     // Helper to recreate a url string from its building blocks.
     function renderURL(urlobject) {
-        var url = urlobject.protocol + "://" + urlobject.host;
-        if (urlobject.port != "") {
-            url += ":" + urlobject.port;
+        let url = urlobject.protocol + '://' + urlobject.host;
+        if (urlobject.port !== '') {
+            url += ':' + urlobject.port;
         }
         url += urlobject.path;
-        var joiner = "?";
-        for(var prop in urlobject.params) {
-            if(urlobject.params.hasOwnProperty(prop)) {
-                url += joiner + prop + "=" + urlobject.params[prop];
-                joiner = "&";
+        let joiner = '?';
+        for (const prop in urlobject.params) {
+            if (Object.prototype.hasOwnProperty.call(urlobject.params, prop)) {
+                url += joiner + prop + '=' + urlobject.params[prop];
+                joiner = '&';
             }
         }
-        if (urlobject.hash != "") {
-            url += "#" + urlobject.hash;
+        if (urlobject.hash !== '') {
+            url += '#' + urlobject.hash;
         }
         return url;
     }
-    
+
     // Helper to escape html special chars for displaying the teasers
-    var escapeHTML = (function() {
-        var MAP = {
+    const escapeHTML = (function() {
+        const MAP = {
             '&': '&amp;',
             '<': '&lt;',
             '>': '&gt;',
             '"': '&#34;',
-            "'": '&#39;'
+            '\'': '&#39;',
+        };
+        const repl = function(c) {
+            return MAP[c];
         };
-        var repl = function(c) { return MAP[c]; };
         return function(s) {
             return s.replace(/[&<>'"]/g, repl);
         };
     })();
-    
+
     function formatSearchMetric(count, searchterm) {
-        if (count == 1) {
-            return count + " search result for '" + searchterm + "':";
-        } else if (count == 0) {
-            return "No search results for '" + searchterm + "'.";
+        if (count === 1) {
+            return count + ' search result for \'' + searchterm + '\':';
+        } else if (count === 0) {
+            return 'No search results for \'' + searchterm + '\'.';
         } else {
-            return count + " search results for '" + searchterm + "':";
+            return count + ' search results for \'' + searchterm + '\':';
         }
     }
-    
+
     function formatSearchResult(result, searchterms) {
-        var teaser = makeTeaser(escapeHTML(result.doc.body), searchterms);
+        const teaser = makeTeaser(escapeHTML(result.doc.body), searchterms);
         teaser_count++;
 
         // The ?URL_MARK_PARAM= parameter belongs inbetween the page and the #heading-anchor
-        var url = doc_urls[result.ref].split("#");
-        if (url.length == 1) { // no anchor found
-            url.push("");
+        const url = doc_urls[result.ref].split('#');
+        if (url.length === 1) { // no anchor found
+            url.push('');
         }
 
         // encodeURIComponent escapes all chars that could allow an XSS except
         // for '. Due to that we also manually replace ' with its url-encoded
         // representation (%27).
-        var searchterms = encodeURIComponent(searchterms.join(" ")).replace(/\'/g, "%27");
+        const encoded_search = encodeURIComponent(searchterms.join(' ')).replace(/'/g, '%27');
 
-        return '<a href="' + path_to_root + url[0] + '?' + URL_MARK_PARAM + '=' + searchterms + '#' + url[1]
-            + '" aria-details="teaser_' + teaser_count + '">' + result.doc.breadcrumbs + '</a>'
-            + '<span class="teaser" id="teaser_' + teaser_count + '" aria-label="Search Result Teaser">' 
-            + teaser + '</span>';
+        return '<a href="' + path_to_root + url[0] + '?' + URL_MARK_PARAM + '=' + encoded_search
+            + '#' + url[1] + '" aria-details="teaser_' + teaser_count + '">'
+            + result.doc.breadcrumbs + '</a>' + '<span class="teaser" id="teaser_' + teaser_count
+            + '" aria-label="Search Result Teaser">' + teaser + '</span>';
     }
-    
+
     function makeTeaser(body, searchterms) {
         // The strategy is as follows:
         // First, assign a value to each word in the document:
@@ -166,88 +173,90 @@ window.search = window.search || {};
         // sum of the values of the words within the window. Then use the window that got the
         // maximum sum. If there are multiple maximas, then get the last one.
         // Enclose the terms in <em>.
-        var stemmed_searchterms = searchterms.map(function(w) {
+        const stemmed_searchterms = searchterms.map(function(w) {
             return elasticlunr.stemmer(w.toLowerCase());
         });
-        var searchterm_weight = 40;
-        var weighted = []; // contains elements of ["word", weight, index_in_document]
+        const searchterm_weight = 40;
+        const weighted = []; // contains elements of ["word", weight, index_in_document]
         // split in sentences, then words
-        var sentences = body.toLowerCase().split('. ');
-        var index = 0;
-        var value = 0;
-        var searchterm_found = false;
-        for (var sentenceindex in sentences) {
-            var words = sentences[sentenceindex].split(' ');
+        const sentences = body.toLowerCase().split('. ');
+        let index = 0;
+        let value = 0;
+        let searchterm_found = false;
+        for (const sentenceindex in sentences) {
+            const words = sentences[sentenceindex].split(' ');
             value = 8;
-            for (var wordindex in words) {
-                var word = words[wordindex];
+            for (const wordindex in words) {
+                const word = words[wordindex];
                 if (word.length > 0) {
-                    for (var searchtermindex in stemmed_searchterms) {
-                        if (elasticlunr.stemmer(word).startsWith(stemmed_searchterms[searchtermindex])) {
+                    for (const searchtermindex in stemmed_searchterms) {
+                        if (elasticlunr.stemmer(word).startsWith(
+                            stemmed_searchterms[searchtermindex])
+                        ) {
                             value = searchterm_weight;
                             searchterm_found = true;
                         }
-                    };
+                    }
                     weighted.push([word, value, index]);
                     value = 2;
                 }
                 index += word.length;
                 index += 1; // ' ' or '.' if last word in sentence
-            };
+            }
             index += 1; // because we split at a two-char boundary '. '
-        };
+        }
 
-        if (weighted.length == 0) {
+        if (weighted.length === 0) {
             return body;
         }
 
-        var window_weight = [];
-        var window_size = Math.min(weighted.length, results_options.teaser_word_count);
+        const window_weight = [];
+        const window_size = Math.min(weighted.length, results_options.teaser_word_count);
 
-        var cur_sum = 0;
-        for (var wordindex = 0; wordindex < window_size; wordindex++) {
+        let cur_sum = 0;
+        for (let wordindex = 0; wordindex < window_size; wordindex++) {
             cur_sum += weighted[wordindex][1];
-        };
+        }
         window_weight.push(cur_sum);
-        for (var wordindex = 0; wordindex < weighted.length - window_size; wordindex++) {
+        for (let wordindex = 0; wordindex < weighted.length - window_size; wordindex++) {
             cur_sum -= weighted[wordindex][1];
             cur_sum += weighted[wordindex + window_size][1];
             window_weight.push(cur_sum);
-        };
+        }
 
+        let max_sum_window_index = 0;
         if (searchterm_found) {
-            var max_sum = 0;
-            var max_sum_window_index = 0;
+            let max_sum = 0;
             // backwards
-            for (var i = window_weight.length - 1; i >= 0; i--) {
+            for (let i = window_weight.length - 1; i >= 0; i--) {
                 if (window_weight[i] > max_sum) {
                     max_sum = window_weight[i];
                     max_sum_window_index = i;
                 }
-            };
+            }
         } else {
             max_sum_window_index = 0;
         }
 
         // add <em/> around searchterms
-        var teaser_split = [];
-        var index = weighted[max_sum_window_index][2];
-        for (var i = max_sum_window_index; i < max_sum_window_index+window_size; i++) {
-            var word = weighted[i];
+        const teaser_split = [];
+        index = weighted[max_sum_window_index][2];
+        for (let i = max_sum_window_index; i < max_sum_window_index + window_size; i++) {
+            const word = weighted[i];
             if (index < word[2]) {
                 // missing text from index to start of `word`
                 teaser_split.push(body.substring(index, word[2]));
                 index = word[2];
             }
-            if (word[1] == searchterm_weight) {
-                teaser_split.push("<em>")
+            if (word[1] === searchterm_weight) {
+                teaser_split.push('<em>');
             }
             index = word[2] + word[0].length;
             teaser_split.push(body.substring(word[2], index));
-            if (word[1] == searchterm_weight) {
-                teaser_split.push("</em>")
+            if (word[1] === searchterm_weight) {
+                teaser_split.push('</em>');
             }
-        };
+        }
 
         return teaser_split.join('');
     }
@@ -255,74 +264,95 @@ window.search = window.search || {};
     function init(config) {
         results_options = config.results_options;
         search_options = config.search_options;
-        searchbar_outer = config.searchbar_outer;
         doc_urls = config.doc_urls;
         searchindex = elasticlunr.Index.load(config.index);
 
         // Set up events
-        searchicon.addEventListener('click', function(e) { searchIconClickHandler(); }, false);
-        searchbar.addEventListener('keyup', function(e) { searchbarKeyUpHandler(); }, false);
-        document.addEventListener('keydown', function(e) { globalKeyHandler(e); }, false);
+        searchicon.addEventListener('click', () => {
+            searchIconClickHandler();
+        }, false);
+        searchbar.addEventListener('keyup', () => {
+            searchbarKeyUpHandler();
+        }, false);
+        document.addEventListener('keydown', e => {
+            globalKeyHandler(e);
+        }, false);
         // If the user uses the browser buttons, do the same as if a reload happened
-        window.onpopstate = function(e) { doSearchOrMarkFromUrl(); };
+        window.onpopstate = () => {
+            doSearchOrMarkFromUrl();
+        };
         // Suppress "submit" events so the page doesn't reload when the user presses Enter
-        document.addEventListener('submit', function(e) { e.preventDefault(); }, false);
+        document.addEventListener('submit', e => {
+            e.preventDefault();
+        }, false);
 
         // If reloaded, do the search or mark again, depending on the current url parameters
         doSearchOrMarkFromUrl();
     }
-    
+
     function unfocusSearchbar() {
         // hacky, but just focusing a div only works once
-        var tmp = document.createElement('input');
+        const tmp = document.createElement('input');
         tmp.setAttribute('style', 'position: absolute; opacity: 0;');
         searchicon.appendChild(tmp);
         tmp.focus();
         tmp.remove();
     }
-    
+
     // On reload or browser history backwards/forwards events, parse the url and do search or mark
     function doSearchOrMarkFromUrl() {
         // Check current URL for search request
-        var url = parseURL(window.location.href);
-        if (url.params.hasOwnProperty(URL_SEARCH_PARAM)
-            && url.params[URL_SEARCH_PARAM] != "") {
+        const url = parseURL(window.location.href);
+        if (Object.prototype.hasOwnProperty.call(url.params, URL_SEARCH_PARAM)
+            && url.params[URL_SEARCH_PARAM] !== '') {
             showSearch(true);
             searchbar.value = decodeURIComponent(
-                (url.params[URL_SEARCH_PARAM]+'').replace(/\+/g, '%20'));
+                (url.params[URL_SEARCH_PARAM] + '').replace(/\+/g, '%20'));
             searchbarKeyUpHandler(); // -> doSearch()
         } else {
             showSearch(false);
         }
 
-        if (url.params.hasOwnProperty(URL_MARK_PARAM)) {
-            var words = decodeURIComponent(url.params[URL_MARK_PARAM]).split(' ');
+        if (Object.prototype.hasOwnProperty.call(url.params, URL_MARK_PARAM)) {
+            const words = decodeURIComponent(url.params[URL_MARK_PARAM]).split(' ');
             marker.mark(words, {
-                exclude: mark_exclude
+                exclude: mark_exclude,
             });
 
-            var markers = document.querySelectorAll("mark");
-            function hide() {
-                for (var i = 0; i < markers.length; i++) {
-                    markers[i].classList.add("fade-out");
-                    window.setTimeout(function(e) { marker.unmark(); }, 300);
+            const markers = document.querySelectorAll('mark');
+            const hide = () => {
+                for (let i = 0; i < markers.length; i++) {
+                    markers[i].classList.add('fade-out');
+                    window.setTimeout(() => {
+                        marker.unmark();
+                    }, 300);
                 }
-            }
-            for (var i = 0; i < markers.length; i++) {
+            };
+
+            for (let i = 0; i < markers.length; i++) {
                 markers[i].addEventListener('click', hide);
             }
         }
     }
-    
+
     // Eventhandler for keyevents on `document`
     function globalKeyHandler(e) {
-        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey || e.target.type === 'textarea' || e.target.type === 'text' || !hasFocus() && /^(?:input|select|textarea)$/i.test(e.target.nodeName)) { return; }
+        if (e.altKey ||
+            e.ctrlKey ||
+            e.metaKey ||
+            e.shiftKey ||
+            e.target.type === 'textarea' ||
+            e.target.type === 'text' ||
+            !hasFocus() && /^(?:input|select|textarea)$/i.test(e.target.nodeName)
+        ) {
+            return;
+        }
 
         if (e.keyCode === ESCAPE_KEYCODE) {
             e.preventDefault();
-            searchbar.classList.remove("active");
-            setSearchUrlParameters("",
-                (searchbar.value.trim() !== "") ? "push" : "replace");
+            searchbar.classList.remove('active');
+            setSearchUrlParameters('',
+                searchbar.value.trim() !== '' ? 'push' : 'replace');
             if (hasFocus()) {
                 unfocusSearchbar();
             }
@@ -336,25 +366,27 @@ window.search = window.search || {};
         } else if (hasFocus() && e.keyCode === DOWN_KEYCODE) {
             e.preventDefault();
             unfocusSearchbar();
-            searchresults.firstElementChild.classList.add("focus");
+            searchresults.firstElementChild.classList.add('focus');
         } else if (!hasFocus() && (e.keyCode === DOWN_KEYCODE
                                 || e.keyCode === UP_KEYCODE
                                 || e.keyCode === SELECT_KEYCODE)) {
             // not `:focus` because browser does annoying scrolling
-            var focused = searchresults.querySelector("li.focus");
-            if (!focused) return;
+            const focused = searchresults.querySelector('li.focus');
+            if (!focused) {
+                return;
+            }
             e.preventDefault();
             if (e.keyCode === DOWN_KEYCODE) {
-                var next = focused.nextElementSibling;
+                const next = focused.nextElementSibling;
                 if (next) {
-                    focused.classList.remove("focus");
-                    next.classList.add("focus");
+                    focused.classList.remove('focus');
+                    next.classList.add('focus');
                 }
             } else if (e.keyCode === UP_KEYCODE) {
-                focused.classList.remove("focus");
-                var prev = focused.previousElementSibling;
+                focused.classList.remove('focus');
+                const prev = focused.previousElementSibling;
                 if (prev) {
-                    prev.classList.add("focus");
+                    prev.classList.add('focus');
                 } else {
                     searchbar.select();
                 }
@@ -363,7 +395,7 @@ window.search = window.search || {};
             }
         }
     }
-    
+
     function showSearch(yes) {
         if (yes) {
             search_wrap.classList.remove('hidden');
@@ -371,9 +403,9 @@ window.search = window.search || {};
         } else {
             search_wrap.classList.add('hidden');
             searchicon.setAttribute('aria-expanded', 'false');
-            var results = searchresults.children;
-            for (var i = 0; i < results.length; i++) {
-                results[i].classList.remove("focus");
+            const results = searchresults.children;
+            for (let i = 0; i < results.length; i++) {
+                results[i].classList.remove('focus');
             }
         }
     }
@@ -396,36 +428,37 @@ window.search = window.search || {};
             showSearch(false);
         }
     }
-    
+
     // Eventhandler for keyevents while the searchbar is focused
     function searchbarKeyUpHandler() {
-        var searchterm = searchbar.value.trim();
-        if (searchterm != "") {
-            searchbar.classList.add("active");
+        const searchterm = searchbar.value.trim();
+        if (searchterm !== '') {
+            searchbar.classList.add('active');
             doSearch(searchterm);
         } else {
-            searchbar.classList.remove("active");
+            searchbar.classList.remove('active');
             showResults(false);
             removeChildren(searchresults);
         }
 
-        setSearchUrlParameters(searchterm, "push_if_new_search_else_replace");
+        setSearchUrlParameters(searchterm, 'push_if_new_search_else_replace');
 
         // Remove marks
         marker.unmark();
     }
-    
-    // Update current url with ?URL_SEARCH_PARAM= parameter, remove ?URL_MARK_PARAM and #heading-anchor .
-    // `action` can be one of "push", "replace", "push_if_new_search_else_replace"
-    // and replaces or pushes a new browser history item.
+
+    // Update current url with ?URL_SEARCH_PARAM= parameter, remove ?URL_MARK_PARAM and
+    // `#heading-anchor`. `action` can be one of "push", "replace",
+    // "push_if_new_search_else_replace" and replaces or pushes a new browser history item.
     // "push_if_new_search_else_replace" pushes if there is no `?URL_SEARCH_PARAM=abc` yet.
     function setSearchUrlParameters(searchterm, action) {
-        var url = parseURL(window.location.href);
-        var first_search = ! url.params.hasOwnProperty(URL_SEARCH_PARAM);
-        if (searchterm != "" || action == "push_if_new_search_else_replace") {
+        const url = parseURL(window.location.href);
+        const first_search = !Object.prototype.hasOwnProperty.call(url.params, URL_SEARCH_PARAM);
+
+        if (searchterm !== '' || action === 'push_if_new_search_else_replace') {
             url.params[URL_SEARCH_PARAM] = searchterm;
             delete url.params[URL_MARK_PARAM];
-            url.hash = "";
+            url.hash = '';
         } else {
             delete url.params[URL_MARK_PARAM];
             delete url.params[URL_SEARCH_PARAM];
@@ -433,33 +466,40 @@ window.search = window.search || {};
         // A new search will also add a new history item, so the user can go back
         // to the page prior to searching. A updated search term will only replace
         // the url.
-        if (action == "push" || (action == "push_if_new_search_else_replace" && first_search) ) {
+        if (action === 'push' || action === 'push_if_new_search_else_replace' && first_search ) {
             history.pushState({}, document.title, renderURL(url));
-        } else if (action == "replace" || (action == "push_if_new_search_else_replace" && !first_search) ) {
+        } else if (action === 'replace' ||
+            action === 'push_if_new_search_else_replace' &&
+            !first_search
+        ) {
             history.replaceState({}, document.title, renderURL(url));
         }
     }
-    
+
     function doSearch(searchterm) {
-
         // Don't search the same twice
-        if (current_searchterm == searchterm) { return; }
-        else { current_searchterm = searchterm; }
+        if (current_searchterm === searchterm) {
+            return;
+        } else {
+            current_searchterm = searchterm;
+        }
 
-        if (searchindex == null) { return; }
+        if (searchindex === null) {
+            return;
+        }
 
         // Do the actual search
-        var results = searchindex.search(searchterm, search_options);
-        var resultcount = Math.min(results.length, results_options.limit_results);
+        const results = searchindex.search(searchterm, search_options);
+        const resultcount = Math.min(results.length, results_options.limit_results);
 
         // Display search metrics
         searchresults_header.innerText = formatSearchMetric(resultcount, searchterm);
 
         // Clear and insert results
-        var searchterms  = searchterm.split(' ');
+        const searchterms = searchterm.split(' ');
         removeChildren(searchresults);
-        for(var i = 0; i < resultcount ; i++){
-            var resultElem = document.createElement('li');
+        for (let i = 0; i < resultcount ; i++) {
+            const resultElem = document.createElement('li');
             resultElem.innerHTML = formatSearchResult(results[i], searchterms);
             searchresults.appendChild(resultElem);
         }
@@ -468,15 +508,18 @@ window.search = window.search || {};
         showResults(true);
     }
 
-    fetch(path_to_root + 'searchindex.json')
-        .then(response => response.json())
-        .then(json => init(json))        
-        .catch(error => { // Try to load searchindex.js if fetch failed
-            var script = document.createElement('script');
-            script.src = path_to_root + 'searchindex.js';
-            script.onload = () => init(window.search);
-            document.head.appendChild(script);
-        });
+    function loadScript(url, id) {
+        const script = document.createElement('script');
+        script.src = url;
+        script.id = id;
+        script.onload = () => init(window.search);
+        script.onerror = error => {
+            console.error(`Failed to load \`${url}\`: ${error}`);
+        };
+        document.head.append(script);
+    }
+
+    loadScript(path_to_root + '{{ resource "searchindex.js" }}', 'search-index');
 
     // Exported functions
     search.hasFocus = hasFocus;

src/front-end/templates/index.hbs

@@ -20,52 +20,55 @@
         <meta name="theme-color" content="#ffffff">
 
         {{#if favicon_svg}}
-        <link rel="icon" href="{{ path_to_root }}favicon.svg">
+        <link rel="icon" href="{{ resource "favicon.svg" }}">
         {{/if}}
         {{#if favicon_png}}
-        <link rel="shortcut icon" href="{{ path_to_root }}favicon.png">
+        <link rel="shortcut icon" href="{{ resource "favicon.png" }}">
         {{/if}}
-        <link rel="stylesheet" href="{{ path_to_root }}css/variables.css">
-        <link rel="stylesheet" href="{{ path_to_root }}css/general.css">
-        <link rel="stylesheet" href="{{ path_to_root }}css/chrome.css">
+        <link rel="stylesheet" href="{{ resource "css/variables.css" }}">
+        <link rel="stylesheet" href="{{ resource "css/general.css" }}">
+        <link rel="stylesheet" href="{{ resource "css/chrome.css" }}">
         {{#if print_enable}}
-        <link rel="stylesheet" href="{{ path_to_root }}css/print.css" media="print">
+        <link rel="stylesheet" href="{{ resource "css/print.css" }}" media="print">
         {{/if}}
 
         <!-- Fonts -->
-        <link rel="stylesheet" href="{{ path_to_root }}FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="{{ resource "FontAwesome/css/font-awesome.css" }}">
         {{#if copy_fonts}}
-        <link rel="stylesheet" href="{{ path_to_root }}fonts/fonts.css">
+        <link rel="stylesheet" href="{{ resource "fonts/fonts.css" }}">
         {{/if}}
 
         <!-- Highlight.js Stylesheets -->
-        <link rel="stylesheet" href="{{ path_to_root }}highlight.css">
-        <link rel="stylesheet" href="{{ path_to_root }}tomorrow-night.css">
-        <link rel="stylesheet" href="{{ path_to_root }}ayu-highlight.css">
+        <link rel="stylesheet" id="highlight-css" href="{{ resource "highlight.css" }}">
+        <link rel="stylesheet" id="tomorrow-night-css" href="{{ resource "tomorrow-night.css" }}">
+        <link rel="stylesheet" id="ayu-highlight-css" href="{{ resource "ayu-highlight.css" }}">
 
         <!-- Custom theme stylesheets -->
         {{#each additional_css}}
-        <link rel="stylesheet" href="{{ ../path_to_root }}{{ this }}">
+        <link rel="stylesheet" href="{{ resource this }}">
         {{/each}}
 
         {{#if mathjax_support}}
         <!-- MathJax -->
         <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
         {{/if}}
+
+        <!-- Provide site root and default themes to javascript -->
+        <script>
+            const path_to_root = "{{ path_to_root }}";
+            const default_light_theme = "{{ default_theme }}";
+            const default_dark_theme = "{{ preferred_dark_theme }}";
+        </script>
+        <!-- Start loading toc.js asap -->
+        <script src="{{ resource "toc.js" }}"></script>
     </head>
     <body>
     <div id="body-container">
-        <!-- Provide site root to javascript -->
-        <script>
-            var path_to_root = "{{ path_to_root }}";
-            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "{{ preferred_dark_theme }}" : "{{ default_theme }}";
-        </script>
-
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
         <script>
             try {
-                var theme = localStorage.getItem('mdbook-theme');
-                var sidebar = localStorage.getItem('mdbook-sidebar');
+                let theme = localStorage.getItem('mdbook-theme');
+                let sidebar = localStorage.getItem('mdbook-sidebar');
 
                 if (theme.startsWith('"') && theme.endsWith('"')) {
                     localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
@@ -79,7 +82,8 @@
 
         <!-- Set the theme before any content is loaded, prevents flash -->
         <script>
-            var theme;
+            const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
+            let theme;
             try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
             if (theme === null || theme === undefined) { theme = default_theme; }
             const html = document.documentElement;
@@ -92,8 +96,8 @@
 
         <!-- Hide / unhide sidebar before it is displayed -->
         <script>
-            var sidebar = null;
-            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            let sidebar = null;
+            const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
             if (document.body.clientWidth >= 1080) {
                 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                 sidebar = sidebar || 'visible';
@@ -107,7 +111,7 @@
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <!-- populated by js -->
-            <div class="sidebar-scrollbox"></div>
+            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
             <noscript>
                 <iframe class="sidebar-iframe-outer" src="{{ path_to_root }}toc.html"></iframe>
             </noscript>
@@ -116,8 +120,6 @@
             </div>
         </nav>
 
-        <script async src="{{ path_to_root }}toc.js"></script>
-
         <div id="page-wrapper" class="page-wrapper">
 
             <div class="page">
@@ -132,6 +134,7 @@
                             <i class="fa fa-paint-brush"></i>
                         </button>
                         <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
@@ -251,7 +254,7 @@
         {{#if google_analytics}}
         <!-- Google Analytics Tag -->
         <script>
-            var localAddrs = ["localhost", "127.0.0.1", ""];
+            const localAddrs = ["localhost", "127.0.0.1", ""];
 
             // make sure we don't activate google analytics if the developer is
             // inspecting the book locally...
@@ -280,26 +283,26 @@
         {{/if}}
 
         {{#if playground_js}}
-        <script src="{{ path_to_root }}ace.js"></script>
-        <script src="{{ path_to_root }}editor.js"></script>
-        <script src="{{ path_to_root }}mode-rust.js"></script>
-        <script src="{{ path_to_root }}theme-dawn.js"></script>
-        <script src="{{ path_to_root }}theme-tomorrow_night.js"></script>
+        <script src="{{ resource "ace.js" }}"></script>
+        <script src="{{ resource "editor.js" }}"></script>
+        <script src="{{ resource "mode-rust.js" }}"></script>
+        <script src="{{ resource "theme-dawn.js" }}"></script>
+        <script src="{{ resource "theme-tomorrow_night.js" }}"></script>
         {{/if}}
 
         {{#if search_js}}
-        <script src="{{ path_to_root }}elasticlunr.min.js"></script>
-        <script src="{{ path_to_root }}mark.min.js"></script>
-        <script src="{{ path_to_root }}searcher.js"></script>
+        <script src="{{ resource "elasticlunr.min.js" }}"></script>
+        <script src="{{ resource "mark.min.js" }}"></script>
+        <script src="{{ resource "searcher.js" }}"></script>
         {{/if}}
 
-        <script src="{{ path_to_root }}clipboard.min.js"></script>
-        <script src="{{ path_to_root }}highlight.js"></script>
-        <script src="{{ path_to_root }}book.js"></script>
+        <script src="{{ resource "clipboard.min.js" }}"></script>
+        <script src="{{ resource "highlight.js" }}"></script>
+        <script src="{{ resource "book.js" }}"></script>
 
         <!-- Custom JS scripts -->
         {{#each additional_js}}
-        <script src="{{ ../path_to_root }}{{this}}"></script>
+        <script src="{{ resource this}}"></script>
         {{/each}}
 
         {{#if is_print}}

src/front-end/templates/toc.html.hbs

@@ -21,20 +21,20 @@
         {{> head}}
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff">
-        <link rel="stylesheet" href="{{ path_to_root }}css/variables.css">
-        <link rel="stylesheet" href="{{ path_to_root }}css/general.css">
-        <link rel="stylesheet" href="{{ path_to_root }}css/chrome.css">
+        <link rel="stylesheet" href="{{ resource "css/variables.css" }}">
+        <link rel="stylesheet" href="{{ resource "css/general.css" }}">
+        <link rel="stylesheet" href="{{ resource "css/chrome.css" }}">
         {{#if print_enable}}
-        <link rel="stylesheet" href="{{ path_to_root }}css/print.css" media="print">
+        <link rel="stylesheet" href="{{ resource "css/print.css" }}" media="print">
         {{/if}}
         <!-- Fonts -->
-        <link rel="stylesheet" href="{{ path_to_root }}FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="{{ resource "FontAwesome/css/font-awesome.css" }}">
         {{#if copy_fonts}}
-        <link rel="stylesheet" href="{{ path_to_root }}fonts/fonts.css">
+        <link rel="stylesheet" href="{{ resource "fonts/fonts.css" }}">
         {{/if}}
         <!-- Custom theme stylesheets -->
         {{#each additional_css}}
-        <link rel="stylesheet" href="{{ ../path_to_root }}{{ this }}">
+        <link rel="stylesheet" href="{{ resource this }}">
         {{/each}}
     </head>
     <body class="sidebar-iframe-inner">

src/front-end/templates/toc.js.hbs

@@ -0,0 +1,70 @@
+// Populate the sidebar
+//
+// This is a script, and not included directly in the page, to control the total size of the book.
+// The TOC contains an entry for each page, so if each page includes a copy of the TOC,
+// the total size of the page becomes O(n**2).
+class MDBookSidebarScrollbox extends HTMLElement {
+    constructor() {
+        super();
+    }
+    connectedCallback() {
+        this.innerHTML = '{{#toc}}{{/toc}}';
+        // Set the current, active page, and reveal it if it's hidden
+        let current_page = document.location.href.toString().split("#")[0];
+        if (current_page.endsWith("/")) {
+            current_page += "index.html";
+        }
+        var links = Array.prototype.slice.call(this.querySelectorAll("a"));
+        var l = links.length;
+        for (var i = 0; i < l; ++i) {
+            var link = links[i];
+            var href = link.getAttribute("href");
+            if (href && !href.startsWith("#") && !/^(?:[a-z+]+:)?\/\//.test(href)) {
+                link.href = path_to_root + href;
+            }
+            // The "index" page is supposed to alias the first chapter in the book.
+            if (link.href === current_page || (i === 0 && path_to_root === "" && current_page.endsWith("/index.html"))) {
+                link.classList.add("active");
+                var parent = link.parentElement;
+                if (parent && parent.classList.contains("chapter-item")) {
+                    parent.classList.add("expanded");
+                }
+                while (parent) {
+                    if (parent.tagName === "LI" && parent.previousElementSibling) {
+                        if (parent.previousElementSibling.classList.contains("chapter-item")) {
+                            parent.previousElementSibling.classList.add("expanded");
+                        }
+                    }
+                    parent = parent.parentElement;
+                }
+            }
+        }
+        // Track and set sidebar scroll position
+        this.addEventListener('click', function(e) {
+            if (e.target.tagName === 'A') {
+                sessionStorage.setItem('sidebar-scroll', this.scrollTop);
+            }
+        }, { passive: true });
+        var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+        sessionStorage.removeItem('sidebar-scroll');
+        if (sidebarScrollTop) {
+            // preserve sidebar scroll position when navigating via links within sidebar
+            this.scrollTop = sidebarScrollTop;
+        } else {
+            // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+            var activeSection = document.querySelector('#sidebar .active');
+            if (activeSection) {
+                activeSection.scrollIntoView({ block: 'center' });
+            }
+        }
+        // Toggle buttons
+        var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle');
+        function toggleSection(ev) {
+            ev.currentTarget.parentElement.classList.toggle('expanded');
+        }
+        Array.from(sidebarAnchorToggles).forEach(function (el) {
+            el.addEventListener('click', toggleSection);
+        });
+    }
+}
+window.customElements.define("mdbook-sidebar-scrollbox", MDBookSidebarScrollbox);

src/lib.rs

@@ -87,6 +87,7 @@ pub mod book;
 pub mod config;
 pub mod preprocess;
 pub mod renderer;
+#[path = "front-end/mod.rs"]
 pub mod theme;
 pub mod utils;
 

src/preprocess/links.rs

@@ -19,9 +19,9 @@ const MAX_LINK_NESTED_DEPTH: usize = 10;
 /// A preprocessor for expanding helpers in a chapter. Supported helpers are:
 ///
 /// - `{{# include}}` - Insert an external file of any type. Include the whole file, only particular
-///.  lines, or only between the specified anchors.
+///   lines, or only between the specified anchors.
 /// - `{{# rustdoc_include}}` - Insert an external Rust file, showing the particular lines
-///.  specified or the lines between specified anchors, and include the rest of the file behind `#`.
+///   specified or the lines between specified anchors, and include the rest of the file behind `#`.
 ///   This hides the lines from initial display but shows them when the reader expands the code
 ///   block and provides them to Rustdoc for testing.
 /// - `{{# playground}}` - Insert runnable Rust files

src/renderer/html_handlebars/hbs_renderer.rs

@@ -2,8 +2,9 @@ use crate::book::{Book, BookItem};
 use crate::config::{BookConfig, Code, Config, HtmlConfig, Playground, RustEdition};
 use crate::errors::*;
 use crate::renderer::html_handlebars::helpers;
+use crate::renderer::html_handlebars::StaticFiles;
 use crate::renderer::{RenderContext, Renderer};
-use crate::theme::{self, playground_editor, Theme};
+use crate::theme::{self, Theme};
 use crate::utils;
 
 use std::borrow::Cow;
@@ -222,134 +223,6 @@ impl HtmlHandlebars {
         rendered
     }
 
-    fn copy_static_files(
-        &self,
-        destination: &Path,
-        theme: &Theme,
-        html_config: &HtmlConfig,
-    ) -> Result<()> {
-        use crate::utils::fs::write_file;
-
-        write_file(
-            destination,
-            ".nojekyll",
-            b"This file makes sure that Github Pages doesn't process mdBook's output.\n",
-        )?;
-
-        if let Some(cname) = &html_config.cname {
-            write_file(destination, "CNAME", format!("{cname}\n").as_bytes())?;
-        }
-
-        write_file(destination, "book.js", &theme.js)?;
-        write_file(destination, "css/general.css", &theme.general_css)?;
-        write_file(destination, "css/chrome.css", &theme.chrome_css)?;
-        if html_config.print.enable {
-            write_file(destination, "css/print.css", &theme.print_css)?;
-        }
-        write_file(destination, "css/variables.css", &theme.variables_css)?;
-        if let Some(contents) = &theme.favicon_png {
-            write_file(destination, "favicon.png", contents)?;
-        }
-        if let Some(contents) = &theme.favicon_svg {
-            write_file(destination, "favicon.svg", contents)?;
-        }
-        write_file(destination, "highlight.css", &theme.highlight_css)?;
-        write_file(destination, "tomorrow-night.css", &theme.tomorrow_night_css)?;
-        write_file(destination, "ayu-highlight.css", &theme.ayu_highlight_css)?;
-        write_file(destination, "highlight.js", &theme.highlight_js)?;
-        write_file(destination, "clipboard.min.js", &theme.clipboard_js)?;
-        write_file(
-            destination,
-            "FontAwesome/css/font-awesome.css",
-            theme::FONT_AWESOME,
-        )?;
-        write_file(
-            destination,
-            "FontAwesome/fonts/fontawesome-webfont.eot",
-            theme::FONT_AWESOME_EOT,
-        )?;
-        write_file(
-            destination,
-            "FontAwesome/fonts/fontawesome-webfont.svg",
-            theme::FONT_AWESOME_SVG,
-        )?;
-        write_file(
-            destination,
-            "FontAwesome/fonts/fontawesome-webfont.ttf",
-            theme::FONT_AWESOME_TTF,
-        )?;
-        write_file(
-            destination,
-            "FontAwesome/fonts/fontawesome-webfont.woff",
-            theme::FONT_AWESOME_WOFF,
-        )?;
-        write_file(
-            destination,
-            "FontAwesome/fonts/fontawesome-webfont.woff2",
-            theme::FONT_AWESOME_WOFF2,
-        )?;
-        write_file(
-            destination,
-            "FontAwesome/fonts/FontAwesome.ttf",
-            theme::FONT_AWESOME_TTF,
-        )?;
-        // Don't copy the stock fonts if the user has specified their own fonts to use.
-        if html_config.copy_fonts && theme.fonts_css.is_none() {
-            write_file(destination, "fonts/fonts.css", theme::fonts::CSS)?;
-            for (file_name, contents) in theme::fonts::LICENSES.iter() {
-                write_file(destination, file_name, contents)?;
-            }
-            for (file_name, contents) in theme::fonts::OPEN_SANS.iter() {
-                write_file(destination, file_name, contents)?;
-            }
-            write_file(
-                destination,
-                theme::fonts::SOURCE_CODE_PRO.0,
-                theme::fonts::SOURCE_CODE_PRO.1,
-            )?;
-        }
-        if let Some(fonts_css) = &theme.fonts_css {
-            if !fonts_css.is_empty() {
-                write_file(destination, "fonts/fonts.css", fonts_css)?;
-            }
-        }
-        if !html_config.copy_fonts && theme.fonts_css.is_none() {
-            warn!(
-                "output.html.copy-fonts is deprecated.\n\
-                This book appears to have copy-fonts=false in book.toml without a fonts.css file.\n\
-                Add an empty `theme/fonts/fonts.css` file to squelch this warning."
-            );
-        }
-        for font_file in &theme.font_files {
-            let contents = fs::read(font_file)?;
-            let filename = font_file.file_name().unwrap();
-            let filename = Path::new("fonts").join(filename);
-            write_file(destination, filename, &contents)?;
-        }
-
-        let playground_config = &html_config.playground;
-
-        // Ace is a very large dependency, so only load it when requested
-        if playground_config.editable && playground_config.copy_js {
-            // Load the editor
-            write_file(destination, "editor.js", playground_editor::JS)?;
-            write_file(destination, "ace.js", playground_editor::ACE_JS)?;
-            write_file(destination, "mode-rust.js", playground_editor::MODE_RUST_JS)?;
-            write_file(
-                destination,
-                "theme-dawn.js",
-                playground_editor::THEME_DAWN_JS,
-            )?;
-            write_file(
-                destination,
-                "theme-tomorrow_night.js",
-                playground_editor::THEME_TOMORROW_NIGHT_JS,
-            )?;
-        }
-
-        Ok(())
-    }
-
     /// Update the context with data for this file
     fn configure_print_version(
         &self,
@@ -381,43 +254,6 @@ impl HtmlHandlebars {
         handlebars.register_helper("theme_option", Box::new(helpers::theme::theme_option));
     }
 
-    /// Copy across any additional CSS and JavaScript files which the book
-    /// has been configured to use.
-    fn copy_additional_css_and_js(
-        &self,
-        html: &HtmlConfig,
-        root: &Path,
-        destination: &Path,
-    ) -> Result<()> {
-        let custom_files = html.additional_css.iter().chain(html.additional_js.iter());
-
-        debug!("Copying additional CSS and JS");
-
-        for custom_file in custom_files {
-            let input_location = root.join(custom_file);
-            let output_location = destination.join(custom_file);
-            if let Some(parent) = output_location.parent() {
-                fs::create_dir_all(parent)
-                    .with_context(|| format!("Unable to create {}", parent.display()))?;
-            }
-            debug!(
-                "Copying {} -> {}",
-                input_location.display(),
-                output_location.display()
-            );
-
-            fs::copy(&input_location, &output_location).with_context(|| {
-                format!(
-                    "Unable to copy {} to {}",
-                    input_location.display(),
-                    output_location.display()
-                )
-            })?;
-        }
-
-        Ok(())
-    }
-
     fn emit_redirects(
         &self,
         root: &Path,
@@ -544,6 +380,57 @@ impl Renderer for HtmlHandlebars {
         fs::create_dir_all(destination)
             .with_context(|| "Unexpected error when constructing destination path")?;
 
+        let mut static_files = StaticFiles::new(&theme, &html_config, &ctx.root)?;
+
+        // Render search index
+        #[cfg(feature = "search")]
+        {
+            let default = crate::config::Search::default();
+            let search = html_config.search.as_ref().unwrap_or(&default);
+            if search.enable {
+                super::search::create_files(&search, &mut static_files, &book)?;
+            }
+        }
+
+        debug!("Render toc js");
+        {
+            let rendered_toc = handlebars.render("toc_js", &data)?;
+            static_files.add_builtin("toc.js", rendered_toc.as_bytes());
+            debug!("Creating toc.js ✓");
+        }
+
+        if html_config.hash_files {
+            static_files.hash_files()?;
+        }
+
+        debug!("Copy static files");
+        let resource_helper = static_files
+            .write_files(&destination)
+            .with_context(|| "Unable to copy across static files")?;
+
+        handlebars.register_helper("resource", Box::new(resource_helper));
+
+        debug!("Render toc html");
+        {
+            data.insert("is_toc_html".to_owned(), json!(true));
+            data.insert("path".to_owned(), json!("toc.html"));
+            let rendered_toc = handlebars.render("toc_html", &data)?;
+            utils::fs::write_file(destination, "toc.html", rendered_toc.as_bytes())?;
+            debug!("Creating toc.html ✓");
+            data.remove("path");
+            data.remove("is_toc_html");
+        }
+
+        utils::fs::write_file(
+            destination,
+            ".nojekyll",
+            b"This file makes sure that Github Pages doesn't process mdBook's output.\n",
+        )?;
+
+        if let Some(cname) = &html_config.cname {
+            utils::fs::write_file(destination, "CNAME", format!("{cname}\n").as_bytes())?;
+        }
+
         let mut is_index = true;
         for item in book.iter() {
             let ctx = RenderItemContext {
@@ -588,33 +475,6 @@ impl Renderer for HtmlHandlebars {
             debug!("Creating print.html ✓");
         }
 
-        debug!("Render toc");
-        {
-            let rendered_toc = handlebars.render("toc_js", &data)?;
-            utils::fs::write_file(destination, "toc.js", rendered_toc.as_bytes())?;
-            debug!("Creating toc.js ✓");
-            data.insert("is_toc_html".to_owned(), json!(true));
-            let rendered_toc = handlebars.render("toc_html", &data)?;
-            utils::fs::write_file(destination, "toc.html", rendered_toc.as_bytes())?;
-            debug!("Creating toc.html ✓");
-            data.remove("is_toc_html");
-        }
-
-        debug!("Copy static files");
-        self.copy_static_files(destination, &theme, &html_config)
-            .with_context(|| "Unable to copy across static files")?;
-        self.copy_additional_css_and_js(&html_config, &ctx.root, destination)
-            .with_context(|| "Unable to copy across additional CSS and JS")?;
-
-        // Render search index
-        #[cfg(feature = "search")]
-        {
-            let search = html_config.search.unwrap_or_default();
-            if search.enable {
-                super::search::create_files(&search, destination, book)?;
-            }
-        }
-
         self.emit_redirects(&ctx.destination, &handlebars, &html_config.redirect)
             .context("Unable to emit redirects")?;
 
@@ -931,7 +791,7 @@ fn add_playground_pre(
                             // we need to inject our own main
                             let (attrs, code) = partition_source(code);
 
-                            format!("# #![allow(unused)]\n{attrs}#fn main() {{\n{code}#}}").into()
+                            format!("# #![allow(unused)]\n{attrs}# fn main() {{\n{code}# }}").into()
                         };
                         content
                     }
@@ -1003,12 +863,9 @@ fn hide_lines_rust(content: &str) -> String {
                 result += &caps[3];
                 result += newline;
                 continue;
-            } else if &caps[2] != "!" && &caps[2] != "[" {
+            } else if matches!(&caps[2], "" | " ") {
                 result += "<span class=\"boring\">";
                 result += &caps[1];
-                if &caps[2] != " " {
-                    result += &caps[2];
-                }
                 result += &caps[3];
                 result += newline;
                 result += "</span>";
@@ -1134,7 +991,7 @@ mod tests {
     fn add_playground() {
         let inputs = [
           ("<code class=\"language-rust\">x()</code>",
-           "<pre class=\"playground\"><code class=\"language-rust\"># #![allow(unused)]\n#fn main() {\nx()\n#}</code></pre>"),
+           "<pre class=\"playground\"><code class=\"language-rust\"># #![allow(unused)]\n# fn main() {\nx()\n# }</code></pre>"),
           ("<code class=\"language-rust\">fn main() {}</code>",
            "<pre class=\"playground\"><code class=\"language-rust\">fn main() {}</code></pre>"),
           ("<code class=\"language-rust editable\">let s = \"foo\n # bar\n\";</code>",
@@ -1164,7 +1021,7 @@ mod tests {
     fn add_playground_edition2015() {
         let inputs = [
           ("<code class=\"language-rust\">x()</code>",
-           "<pre class=\"playground\"><code class=\"language-rust edition2015\"># #![allow(unused)]\n#fn main() {\nx()\n#}</code></pre>"),
+           "<pre class=\"playground\"><code class=\"language-rust edition2015\"># #![allow(unused)]\n# fn main() {\nx()\n# }</code></pre>"),
           ("<code class=\"language-rust\">fn main() {}</code>",
            "<pre class=\"playground\"><code class=\"language-rust edition2015\">fn main() {}</code></pre>"),
           ("<code class=\"language-rust edition2015\">fn main() {}</code>",
@@ -1188,7 +1045,7 @@ mod tests {
     fn add_playground_edition2018() {
         let inputs = [
           ("<code class=\"language-rust\">x()</code>",
-           "<pre class=\"playground\"><code class=\"language-rust edition2018\"># #![allow(unused)]\n#fn main() {\nx()\n#}</code></pre>"),
+           "<pre class=\"playground\"><code class=\"language-rust edition2018\"># #![allow(unused)]\n# fn main() {\nx()\n# }</code></pre>"),
           ("<code class=\"language-rust\">fn main() {}</code>",
            "<pre class=\"playground\"><code class=\"language-rust edition2018\">fn main() {}</code></pre>"),
           ("<code class=\"language-rust edition2015\">fn main() {}</code>",
@@ -1212,7 +1069,7 @@ mod tests {
     fn add_playground_edition2021() {
         let inputs = [
             ("<code class=\"language-rust\">x()</code>",
-             "<pre class=\"playground\"><code class=\"language-rust edition2021\"># #![allow(unused)]\n#fn main() {\nx()\n#}</code></pre>"),
+             "<pre class=\"playground\"><code class=\"language-rust edition2021\"># #![allow(unused)]\n# fn main() {\nx()\n# }</code></pre>"),
             ("<code class=\"language-rust\">fn main() {}</code>",
              "<pre class=\"playground\"><code class=\"language-rust edition2021\">fn main() {}</code></pre>"),
             ("<code class=\"language-rust edition2015\">fn main() {}</code>",
@@ -1237,8 +1094,12 @@ mod tests {
     fn hide_lines_language_rust() {
         let inputs = [
           (
-           "<pre class=\"playground\"><code class=\"language-rust\">\n# #![allow(unused)]\n#fn main() {\nx()\n#}</code></pre>",
+           "<pre class=\"playground\"><code class=\"language-rust\">\n# #![allow(unused)]\n# fn main() {\nx()\n# }</code></pre>",
            "<pre class=\"playground\"><code class=\"language-rust\">\n<span class=\"boring\">#![allow(unused)]\n</span><span class=\"boring\">fn main() {\n</span>x()\n<span class=\"boring\">}</span></code></pre>",),
+          // # must be followed by a space for a line to be hidden
+          (
+           "<pre class=\"playground\"><code class=\"language-rust\">\n#fn main() {\nx()\n#}</code></pre>",
+           "<pre class=\"playground\"><code class=\"language-rust\">\n#fn main() {\nx()\n#}</code></pre>",),
           (
            "<pre class=\"playground\"><code class=\"language-rust\">fn main() {}</code></pre>",
            "<pre class=\"playground\"><code class=\"language-rust\">fn main() {}</code></pre>",),

src/renderer/html_handlebars/helpers/mod.rs

@@ -1,3 +1,4 @@
 pub mod navigation;
+pub mod resources;
 pub mod theme;
 pub mod toc;

src/renderer/html_handlebars/helpers/resources.rs

@@ -0,0 +1,50 @@
+use std::collections::HashMap;
+
+use crate::utils;
+
+use handlebars::{
+    Context, Handlebars, Helper, HelperDef, Output, RenderContext, RenderError, RenderErrorReason,
+};
+
+// Handlebars helper to find filenames with hashes in them
+#[derive(Clone)]
+pub struct ResourceHelper {
+    pub hash_map: HashMap<String, String>,
+}
+
+impl HelperDef for ResourceHelper {
+    fn call<'reg: 'rc, 'rc>(
+        &self,
+        h: &Helper<'rc>,
+        _r: &'reg Handlebars<'_>,
+        ctx: &'rc Context,
+        rc: &mut RenderContext<'reg, 'rc>,
+        out: &mut dyn Output,
+    ) -> Result<(), RenderError> {
+        let param = h.param(0).and_then(|v| v.value().as_str()).ok_or_else(|| {
+            RenderErrorReason::Other(
+                "Param 0 with String type is required for theme_option helper.".to_owned(),
+            )
+        })?;
+
+        let base_path = rc
+            .evaluate(ctx, "@root/path")?
+            .as_json()
+            .as_str()
+            .ok_or_else(|| {
+                RenderErrorReason::Other("Type error for `path`, string expected".to_owned())
+            })?
+            .replace("\"", "");
+
+        let path_to_root = utils::fs::path_to_root(&base_path);
+
+        out.write(&path_to_root)?;
+        out.write(
+            self.hash_map
+                .get(&param[..])
+                .map(|p| &p[..])
+                .unwrap_or(&param),
+        )?;
+        Ok(())
+    }
+}

src/renderer/html_handlebars/mod.rs

@@ -1,9 +1,11 @@
 #![allow(missing_docs)] // FIXME: Document this
 
 pub use self::hbs_renderer::HtmlHandlebars;
+pub use self::static_files::StaticFiles;
 
 mod hbs_renderer;
 mod helpers;
+mod static_files;
 
 #[cfg(feature = "search")]
 mod search;

src/renderer/html_handlebars/search.rs

@@ -1,14 +1,15 @@
 use std::borrow::Cow;
 use std::collections::{HashMap, HashSet};
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use elasticlunr::{Index, IndexBuilder};
 use once_cell::sync::Lazy;
 use pulldown_cmark::*;
 
-use crate::book::{Book, BookItem};
-use crate::config::Search;
+use crate::book::{Book, BookItem, Chapter};
+use crate::config::{Search, SearchChapterSettings};
 use crate::errors::*;
+use crate::renderer::html_handlebars::StaticFiles;
 use crate::theme::searcher;
 use crate::utils;
 use log::{debug, warn};
@@ -26,7 +27,11 @@ fn tokenize(text: &str) -> Vec<String> {
 }
 
 /// Creates all files required for search.
-pub fn create_files(search_config: &Search, destination: &Path, book: &Book) -> Result<()> {
+pub fn create_files(
+    search_config: &Search,
+    static_files: &mut StaticFiles,
+    book: &Book,
+) -> Result<()> {
     let mut index = IndexBuilder::new()
         .add_field_with_tokenizer("title", Box::new(&tokenize))
         .add_field_with_tokenizer("body", Box::new(&tokenize))
@@ -35,26 +40,37 @@ pub fn create_files(search_config: &Search, destination: &Path, book: &Book) ->
 
     let mut doc_urls = Vec::with_capacity(book.sections.len());
 
+    let chapter_configs = sort_search_config(&search_config.chapter);
+    validate_chapter_config(&chapter_configs, book)?;
+
     for item in book.iter() {
-        render_item(&mut index, search_config, &mut doc_urls, item)?;
+        let chapter = match item {
+            BookItem::Chapter(ch) if !ch.is_draft_chapter() => ch,
+            _ => continue,
+        };
+        if let Some(path) = settings_path(chapter) {
+            let chapter_settings = get_chapter_settings(&chapter_configs, path);
+            if !chapter_settings.enable.unwrap_or(true) {
+                continue;
+            }
+        }
+        render_item(&mut index, search_config, &mut doc_urls, chapter)?;
     }
 
     let index = write_to_json(index, search_config, doc_urls)?;
     debug!("Writing search index ✓");
     if index.len() > 10_000_000 {
-        warn!("searchindex.json is very large ({} bytes)", index.len());
+        warn!("search index is very large ({} bytes)", index.len());
     }
 
     if search_config.copy_js {
-        utils::fs::write_file(destination, "searchindex.json", index.as_bytes())?;
-        utils::fs::write_file(
-            destination,
+        static_files.add_builtin(
             "searchindex.js",
-            format!("Object.assign(window.search, {index});").as_bytes(),
-        )?;
-        utils::fs::write_file(destination, "searcher.js", searcher::JS)?;
-        utils::fs::write_file(destination, "mark.min.js", searcher::MARK_JS)?;
-        utils::fs::write_file(destination, "elasticlunr.min.js", searcher::ELASTICLUNR_JS)?;
+            format!("Object.assign(window.search, {});", index).as_bytes(),
+        );
+        static_files.add_builtin("searcher.js", searcher::JS);
+        static_files.add_builtin("mark.min.js", searcher::MARK_JS);
+        static_files.add_builtin("elasticlunr.min.js", searcher::ELASTICLUNR_JS);
         debug!("Copying search files ✓");
     }
 
@@ -100,13 +116,8 @@ fn render_item(
     index: &mut Index,
     search_config: &Search,
     doc_urls: &mut Vec<String>,
-    item: &BookItem,
+    chapter: &Chapter,
 ) -> Result<()> {
-    let chapter = match *item {
-        BookItem::Chapter(ref ch) if !ch.is_draft_chapter() => ch,
-        _ => return Ok(()),
-    };
-
     let chapter_path = chapter
         .path
         .as_ref()
@@ -313,3 +324,82 @@ fn clean_html(html: &str) -> String {
     });
     AMMONIA.clean(html).to_string()
 }
+
+fn settings_path(ch: &Chapter) -> Option<&Path> {
+    ch.source_path.as_deref().or_else(|| ch.path.as_deref())
+}
+
+fn validate_chapter_config(
+    chapter_configs: &[(PathBuf, SearchChapterSettings)],
+    book: &Book,
+) -> Result<()> {
+    for (path, _) in chapter_configs {
+        let found = book
+            .iter()
+            .filter_map(|item| match item {
+                BookItem::Chapter(ch) if !ch.is_draft_chapter() => settings_path(ch),
+                _ => None,
+            })
+            .any(|source_path| source_path.starts_with(path));
+        if !found {
+            bail!(
+                "[output.html.search.chapter] key `{}` does not match any chapter paths",
+                path.display()
+            );
+        }
+    }
+    Ok(())
+}
+
+fn sort_search_config(
+    map: &HashMap<String, SearchChapterSettings>,
+) -> Vec<(PathBuf, SearchChapterSettings)> {
+    let mut settings: Vec<_> = map
+        .iter()
+        .map(|(key, value)| (PathBuf::from(key), value.clone()))
+        .collect();
+    // Note: This is case-sensitive, and assumes the author uses the same case
+    // as the actual filename.
+    settings.sort_by(|a, b| a.0.cmp(&b.0));
+    settings
+}
+
+fn get_chapter_settings(
+    chapter_configs: &[(PathBuf, SearchChapterSettings)],
+    source_path: &Path,
+) -> SearchChapterSettings {
+    let mut result = SearchChapterSettings::default();
+    for (path, config) in chapter_configs {
+        if source_path.starts_with(path) {
+            result.enable = config.enable.or(result.enable);
+        }
+    }
+    result
+}
+
+#[test]
+fn chapter_settings_priority() {
+    let cfg = r#"
+        [output.html.search.chapter]
+        "cli/watch.md" = { enable = true }
+        "cli" = { enable = false }
+        "cli/inner/foo.md" = { enable = false }
+        "cli/inner" = { enable = true }
+        "foo" = {} # Just to make sure empty table is allowed.
+    "#;
+    let cfg: crate::Config = toml::from_str(cfg).unwrap();
+    let html = cfg.html_config().unwrap();
+    let chapter_configs = sort_search_config(&html.search.unwrap().chapter);
+    for (path, enable) in [
+        ("foo.md", None),
+        ("cli/watch.md", Some(true)),
+        ("cli/index.md", Some(false)),
+        ("cli/inner/index.md", Some(true)),
+        ("cli/inner/foo.md", Some(false)),
+    ] {
+        assert_eq!(
+            get_chapter_settings(&chapter_configs, Path::new(path)),
+            SearchChapterSettings { enable }
+        );
+    }
+}

src/renderer/html_handlebars/static_files.rs

@@ -0,0 +1,358 @@
+//! Support for writing static files.
+
+use log::{debug, warn};
+use once_cell::sync::Lazy;
+
+use crate::config::HtmlConfig;
+use crate::errors::*;
+use crate::renderer::html_handlebars::helpers::resources::ResourceHelper;
+use crate::theme::{self, playground_editor, Theme};
+use crate::utils;
+
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::fs::{self, File};
+use std::path::{Path, PathBuf};
+
+/// Map static files to their final names and contents.
+///
+/// It performs [fingerprinting], if you call the `hash_files` method.
+/// If hash-files is turned off, then the files will not be renamed.
+/// It also writes files to their final destination, when `write_files` is called,
+/// and interprets the `{{ resource }}` directives to allow assets to name each other.
+///
+/// [fingerprinting]: https://guides.rubyonrails.org/asset_pipeline.html#fingerprinting-versioning-with-digest-based-urls
+pub struct StaticFiles {
+    static_files: Vec<StaticFile>,
+    hash_map: HashMap<String, String>,
+}
+
+enum StaticFile {
+    Builtin {
+        data: Vec<u8>,
+        filename: String,
+    },
+    Additional {
+        input_location: PathBuf,
+        filename: String,
+    },
+}
+
+impl StaticFiles {
+    pub fn new(theme: &Theme, html_config: &HtmlConfig, root: &Path) -> Result<StaticFiles> {
+        let static_files = Vec::new();
+        let mut this = StaticFiles {
+            hash_map: HashMap::new(),
+            static_files,
+        };
+
+        this.add_builtin("book.js", &theme.js);
+        this.add_builtin("css/general.css", &theme.general_css);
+        this.add_builtin("css/chrome.css", &theme.chrome_css);
+        if html_config.print.enable {
+            this.add_builtin("css/print.css", &theme.print_css);
+        }
+        this.add_builtin("css/variables.css", &theme.variables_css);
+        if let Some(contents) = &theme.favicon_png {
+            this.add_builtin("favicon.png", contents);
+        }
+        if let Some(contents) = &theme.favicon_svg {
+            this.add_builtin("favicon.svg", contents);
+        }
+        this.add_builtin("highlight.css", &theme.highlight_css);
+        this.add_builtin("tomorrow-night.css", &theme.tomorrow_night_css);
+        this.add_builtin("ayu-highlight.css", &theme.ayu_highlight_css);
+        this.add_builtin("highlight.js", &theme.highlight_js);
+        this.add_builtin("clipboard.min.js", &theme.clipboard_js);
+        this.add_builtin("FontAwesome/css/font-awesome.css", theme::FONT_AWESOME);
+        this.add_builtin(
+            "FontAwesome/fonts/fontawesome-webfont.eot",
+            theme::FONT_AWESOME_EOT,
+        );
+        this.add_builtin(
+            "FontAwesome/fonts/fontawesome-webfont.svg",
+            theme::FONT_AWESOME_SVG,
+        );
+        this.add_builtin(
+            "FontAwesome/fonts/fontawesome-webfont.ttf",
+            theme::FONT_AWESOME_TTF,
+        );
+        this.add_builtin(
+            "FontAwesome/fonts/fontawesome-webfont.woff",
+            theme::FONT_AWESOME_WOFF,
+        );
+        this.add_builtin(
+            "FontAwesome/fonts/fontawesome-webfont.woff2",
+            theme::FONT_AWESOME_WOFF2,
+        );
+        this.add_builtin("FontAwesome/fonts/FontAwesome.ttf", theme::FONT_AWESOME_TTF);
+        if html_config.copy_fonts && theme.fonts_css.is_none() {
+            this.add_builtin("fonts/fonts.css", theme::fonts::CSS);
+            for (file_name, contents) in theme::fonts::LICENSES.iter() {
+                this.add_builtin(file_name, contents);
+            }
+            for (file_name, contents) in theme::fonts::OPEN_SANS.iter() {
+                this.add_builtin(file_name, contents);
+            }
+            this.add_builtin(
+                theme::fonts::SOURCE_CODE_PRO.0,
+                theme::fonts::SOURCE_CODE_PRO.1,
+            );
+        } else if let Some(fonts_css) = &theme.fonts_css {
+            if !fonts_css.is_empty() {
+                this.add_builtin("fonts/fonts.css", fonts_css);
+            }
+        }
+        if !html_config.copy_fonts && theme.fonts_css.is_none() {
+            warn!(
+                "output.html.copy-fonts is deprecated.\n\
+                This book appears to have copy-fonts=false in book.toml without a fonts.css file.\n\
+                Add an empty `theme/fonts/fonts.css` file to squelch this warning."
+            );
+        }
+
+        let playground_config = &html_config.playground;
+
+        // Ace is a very large dependency, so only load it when requested
+        if playground_config.editable && playground_config.copy_js {
+            // Load the editor
+            this.add_builtin("editor.js", playground_editor::JS);
+            this.add_builtin("ace.js", playground_editor::ACE_JS);
+            this.add_builtin("mode-rust.js", playground_editor::MODE_RUST_JS);
+            this.add_builtin("theme-dawn.js", playground_editor::THEME_DAWN_JS);
+            this.add_builtin(
+                "theme-tomorrow_night.js",
+                playground_editor::THEME_TOMORROW_NIGHT_JS,
+            );
+        }
+
+        let custom_files = html_config
+            .additional_css
+            .iter()
+            .chain(html_config.additional_js.iter());
+
+        for custom_file in custom_files {
+            let input_location = root.join(custom_file);
+
+            this.static_files.push(StaticFile::Additional {
+                input_location,
+                filename: custom_file
+                    .to_str()
+                    .with_context(|| "resource file names must be valid utf8")?
+                    .to_owned(),
+            });
+        }
+
+        for input_location in theme.font_files.iter().cloned() {
+            let filename = Path::new("fonts")
+                .join(input_location.file_name().unwrap())
+                .to_str()
+                .with_context(|| "resource file names must be valid utf8")?
+                .to_owned();
+            this.static_files.push(StaticFile::Additional {
+                input_location,
+                filename,
+            });
+        }
+
+        Ok(this)
+    }
+
+    pub fn add_builtin(&mut self, filename: &str, data: &[u8]) {
+        self.static_files.push(StaticFile::Builtin {
+            filename: filename.to_owned(),
+            data: data.to_owned(),
+        });
+    }
+
+    /// Updates this [`StaticFiles`] to hash the contents for determining the
+    /// filename for each resource.
+    pub fn hash_files(&mut self) -> Result<()> {
+        use sha2::{Digest, Sha256};
+        use std::io::Read;
+        for static_file in &mut self.static_files {
+            match static_file {
+                StaticFile::Builtin {
+                    ref mut filename,
+                    ref data,
+                } => {
+                    let mut parts = filename.splitn(2, '.');
+                    let parts = parts.next().and_then(|p| Some((p, parts.next()?)));
+                    if let Some((name, suffix)) = parts {
+                        // FontAwesome already does its own cache busting with the ?v=4.7.0 thing,
+                        // and I don't want to have to patch its CSS file to use `{{ resource }}`
+                        if name != ""
+                            && suffix != ""
+                            && suffix != "txt"
+                            && !name.starts_with("FontAwesome/fonts/")
+                        {
+                            let hex = hex::encode(&Sha256::digest(data)[..4]);
+                            let new_filename = format!("{}-{}.{}", name, hex, suffix);
+                            self.hash_map.insert(filename.clone(), new_filename.clone());
+                            *filename = new_filename;
+                        }
+                    }
+                }
+                StaticFile::Additional {
+                    ref mut filename,
+                    ref input_location,
+                } => {
+                    let mut parts = filename.splitn(2, '.');
+                    let parts = parts.next().and_then(|p| Some((p, parts.next()?)));
+                    if let Some((name, suffix)) = parts {
+                        if name != "" && suffix != "" {
+                            let mut digest = Sha256::new();
+                            let mut input_file = File::open(input_location)
+                                .with_context(|| "open static file for hashing")?;
+                            let mut buf = vec![0; 1024];
+                            loop {
+                                let amt = input_file
+                                    .read(&mut buf)
+                                    .with_context(|| "read static file for hashing")?;
+                                if amt == 0 {
+                                    break;
+                                };
+                                digest.update(&buf[..amt]);
+                            }
+                            let hex = hex::encode(&digest.finalize()[..4]);
+                            let new_filename = format!("{}-{}.{}", name, hex, suffix);
+                            self.hash_map.insert(filename.clone(), new_filename.clone());
+                            *filename = new_filename;
+                        }
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    pub fn write_files(self, destination: &Path) -> Result<ResourceHelper> {
+        use crate::utils::fs::write_file;
+        use regex::bytes::{Captures, Regex};
+        // The `{{ resource "name" }}` directive in static resources look like
+        // handlebars syntax, even if they technically aren't.
+        static RESOURCE: Lazy<Regex> =
+            Lazy::new(|| Regex::new(r#"\{\{ resource "([^"]+)" \}\}"#).unwrap());
+        fn replace_all<'a>(
+            hash_map: &HashMap<String, String>,
+            data: &'a [u8],
+            filename: &str,
+        ) -> Cow<'a, [u8]> {
+            RESOURCE.replace_all(data, move |captures: &Captures<'_>| {
+                let name = captures
+                    .get(1)
+                    .expect("capture 1 in resource regex")
+                    .as_bytes();
+                let name = std::str::from_utf8(name).expect("resource name with invalid utf8");
+                let resource_filename = hash_map.get(name).map(|s| &s[..]).unwrap_or(name);
+                let path_to_root = utils::fs::path_to_root(filename);
+                format!("{}{}", path_to_root, resource_filename)
+                    .as_bytes()
+                    .to_owned()
+            })
+        }
+        for static_file in &self.static_files {
+            match static_file {
+                StaticFile::Builtin { filename, data } => {
+                    debug!("Writing builtin -> {}", filename);
+                    let data = if filename.ends_with(".css") || filename.ends_with(".js") {
+                        replace_all(&self.hash_map, data, filename)
+                    } else {
+                        Cow::Borrowed(&data[..])
+                    };
+                    write_file(destination, filename, &data)?;
+                }
+                StaticFile::Additional {
+                    ref input_location,
+                    ref filename,
+                } => {
+                    let output_location = destination.join(filename);
+                    debug!(
+                        "Copying {} -> {}",
+                        input_location.display(),
+                        output_location.display()
+                    );
+                    if let Some(parent) = output_location.parent() {
+                        fs::create_dir_all(parent)
+                            .with_context(|| format!("Unable to create {}", parent.display()))?;
+                    }
+                    if filename.ends_with(".css") || filename.ends_with(".js") {
+                        let data = fs::read(input_location)?;
+                        let data = replace_all(&self.hash_map, &data, filename);
+                        write_file(destination, filename, &data)?;
+                    } else {
+                        fs::copy(input_location, &output_location).with_context(|| {
+                            format!(
+                                "Unable to copy {} to {}",
+                                input_location.display(),
+                                output_location.display()
+                            )
+                        })?;
+                    }
+                }
+            }
+        }
+        let hash_map = self.hash_map;
+        Ok(ResourceHelper { hash_map })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::HtmlConfig;
+    use crate::theme::Theme;
+    use crate::utils::fs::write_file;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_write_directive() {
+        let theme = Theme {
+            index: Vec::new(),
+            head: Vec::new(),
+            redirect: Vec::new(),
+            header: Vec::new(),
+            chrome_css: Vec::new(),
+            general_css: Vec::new(),
+            print_css: Vec::new(),
+            variables_css: Vec::new(),
+            favicon_png: Some(Vec::new()),
+            favicon_svg: Some(Vec::new()),
+            js: Vec::new(),
+            highlight_css: Vec::new(),
+            tomorrow_night_css: Vec::new(),
+            ayu_highlight_css: Vec::new(),
+            highlight_js: Vec::new(),
+            clipboard_js: Vec::new(),
+            toc_js: Vec::new(),
+            toc_html: Vec::new(),
+            fonts_css: None,
+            font_files: Vec::new(),
+        };
+        let temp_dir = TempDir::with_prefix("mdbook-").unwrap();
+        let reference_js = Path::new("static-files-test-case-reference.js");
+        let mut html_config = HtmlConfig::default();
+        html_config.additional_js.push(reference_js.to_owned());
+        write_file(
+            temp_dir.path(),
+            reference_js,
+            br#"{{ resource "book.js" }}"#,
+        )
+        .unwrap();
+        let mut static_files = StaticFiles::new(&theme, &html_config, temp_dir.path()).unwrap();
+        static_files.hash_files().unwrap();
+        static_files.write_files(temp_dir.path()).unwrap();
+        // custom JS winds up referencing book.js
+        let reference_js_content = std::fs::read_to_string(
+            temp_dir
+                .path()
+                .join("static-files-test-case-reference-635c9cdc.js"),
+        )
+        .unwrap();
+        assert_eq!("book-e3b0c442.js", reference_js_content);
+        // book.js winds up empty
+        let book_js_content =
+            std::fs::read_to_string(temp_dir.path().join("book-e3b0c442.js")).unwrap();
+        assert_eq!("", book_js_content);
+    }
+}

src/theme/toc.js.hbs

@@ -1,54 +0,0 @@
-// Populate the sidebar
-//
-// This is a script, and not included directly in the page, to control the total size of the book.
-// The TOC contains an entry for each page, so if each page includes a copy of the TOC,
-// the total size of the page becomes O(n**2).
-var sidebarScrollbox = document.querySelector("#sidebar .sidebar-scrollbox");
-sidebarScrollbox.innerHTML = '{{#toc}}{{/toc}}';
-(function() {
-    let current_page = document.location.href.toString();
-    if (current_page.endsWith("/")) {
-        current_page += "index.html";
-    }
-    var links = sidebarScrollbox.querySelectorAll("a");
-    var l = links.length;
-    for (var i = 0; i < l; ++i) {
-        var link = links[i];
-        var href = link.getAttribute("href");
-        if (href && !href.startsWith("#") && !/^(?:[a-z+]+:)?\/\//.test(href)) {
-            link.href = path_to_root + href;
-        }
-        // The "index" page is supposed to alias the first chapter in the book.
-        if (link.href === current_page || (i === 0 && path_to_root === "" && current_page.endsWith("/index.html"))) {
-            link.classList.add("active");
-            var parent = link.parentElement;
-            while (parent) {
-                if (parent.tagName === "LI" && parent.previousElementSibling) {
-                    if (parent.previousElementSibling.classList.contains("chapter-item")) {
-                        parent.previousElementSibling.classList.add("expanded");
-                    }
-                }
-                parent = parent.parentElement;
-            }
-        }
-    }
-})();
-
-// Track and set sidebar scroll position
-sidebarScrollbox.addEventListener('click', function(e) {
-    if (e.target.tagName === 'A') {
-        sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
-    }
-}, { passive: true });
-var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
-sessionStorage.removeItem('sidebar-scroll');
-if (sidebarScrollTop) {
-    // preserve sidebar scroll position when navigating via links within sidebar
-    sidebarScrollbox.scrollTop = sidebarScrollTop;
-} else {
-    // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
-    var activeSection = document.querySelector('#sidebar .active');
-    if (activeSection) {
-        activeSection.scrollIntoView({ block: 'center' });
-    }
-}

src/utils/mod.rs

@@ -212,18 +212,156 @@ pub fn render_markdown_with_path(
     smart_punctuation: bool,
     path: Option<&Path>,
 ) -> String {
-    let mut s = String::with_capacity(text.len() * 3 / 2);
-    let p = new_cmark_parser(text, smart_punctuation);
-    let events = p
+    let mut body = String::with_capacity(text.len() * 3 / 2);
+
+    // Based on
+    // https://github.com/pulldown-cmark/pulldown-cmark/blob/master/pulldown-cmark/examples/footnote-rewrite.rs
+
+    // This handling of footnotes is a two-pass process. This is done to
+    // support linkbacks, little arrows that allow you to jump back to the
+    // footnote reference. The first pass collects the footnote definitions.
+    // The second pass modifies those definitions to include the linkbacks,
+    // and inserts the definitions back into the `events` list.
+
+    // This is a map of name -> (number, count)
+    // `name` is the name of the footnote.
+    // `number` is the footnote number displayed in the output.
+    // `count` is the number of references to this footnote (used for multiple
+    // linkbacks, and checking for unused footnotes).
+    let mut footnote_numbers = HashMap::new();
+    // This is a list of (name, Vec<Event>)
+    // `name` is the name of the footnote.
+    // The events list is the list of events needed to build the footnote definition.
+    let mut footnote_defs = Vec::new();
+
+    // The following are used when currently processing a footnote definition.
+    //
+    // This is the name of the footnote (escaped).
+    let mut in_footnote_name = String::new();
+    // This is the list of events to build the footnote definition.
+    let mut in_footnote = Vec::new();
+
+    let events = new_cmark_parser(text, smart_punctuation)
         .map(clean_codeblock_headers)
         .map(|event| adjust_links(event, path))
         .flat_map(|event| {
             let (a, b) = wrap_tables(event);
             a.into_iter().chain(b)
+        })
+        // Footnote rewriting must go last to ensure inner definition contents
+        // are processed (since they get pulled out of the initial stream).
+        .filter_map(|event| {
+            match event {
+                Event::Start(Tag::FootnoteDefinition(name)) => {
+                    if !in_footnote.is_empty() {
+                        log::warn!("internal bug: nested footnote not expected in {path:?}");
+                    }
+                    in_footnote_name = special_escape(&name);
+                    None
+                }
+                Event::End(TagEnd::FootnoteDefinition) => {
+                    let def_events = std::mem::take(&mut in_footnote);
+                    let name = std::mem::take(&mut in_footnote_name);
+                    footnote_defs.push((name, def_events));
+                    None
+                }
+                Event::FootnoteReference(name) => {
+                    let name = special_escape(&name);
+                    let len = footnote_numbers.len() + 1;
+                    let (n, count) = footnote_numbers.entry(name.clone()).or_insert((len, 0));
+                    *count += 1;
+                    let html = Event::Html(
+                        format!(
+                            "<sup class=\"footnote-reference\" id=\"fr-{name}-{count}\">\
+                                <a href=\"#footnote-{name}\">{n}</a>\
+                             </sup>"
+                        )
+                        .into(),
+                    );
+                    if in_footnote_name.is_empty() {
+                        Some(html)
+                    } else {
+                        // While inside a footnote, we need to accumulate.
+                        in_footnote.push(html);
+                        None
+                    }
+                }
+                // While inside a footnote, accumulate all events into a local.
+                _ if !in_footnote_name.is_empty() => {
+                    in_footnote.push(event);
+                    None
+                }
+                _ => Some(event),
+            }
         });
 
-    html::push_html(&mut s, events);
-    s
+    html::push_html(&mut body, events);
+
+    if !footnote_defs.is_empty() {
+        add_footnote_defs(&mut body, path, footnote_defs, &footnote_numbers);
+    }
+
+    body
+}
+
+/// Adds all footnote definitions into `body`.
+fn add_footnote_defs(
+    body: &mut String,
+    path: Option<&Path>,
+    mut defs: Vec<(String, Vec<Event<'_>>)>,
+    numbers: &HashMap<String, (usize, u32)>,
+) {
+    // Remove unused.
+    defs.retain(|(name, _)| {
+        if !numbers.contains_key(name) {
+            log::warn!(
+                "footnote `{name}` in `{}` is defined but not referenced",
+                path.map_or_else(|| Cow::from("<unknown>"), |p| p.to_string_lossy())
+            );
+            false
+        } else {
+            true
+        }
+    });
+
+    defs.sort_by_cached_key(|(name, _)| numbers[name].0);
+
+    body.push_str(
+        "<hr>\n\
+         <ol class=\"footnote-definition\">",
+    );
+
+    // Insert the backrefs to the definition, and put the definitions in the output.
+    for (name, mut fn_events) in defs {
+        let count = numbers[&name].1;
+        fn_events.insert(
+            0,
+            Event::Html(format!("<li id=\"footnote-{name}\">").into()),
+        );
+        // Generate the linkbacks.
+        for usage in 1..=count {
+            let nth = if usage == 1 {
+                String::new()
+            } else {
+                usage.to_string()
+            };
+            let backlink =
+                Event::Html(format!(" <a href=\"#fr-{name}-{usage}\">↩{nth}</a>").into());
+            if matches!(fn_events.last(), Some(Event::End(TagEnd::Paragraph))) {
+                // Put the linkback at the end of the last paragraph instead
+                // of on a line by itself.
+                fn_events.insert(fn_events.len() - 1, backlink);
+            } else {
+                // Not a clear place to put it in this circumstance, so put it
+                // at the end.
+                fn_events.push(backlink);
+            }
+        }
+        fn_events.push(Event::Html("</li>\n".into()));
+        html::push_html(body, fn_events.into_iter());
+    }
+
+    body.push_str("</ol>");
 }
 
 /// Wraps tables in a `.table-wrapper` class to apply overflow-x rules to.
@@ -267,13 +405,14 @@ pub fn log_backtrace(e: &Error) {
 
 pub(crate) fn special_escape(mut s: &str) -> String {
     let mut escaped = String::with_capacity(s.len());
-    let needs_escape: &[char] = &['<', '>', '\'', '\\', '&'];
+    let needs_escape: &[char] = &['<', '>', '\'', '"', '\\', '&'];
     while let Some(next) = s.find(needs_escape) {
         escaped.push_str(&s[..next]);
         match s.as_bytes()[next] {
             b'<' => escaped.push_str("&lt;"),
             b'>' => escaped.push_str("&gt;"),
             b'\'' => escaped.push_str("&#39;"),
+            b'"' => escaped.push_str("&quot;"),
             b'\\' => escaped.push_str("&#92;"),
             b'&' => escaped.push_str("&amp;"),
             _ => unreachable!(),

test_book/book.toml

@@ -9,6 +9,7 @@ edition = "2018"
 
 [output.html]
 mathjax-support = true
+hash-files = true
 
 [output.html.playground]
 editable = true

tests/alternative_backends.rs

@@ -23,7 +23,10 @@ fn failing_alternate_backend() {
 #[test]
 fn missing_backends_are_fatal() {
     let (md, _temp) = dummy_book_with_backend("missing", "trduyvbhijnorgevfuhn", false);
-    assert!(md.build().is_err());
+    let got = md.build();
+    assert!(got.is_err());
+    let error_message = got.err().unwrap().to_string();
+    assert_eq!(error_message, "Rendering failed");
 }
 
 #[test]

tests/cli/init.rs

@@ -22,3 +22,26 @@ fn base_mdbook_init_can_skip_confirmation_prompts() {
 
     assert!(!temp.path().join(".gitignore").exists());
 }
+
+/// Run `mdbook init` with `--title` without git config.
+///
+/// Regression test for https://github.com/rust-lang/mdBook/issues/2485
+#[test]
+fn no_git_config_with_title() {
+    let temp = DummyBook::new().build().unwrap();
+
+    // doesn't exist before
+    assert!(!temp.path().join("book").exists());
+
+    let mut cmd = mdbook_cmd();
+    cmd.args(["init", "--title", "Example title"])
+        .current_dir(temp.path())
+        .env("GIT_CONFIG_GLOBAL", "")
+        .env("GIT_CONFIG_NOSYSTEM", "1");
+    cmd.assert()
+        .success()
+        .stdout(predicates::str::contains("\nAll done, no errors...\n"));
+
+    let config = Config::from_disk(temp.path().join("book.toml")).unwrap();
+    assert_eq!(config.book.title.as_deref(), Some("Example title"));
+}

tests/cli/test.rs

@@ -32,3 +32,15 @@ fn mdbook_cli_detects_book_with_failing_tests() {
       .stderr(predicates::str::is_match(r##"returned an error:\n\n"##).unwrap())
       .stderr(predicates::str::is_match(r##"Nested_Chapter::Rustdoc_include_works_with_anchors_too \(line \d+\) ... FAILED"##).unwrap());
 }
+
+#[test]
+fn empty_cli() {
+    let mut cmd = mdbook_cmd();
+    cmd.assert()
+        .failure()
+        .code(2)
+        .stdout(predicates::str::is_empty())
+        .stderr(predicates::str::contains(
+            "Creates a book from markdown files",
+        ));
+}

tests/custom_preprocessors.rs

@@ -43,6 +43,18 @@ fn ask_the_preprocessor_to_blow_up() {
     let got = md.build();
 
     assert!(got.is_err());
+    let error_message = got.err().unwrap().to_string();
+    let status = if cfg!(windows) {
+        "exit code: 1"
+    } else {
+        "exit status: 1"
+    };
+    assert_eq!(
+        error_message,
+        format!(
+            r#"The "nop-preprocessor" preprocessor exited unsuccessfully with {status} status"#
+        )
+    );
 }
 
 #[test]

tests/dummy_book/src/first/markdown.md

@@ -15,8 +15,34 @@ Footnote example[^1], or with a word[^word].
 [^1]: This is a footnote.
 
 [^word]: A longer footnote.
-    With multiple lines.
-    Third line.
+    With multiple lines. [Link to unicode](unicode.md).
+    With a reference inside.[^1]
+
+There are multiple references to word[^word].
+
+Footnote without a paragraph[^para]
+
+[^para]:
+    1. Item one
+       1. Sub-item
+    2. Item two
+
+Footnote with multiple paragraphs[^multiple]
+
+[^define-before-use]: This is defined before it is referred to.
+
+<!-- Using <p> tags to work around rustdoc issue, this should move to a separate book.
+     https://github.com/rust-lang/rust/issues/139064
+-->
+[^multiple]: <p>One</p><p>Two</p><p>Three</p>
+
+[^unused]: This footnote is defined by not used.
+
+Footnote name with wacky characters[^"wacky"]
+
+[^"wacky"]: Testing footnote id with special characters.
+
+Testing when referring to something earlier.[^define-before-use]
 
 ## Strikethrough
 

tests/gui/move-between-pages.goml

@@ -0,0 +1,39 @@
+// This tests pressing the left and right arrows moving to previous and next page.
+
+// We disable the requests checks because `mode-rust.js` is not found.
+fail-on-request-error: false
+
+go-to: |DOC_PATH| + "index.html"
+
+// default page is the first numbered page
+assert-text: ("title", "Introduction - mdBook test book")
+
+// Moving left we get to the prefix page
+press-key: 'ArrowLeft'
+assert-text: ("title", "Prefix Chapter - mdBook test book")
+
+// Trying to move to the left beyond the prefix pages - nothing changes
+press-key: 'ArrowLeft'
+assert-text: ("title", "Prefix Chapter - mdBook test book")
+
+// Back to the main page
+press-key: 'ArrowRight'
+assert-text: ("title", "Introduction - mdBook test book")
+
+press-key: 'ArrowRight'
+assert-text: ("title", "Markdown Individual tags - mdBook test book")
+
+press-key: 'ArrowRight'
+assert-text: ("title", "Heading - mdBook test book")
+
+// Last numbered page
+go-to: "../rust/rust_codeblock.html"
+assert-text: ("title", "Rust Codeblocks - mdBook test book")
+
+// Go to the suffix chapter
+press-key: 'ArrowRight'
+assert-text: ("title", "Suffix Chapter - mdBook test book")
+
+// Try to go beyond the last page
+press-key: 'ArrowRight'
+assert-text: ("title", "Suffix Chapter - mdBook test book")

tests/gui/runner.rs

@@ -0,0 +1,135 @@
+use serde_json::Value;
+use std::collections::HashSet;
+use std::env::current_dir;
+use std::fs::{read_dir, read_to_string, remove_dir_all};
+use std::process::Command;
+
+fn get_available_browser_ui_test_version_inner(global: bool) -> Option<String> {
+    let mut command = Command::new("npm");
+    command
+        .arg("list")
+        .arg("--parseable")
+        .arg("--long")
+        .arg("--depth=0");
+    if global {
+        command.arg("--global");
+    }
+    let stdout = command.output().expect("`npm` command not found").stdout;
+    let lines = String::from_utf8_lossy(&stdout);
+    lines
+        .lines()
+        .find_map(|l| l.split(':').nth(1)?.strip_prefix("browser-ui-test@"))
+        .map(std::borrow::ToOwned::to_owned)
+}
+
+fn get_available_browser_ui_test_version() -> Option<String> {
+    get_available_browser_ui_test_version_inner(false)
+        .or_else(|| get_available_browser_ui_test_version_inner(true))
+}
+
+fn expected_browser_ui_test_version() -> String {
+    let content = read_to_string("package.json").expect("failed to read `package.json`");
+    let v: Value = serde_json::from_str(&content).expect("failed to parse `package.json`");
+    let Some(dependencies) = v.get("dependencies") else {
+        panic!("Missing `dependencies` key in `package.json`");
+    };
+    let Some(browser_ui_test) = dependencies.get("browser-ui-test") else {
+        panic!("Missing `browser-ui-test` key in \"dependencies\" object in `package.json`");
+    };
+    let Value::String(version) = browser_ui_test else {
+        panic!("`browser-ui-test` version is not a string");
+    };
+    version.trim().to_string()
+}
+
+fn main() {
+    let browser_ui_test_version = expected_browser_ui_test_version();
+    match get_available_browser_ui_test_version() {
+        Some(version) => {
+            if version != browser_ui_test_version {
+                eprintln!(
+                    "⚠️ Installed version of browser-ui-test (`{version}`) is different than the \
+                     one used in the CI (`{browser_ui_test_version}`) You can install this version \
+                     using `npm update browser-ui-test` or by using `npm install browser-ui-test\
+                     @{browser_ui_test_version}`",
+                );
+            }
+        }
+        None => {
+            panic!(
+                "`browser-ui-test` is not installed. You can install this package using `npm \
+                 update browser-ui-test` or by using `npm install browser-ui-test\
+                 @{browser_ui_test_version}`",
+            );
+        }
+    }
+
+    let current_dir = current_dir().expect("failed to retrieve current directory");
+    let test_book = current_dir.join("test_book");
+
+    // Result doesn't matter.
+    let _ = remove_dir_all(test_book.join("book"));
+
+    let mut cmd = Command::new("cargo");
+    cmd.arg("run").arg("build").arg(&test_book);
+    // Then we run the GUI tests on it.
+    assert!(cmd.status().is_ok_and(|status| status.success()));
+
+    let book_dir = format!("file://{}", current_dir.join("test_book/book/").display());
+
+    let mut no_headless = false;
+    let mut filters = Vec::new();
+    for arg in std::env::args().skip(1) {
+        if arg == "--disable-headless-test" {
+            no_headless = true;
+        } else {
+            filters.push(arg);
+        }
+    }
+
+    let mut command = Command::new("npx");
+    command
+        .arg("browser-ui-test")
+        .args(["--variable", "DOC_PATH", book_dir.as_str()]);
+    if no_headless {
+        command.arg("--no-headless");
+    }
+
+    let test_dir = "tests/gui";
+    if filters.is_empty() {
+        command.args(["--test-folder", test_dir]);
+    } else {
+        let files = read_dir(test_dir)
+            .map(|dir| {
+                dir.filter_map(|entry| entry.ok())
+                    .map(|entry| entry.path())
+                    .filter(|path| {
+                        path.extension().is_some_and(|ext| ext == "goml") && path.is_file()
+                    })
+                    .collect::<Vec<_>>()
+            })
+            .unwrap_or(Vec::new());
+        let mut matches = HashSet::new();
+        for filter in filters {
+            for file in files.iter().filter(|f| {
+                f.file_name()
+                    .and_then(|name| name.to_str())
+                    .is_some_and(|name| name.contains(&filter))
+            }) {
+                matches.insert(file.display().to_string());
+            }
+        }
+        if matches.is_empty() {
+            println!("No test found");
+            return;
+        }
+        command.arg("--test-files");
+        for entry in matches {
+            command.arg(entry);
+        }
+    }
+
+    // Then we run the GUI tests on it.
+    let status = command.status().expect("failed to get command output");
+    assert!(status.success(), "{status:?}");
+}

tests/gui/search.goml

@@ -0,0 +1,30 @@
+// This tests basic search behavior.
+
+go-to: |DOC_PATH| + "index.html"
+
+define-function: (
+    "open-search",
+    [],
+    block {
+        assert-css: ("#search-wrapper", {"display": "none"})
+        press-key: 'S'
+        wait-for-css-false: ("#search-wrapper", {"display": "none"})
+    }
+)
+
+call-function: ("open-search", {})
+assert-text: ("#searchresults-header", "")
+write: "strikethrough"
+wait-for-text: ("#searchresults-header", "2 search results for 'strikethrough':")
+// Close the search display
+press-key: 'Escape'
+wait-for-css: ("#search-wrapper", {"display": "none"})
+// Reopening the search should show the last value
+call-function: ("open-search", {})
+assert-text: ("#searchresults-header", "2 search results for 'strikethrough':")
+// Navigate to a sub-chapter
+go-to: "./individual/strikethrough.html"
+assert-text: ("#searchresults-header", "")
+call-function: ("open-search", {})
+write: "strikethrough"
+wait-for-text: ("#searchresults-header", "2 search results for 'strikethrough':")

tests/gui/sidebar-nojs.goml

@@ -0,0 +1,13 @@
+// This GUI test checks that the sidebar takes the whole height when it's inside
+// an iframe (because of JS disabled).
+// Regression test for <https://github.com/rust-lang/mdBook/issues/2528>.
+
+// We disable javascript
+javascript: false
+go-to: |DOC_PATH| + "index.html"
+store-value: (height, 1000)
+set-window-size: (1000, |height|)
+
+within-iframe: (".sidebar-iframe-outer", block {
+    assert-size: (" body", {"height": |height|})
+})

tests/gui/sidebar.goml

@@ -0,0 +1,56 @@
+// This GUI test checks sidebar hide/show and also its behaviour on smaller
+// width.
+
+go-to: |DOC_PATH| + "index.html"
+set-window-size: (1100, 600)
+// Need to reload for the new size to be taken account by the JS.
+reload:
+
+store-value: (content_indent, 308)
+
+define-function: (
+    "hide-sidebar",
+    [],
+    block {
+        // The content should be "moved" to the right because of the sidebar.
+        assert-css: ("#sidebar", {"transform": "none"})
+        assert-position: ("#page-wrapper", {"x": |content_indent|})
+
+        // We now hide the sidebar.
+        click: "#sidebar-toggle"
+        wait-for: "body.sidebar-hidden"
+        // `transform` is 0.3s so we need to wait a bit (0.5s) to ensure the animation is done.
+        wait-for: 5000
+        assert-css-false: ("#sidebar", {"transform": "none"})
+        // The page content should now be on the left.
+        assert-position: ("#page-wrapper", {"x": 0})
+    },
+)
+
+define-function: (
+    "show-sidebar",
+    [],
+    block {
+        // The page content should be on the left and the sidebar "moved out".
+        assert-css: ("#sidebar", {"transform": "matrix(1, 0, 0, 1, -308, 0)"})
+        assert-position: ("#page-wrapper", {"x": 0})
+
+        // We expand the sidebar.
+        click: "#sidebar-toggle"
+        wait-for: "body.sidebar-visible"
+        // `transform` is 0.3s so we need to wait a bit (0.5s) to ensure the animation is done.
+        wait-for: 5000
+        assert-css-false: ("#sidebar", {"transform": "matrix(1, 0, 0, 1, -308, 0)"})
+        // The page content should be moved to the right.
+        assert-position: ("#page-wrapper", {"x": |content_indent|})
+    },
+)
+
+call-function: ("hide-sidebar", {})
+call-function: ("show-sidebar", {})
+
+// We now test on smaller width to ensure that the sidebar is collapsed by default.
+set-window-size: (900, 600)
+reload:
+call-function: ("show-sidebar", {})
+call-function: ("hide-sidebar", {})

tests/rendered_output.rs

@@ -3,10 +3,11 @@ mod dummy_book;
 use crate::dummy_book::{assert_contains_strings, assert_doesnt_contain_strings, DummyBook};
 
 use anyhow::Context;
+use mdbook::book::Chapter;
 use mdbook::config::Config;
 use mdbook::errors::*;
 use mdbook::utils::fs::write_file;
-use mdbook::MDBook;
+use mdbook::{BookItem, MDBook};
 use pretty_assertions::assert_eq;
 use select::document::Document;
 use select::predicate::{Attr, Class, Name, Predicate};
@@ -243,7 +244,7 @@ fn toc_js_html() -> Result<Document> {
     let toc_path = temp.path().join("book").join("toc.js");
     let html = fs::read_to_string(toc_path).with_context(|| "Unable to read index.html")?;
     for line in html.lines() {
-        if let Some(left) = line.strip_prefix("sidebarScrollbox.innerHTML = '") {
+        if let Some(left) = line.strip_prefix("        this.innerHTML = '") {
             if let Some(html) = left.strip_suffix("';") {
                 return Ok(Document::from(html));
             }
@@ -544,10 +545,38 @@ fn markdown_options() {
     assert_contains_strings(
         &path,
         &[
-            r##"<sup class="footnote-reference"><a href="#1">1</a></sup>"##,
-            r##"<sup class="footnote-reference"><a href="#word">2</a></sup>"##,
-            r##"<div class="footnote-definition" id="1"><sup class="footnote-definition-label">1</sup>"##,
-            r##"<div class="footnote-definition" id="word"><sup class="footnote-definition-label">2</sup>"##,
+            r##"<sup class="footnote-reference" id="fr-1-1"><a href="#footnote-1">1</a></sup>"##,
+            r##"<sup class="footnote-reference" id="fr-word-1"><a href="#footnote-word">2</a></sup>"##,
+            r##"<sup class="footnote-reference" id="fr-word-2"><a href="#footnote-word">2</a></sup>"##,
+            r##"<hr>
+<ol class="footnote-definition"><li id="footnote-1">
+<p>This is a footnote. <a href="#fr-1-1">↩</a> <a href="#fr-1-2">↩2</a></p>
+</li>
+<li id="footnote-word">
+<p>A longer footnote.
+With multiple lines. <a href="unicode.html">Link to unicode</a>.
+With a reference inside.<sup class="footnote-reference" id="fr-1-2"><a href="#footnote-1">1</a></sup> <a href="#fr-word-1">↩</a> <a href="#fr-word-2">↩2</a></p>
+</li>
+<li id="footnote-para">
+<ol>
+<li>Item one
+<ol>
+<li>Sub-item</li>
+</ol>
+</li>
+<li>Item two</li>
+</ol>
+ <a href="#fr-para-1">↩</a></li>
+<li id="footnote-multiple"><p>One</p><p>Two</p><p>Three</p>
+ <a href="#fr-multiple-1">↩</a></li>
+<li id="footnote-&quot;wacky&quot;">
+<p>Testing footnote id with special characters. <a href="#fr-&quot;wacky&quot;-1">↩</a></p>
+</li>
+<li id="footnote-define-before-use">
+<p>This is defined before it is referred to. <a href="#fr-define-before-use-1">↩</a></p>
+</li>
+</ol>
+"##,
         ],
     );
     assert_contains_strings(&path, &["<del>strikethrough example</del>"]);
@@ -736,6 +765,7 @@ fn failure_on_missing_theme_directory() {
 #[cfg(feature = "search")]
 mod search {
     use crate::dummy_book::DummyBook;
+    use mdbook::utils::fs::write_file;
     use mdbook::MDBook;
     use std::fs::{self, File};
     use std::path::Path;
@@ -810,6 +840,51 @@ mod search {
         );
     }
 
+    #[test]
+    fn can_disable_individual_chapters() {
+        let temp = DummyBook::new().build().unwrap();
+        let book_toml = r#"
+            [book]
+            title = "Search Test"
+
+            [output.html.search.chapter]
+            "second" = { enable = false }
+            "first/unicode.md" = { enable = false }
+            "#;
+        write_file(temp.path(), "book.toml", book_toml.as_bytes()).unwrap();
+        let md = MDBook::load(temp.path()).unwrap();
+        md.build().unwrap();
+        let index = read_book_index(temp.path());
+        let doc_urls = index["doc_urls"].as_array().unwrap();
+        let contains = |path| {
+            doc_urls
+                .iter()
+                .any(|p| p.as_str().unwrap().starts_with(path))
+        };
+        assert!(contains("second.html"));
+        assert!(!contains("second/"));
+        assert!(!contains("first/unicode.html"));
+        assert!(contains("first/markdown.html"));
+    }
+
+    #[test]
+    fn chapter_settings_validation_error() {
+        let temp = DummyBook::new().build().unwrap();
+        let book_toml = r#"
+            [book]
+            title = "Search Test"
+
+            [output.html.search.chapter]
+            "does-not-exist" = { enable = false }
+            "#;
+        write_file(temp.path(), "book.toml", book_toml.as_bytes()).unwrap();
+        let md = MDBook::load(temp.path()).unwrap();
+        let err = md.build().unwrap_err();
+        assert!(format!("{err:?}").contains(
+            "[output.html.search.chapter] key `does-not-exist` does not match any chapter paths"
+        ));
+    }
+
     // Setting this to `true` may cause issues with `cargo watch`,
     // since it may not finish writing the fixture before the tests
     // are run again.
@@ -985,3 +1060,21 @@ fn custom_header_attributes() {
     ];
     assert_contains_strings(&contents, summary_strings);
 }
+
+#[test]
+fn with_no_source_path() {
+    // Test for a regression where search would fail if source_path is None.
+    let temp = DummyBook::new().build().unwrap();
+    let mut md = MDBook::load(temp.path()).unwrap();
+    let chapter = Chapter {
+        name: "Sample chapter".to_string(),
+        content: "".to_string(),
+        number: None,
+        sub_items: Vec::new(),
+        path: Some(PathBuf::from("sample.html")),
+        source_path: None,
+        parent_names: Vec::new(),
+    };
+    md.book.sections.push(BookItem::Chapter(chapter));
+    md.build().unwrap();
+}

triagebot.toml

@@ -21,3 +21,16 @@ allow-unauthenticated = [
 
 [autolabel."S-waiting-on-review"]
 new_pr = true
+
+[merge-conflicts]
+remove = []
+add = ["S-waiting-on-author"]
+unless = ["S-blocked", "S-waiting-on-review"]
+
+[review-submitted]
+reviewed_label = "S-waiting-on-author"
+review_labels = ["S-waiting-on-review"]
+
+[review-requested]
+remove_labels = ["S-waiting-on-author"]
+add_labels = ["S-waiting-on-review"]