Fix typo in changelog

mdbook-compare: fix duplicate "diff" print

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --manifest-path=crates/xtask/Cargo.toml --"

.git-blame-ignore-revs

@@ -0,0 +1,26 @@
+# Use `git config blame.ignorerevsfile .git-blame-ignore-revs` to make `git blame` ignore the following commits.
+
+# rustfmt
+ad0794a0bd692e4f2ff23b85e361889620e93f51
+# rustfmt and use_try_shorthand
+75bbd55128083897d40c3f5265cc5b1f10314ddb
+# rustfmt
+382fc4139b96bde3c4b8875b499c720eabc89c6a
+# rustfmt
+154e0fb3080c6ffc225b0d47b5d835e589789892
+# rustfmt
+5835da243244bfc5c95c6c6db96f453da4bb5740
+# rustfmt
+fd9d27e082f5e9eea50e4fa9fa3a22060d02c66b
+# rustfmt
+1d69ccae4854f13552d452d0bffef95cbff70364
+# rustfmt
+3688f73052454bf510a5acc85cf55aae450c6e46
+# rustfmt
+742dbbc91700dce1b7d910bca6b3e10a5ae46b86
+# rustfmt 1.38
+b88839cc25a6fd1c782101e94318959e8079bb20
+# rustfmt 1.40
+2f59943c04f0aa204a9238d6a699ba9cc06c88d9
+# Rustfmt for 2024
+c7b67e363bb9ce3383636ee615e8e761bf185b33

.gitattributes

@@ -6,3 +6,5 @@
 *.ttf binary
 *.otf binary
 *.png binary
+*.eot binary
+*.woff2 binary

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,45 @@
+name: Bug Report
+description: Create a report to help us improve
+labels: ["C-bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for filing a 🐛 bug report 😄!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: >
+        Please provide a clear and concise description of what the bug is,
+        including what currently happens and what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps
+      description: Please list the steps to reproduce the bug.
+      placeholder: |
+        1.
+        2.
+        3.
+  - type: textarea
+    id: possible-solutions
+    attributes:
+      label: Possible Solution(s)
+      description: >
+        Not obligatory, but suggest a fix/reason for the bug,
+        or ideas how to implement the addition or change.
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Provide any additional notes that might be helpful.
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: >
+        Please paste the output of running `mdbook --version` or which version
+        of the library you are using.
+      render: text

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Enhancement
+description: Suggest an idea for enhancing mdBook
+labels: ["C-enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a 🙋 feature request 😄!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: >
+        Please provide a clear description of your use case and the problem
+        this feature request is trying to solve.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: >
+        Please provide a clear and concise description of what you want to happen.
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Provide any additional context or information that might be helpful.

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,24 @@
+name: Question
+description: Have a question on how to use mdBook?
+labels: ["C-question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Got a question on how to do something with mdBook?
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: >
+        Enter your question here. Please try to provide as much detail as possible.
+    validations:
+      required: true
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: >
+        Please paste the output of running `mdbook --version` or which version
+        of the library you are using.
+      render: text

.github/renovate.json5

@@ -0,0 +1,71 @@
+{
+    schedule: ['before 5am on the first day of the month'],
+    // Raise from default of 2 to reduce trickle.
+    prHourlyLimit: 6,
+    dependencyDashboard: true,
+    // Creates PRs if this renovate config file needs updating.
+    configMigration: true,
+    ignorePaths: [
+        'guide/src/for_developers/mdbook-wordcount/',
+    ],
+    customManagers: [
+        // Custom manager to extract the version of cargo-semver-checks from the workflow.
+        {
+            customType: 'regex',
+            managerFilePatterns: [
+               '/^.github.workflows.main.yml$/',
+            ],
+            matchStrings: [
+                'cargo-semver-checks.releases.download.v(?<currentValue>\\d+\\.\\d+(\\.\\d+)?)',
+            ],
+            depNameTemplate: 'cargo-semver-checks',
+            packageNameTemplate: 'obi1kenobi/cargo-semver-checks',
+            datasourceTemplate: 'github-releases',
+        },
+    ],
+    packageRules: [
+        // The next two rules disable compatible dependency updates. I wasn't
+        // able to get Renovate to be able to update Cargo.toml for compatible
+        // updates only, update all transitive dependencies, and do that all
+        // in a single PR. Instead, the `update-dependencies.sh` will handle
+        // that.
+        {
+            matchManagers: ['cargo'],
+            matchUpdateTypes: ['patch'],
+            enabled: false,
+        },
+        {
+            matchManagers: ['cargo'],
+            matchCurrentVersion: '>=1.0.0',
+            matchUpdateTypes: ['minor'],
+            enabled: false,
+        },
+        // Allow minor updates for pre-1.0 dependencies (semver-breaking)
+        {
+            matchManagers: ['cargo'],
+            matchCurrentVersion: '<1.0.0',
+            matchUpdateTypes: ['minor'],
+        },
+        // Allow major updates for stable dependencies (semver-breaking)
+        {
+            matchManagers: ['cargo'],
+            matchCurrentVersion: '>=1.0.0',
+            matchUpdateTypes: ['major'],
+        },
+        // Update cargo-semver-checks when a new version is available.
+        {
+            commitMessageTopic: 'cargo-semver-checks',
+            matchManagers: [
+                'custom.regex',
+            ],
+            matchDepNames: [
+                'cargo-semver-checks',
+            ],
+            extractVersion: '^v(?<version>\\d+\\.\\d+\\.\\d+)',
+            schedule: [
+                '* * * * *',
+            ],
+            internalChecksFilter: 'strict',
+        },
+    ]
+}

.github/workflows/deploy.yml

@@ -3,37 +3,65 @@ on:
   release:
     types: [created]
 
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: write
+
 jobs:
   release:
-    name: Deploy Release
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-    env:
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        include:
+          - target: aarch64-unknown-linux-musl
+            os: ubuntu-22.04
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-22.04
+          - target: x86_64-unknown-linux-musl
+            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 }}
     steps:
-    - uses: actions/checkout@master
-    - name: Install hub
-      run: ci/install-hub.sh ${{ matrix.os }}
-      shell: bash
-    - name: Install Rustup
-      run: ci/install-rustup.sh stable
-      shell: bash
+    - uses: actions/checkout@v5
     - name: Install Rust
-      run: ci/install-rust.sh stable
-      shell: bash
-    - name: Build and deploy artifacts
-      run: ci/make-release.sh ${{ matrix.os }}
-      shell: bash
+      run: ci/install-rust.sh stable ${{ matrix.target }}
+    - name: Build asset
+      run: ci/make-release-asset.sh ${{ matrix.os }} ${{ matrix.target }}
+    - name: Update release with new asset
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: gh release upload $MDBOOK_TAG $MDBOOK_ASSET
   pages:
     name: GitHub Pages
     runs-on: ubuntu-latest
-    env:
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v5
     - name: Install Rust (rustup)
       run: rustup update stable --no-self-update && rustup default stable
-    - name: Deploy to GitHub Pages
-      run: ci/deploy-gh-pages.sh
+    - name: Deploy the User Guide to GitHub Pages using the gh-pages branch
+      run: ci/publish-guide.sh
+  publish:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for OIDC token exchange
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install Rust (rustup)
+        run: rustup update stable --no-self-update && rustup default stable
+      - name: Authenticate with crates.io
+        id: auth
+        uses: rust-lang/crates-io-auth-action@v1
+      - name: Publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+        run: cargo publish --workspace --no-verify

.github/workflows/main.yml

@@ -1,53 +1,147 @@
 name: CI
 on:
-  # Only run when merging to master, or open/synchronize/reopen a PR.
-  push:
-    branches:
-      - master
   pull_request:
+  merge_group:
 
 jobs:
   test:
-    name: Test
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        build: [stable, beta, nightly, macos, windows, msrv]
         include:
-          - build: stable
+          - name: stable linux
             os: ubuntu-latest
             rust: stable
-          - build: beta
+            target: x86_64-unknown-linux-gnu
+          - name: beta linux
             os: ubuntu-latest
             rust: beta
-          - build: nightly
+            target: x86_64-unknown-linux-gnu
+          - name: nightly linux
             os: ubuntu-latest
             rust: nightly
-          - build: macos
+            target: x86_64-unknown-linux-gnu
+          - name: stable x86_64-unknown-linux-musl
+            os: ubuntu-22.04
+            rust: stable
+            target: x86_64-unknown-linux-musl
+          - name: stable x86_64 macos
             os: macos-latest
             rust: stable
-          - build: windows
+            target: x86_64-apple-darwin
+          - name: stable aarch64 macos
+            os: macos-latest
+            rust: stable
+            target: aarch64-apple-darwin
+          - name: stable windows-msvc
             os: windows-latest
             rust: stable
-          - build: msrv
-            os: ubuntu-latest
-            rust: 1.35.0
+            target: x86_64-pc-windows-msvc
+          - name: msrv
+            os: ubuntu-22.04
+            # sync MSRV with docs: guide/src/guide/installation.md and Cargo.toml
+            rust: 1.88.0
+            target: x86_64-unknown-linux-gnu
+    name: ${{ matrix.name }}
     steps:
-    - uses: actions/checkout@master
-    - name: Install Rustup
-      run: bash ci/install-rustup.sh ${{ matrix.rust }}
+    - uses: actions/checkout@v5
     - name: Install Rust
-      run: bash ci/install-rust.sh ${{ matrix.rust }}
+      run: bash ci/install-rust.sh ${{ matrix.rust }} ${{ matrix.target }}
     - name: Build and run tests
-      run: cargo test
+      run: cargo test --workspace --locked --target ${{ matrix.target }}
     - name: Test no default
-      run: cargo test --no-default-features
+      run: cargo test --workspace --no-default-features --target ${{ matrix.target }}
+
+  aarch64-cross-builds:
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v5
+    - name: Install Rust
+      run: bash ci/install-rust.sh stable aarch64-unknown-linux-musl
+    - name: Build
+      run: cargo build --locked --target aarch64-unknown-linux-musl
 
   rustfmt:
     name: Rustfmt
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v5
     - name: Install Rust
       run: rustup update stable && rustup default stable && rustup component add rustfmt
-    - run: cargo fmt -- --check
+    - run: cargo fmt --check
+
+  gui:
+    name: GUI tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install Rust
+        run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu
+      - name: Install npm
+        uses: actions/setup-node@v5
+        with:
+          node-version: 22
+      - 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
+
+  # Ensure there are no clippy warnings
+  clippy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install Rust
+        run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu
+      - run: rustup component add clippy
+      - run: cargo clippy --workspace --all-targets --no-deps -- -D warnings
+
+  docs:
+    name: Check API docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install Rust
+        run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu
+      - name: Ensure intradoc links are valid
+        run: cargo doc --workspace --document-private-items --no-deps
+        env:
+          RUSTDOCFLAGS: -D warnings
+
+  check-version-bump:
+    name: Check version bump
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - run: rustup update stable && rustup default stable
+      - name: Install cargo-semver-checks
+        run: |
+          mkdir installed-bins
+          curl -Lf https://github.com/obi1kenobi/cargo-semver-checks/releases/download/v0.44.0/cargo-semver-checks-x86_64-unknown-linux-gnu.tar.gz \
+            | tar -xz --directory=./installed-bins
+          echo `pwd`/installed-bins >> $GITHUB_PATH
+      - run: cargo semver-checks --workspace
+
+  # 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
+  # it easier to manage the list of jobs via this yml file and to prevent
+  # accidentally adding new jobs without also updating the branch protections.
+  success:
+    name: Success gate
+    if: always()
+    needs:
+      - test
+      - rustfmt
+      - aarch64-cross-builds
+      - gui
+      - clippy
+      - docs
+      - check-version-bump
+    runs-on: ubuntu-latest
+    steps:
+      - run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}'
+      - name: Done
+        run: exit 0

.github/workflows/update-dependencies.yml

@@ -0,0 +1,20 @@
+name: Update dependencies
+on:
+  schedule:
+    - cron: '0 0 1 * *'
+  workflow_dispatch:
+
+jobs:
+  update:
+    name: Update dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install Rust
+        run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu
+      - name: Install cargo-edit
+        run: cargo install cargo-edit --locked
+      - name: Update dependencies
+        run: ci/update-dependencies.sh
+        env:
+          GH_TOKEN: ${{ github.token }}

.gitignore

@@ -4,10 +4,21 @@ target
 .DS_Store
 
 book-test
-book-example/book
+guide/book
 
 .vscode
 tests/dummy_book/book/
+tests/gui/books/*/book/
+tests/testsuite/*/*/book/
 
 # Ignore Jetbrains specific files.
 .idea/
+
+# Ignore Vim temporary and swap files.
+*.sw?
+*~
+
+# GUI tests
+node_modules
+package-lock.json
+package.json

CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# The Rust Code of Conduct
+
+The Code of Conduct for this repository [can be found online](https://www.rust-lang.org/conduct.html).

CONTRIBUTING.md

@@ -5,35 +5,43 @@ Welcome stranger!
 If you have come here to learn how to contribute to mdBook, we have some tips for you!
 
 First of all, don't hesitate to ask questions!
-Use the [issue tracker](https://github.com/rust-lang-nursery/mdBook/issues), no question is too simple.
-If we don't respond in a couple of days, ping us @Michael-F-Bryan, @budziq, @steveklabnik, @frewsxcv it might just be that we forgot. :wink:
+Use the [issue tracker](https://github.com/rust-lang/mdBook/issues), no question is too simple.
 
-### Issues to work on
+## Issue assignment
 
-Any issue is up for the grabbing, but if you are starting out, you might be interested in the
-[E-Easy issues](https://github.com/rust-lang-nursery/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy).
+**:warning: Important :warning:**
+
+Before working on pull request, please ping us on the corresponding issue.
+The current PR backlog is beyond what we can process at this time.
+Only issues that have an [`E-Help-wanted`](https://github.com/rust-lang/mdBook/labels/E-Help-wanted) or [`Feature accepted`](https://github.com/rust-lang/mdBook/labels/Feature%20accepted) label will likely receive reviews.
+If there isn't already an open issue for what you want to work on, please open one first to see if it is something we would be available to review.
+
+## Issues to work on
+
+If you are starting out, you might be interested in the
+[E-Easy issues](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy).
 Those are issues that are considered more straightforward for beginners to Rust or the codebase itself.
-These issues can be a good launching pad for more involved issues. Easy tasks for a first time contribution
-include documentation improvements, new tests, examples, updating dependencies, etc.
+These issues can be a good launching pad for more involved issues.
+Easy tasks for a first time contribution include documentation improvements, new tests, examples, updating dependencies, etc.
 
 If you come from a web development background, you might be interested in issues related to web technologies tagged
-[A-JavaScript](https://github.com/rust-lang-nursery/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-JavaScript),
-[A-Style](https://github.com/rust-lang-nursery/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Style),
-[A-HTML](https://github.com/rust-lang-nursery/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-HTML) or
-[A-Mobile](https://github.com/rust-lang-nursery/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Mobile).
+[A-JavaScript](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-JavaScript),
+[A-Style](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Style),
+[A-HTML](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-HTML) or
+[A-Mobile](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Mobile).
 
-When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you.
+When you decide you want to work on a specific issue, and it isn't already assigned to someone else, assign the issue to yourself by leaving a comment with the text `@rustbot claim`.
 Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue.
 
 Issues on the issue tracker are categorized with the following labels:
 
 - **A**-prefixed labels state which area of the project an issue relates to.
 - **E**-prefixed labels show an estimate of the experience necessary to fix the issue.
-- **M**-prefixed labels are meta-issues used for questions, discussions, or tracking issues
+- **M**-prefixed labels are meta-issues regarding the management of the mdBook project itself
 - **S**-prefixed labels show the status of the issue
-- **T**-prefixed labels show the type of issue
+- **C**-prefixed labels show the category of issue
 
-### Building mdBook
+## Building mdBook
 
 mdBook builds on stable Rust, if you want to build mdBook from source, here are the steps to follow:
 
@@ -41,26 +49,26 @@ mdBook builds on stable Rust, if you want to build mdBook from source, here are
 0. Clone this repository with git.
 
    ```
-   git clone https://github.com/rust-lang-nursery/mdBook.git
+   git clone https://github.com/rust-lang/mdBook.git
    ```
 0. Navigate into the newly created `mdBook` directory
 0. Run `cargo build`
 
-The resulting binary can be found in `mdBook/target/debug/` under the name `mdBook` or `mdBook.exe`.
+The resulting binary can be found in `mdBook/target/debug/` under the name `mdbook` or `mdbook.exe`.
 
-### Code Quality
+## Code quality
 
 We love code quality and Rust has some excellent tools to assist you with contributions.
 
-#### Formatting Code with rustfmt
+### Formatting code with rustfmt
 
 Before you make your Pull Request to the project, please run it through the `rustfmt` utility.
 This will ensure we have good quality source code that is better for us all to maintain.
 
-[rustfmt](https://github.com/rust-lang-nursery/rustfmt) has a lot more information on the project.
+[rustfmt](https://github.com/rust-lang/rustfmt) has a lot more information on the project.
 The quick guide is
 
-1. Install it
+1. Install it (`rustfmt` is usually installed by default via [rustup](https://rustup.rs/)):
     ```
     rustup component add rustfmt
     ```
@@ -72,18 +80,14 @@ The quick guide is
    ```
    cargo fmt
    ```
-   When run through `cargo` it will format all bin and lib files in the current crate.
+   When run through `cargo` it will format all bin and lib files in the current package.
 
-For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang-nursery/rustfmt)
+For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang/rustfmt)
 
+### Finding issues with clippy
 
-#### Finding Issues with Clippy
-
-Clippy is a code analyser/linter detecting mistakes, and therfore helps to improve your code.
-Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will
-help us maintain awesome code.
-
-The best documentation can be found over at [rust-clippy](https://github.com/rust-lang-nursery/rust-clippy)
+[Clippy](https://doc.rust-lang.org/clippy/) is a code analyser/linter detecting mistakes, and therefore helps to improve your code.
+Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will help us maintain awesome code.
 
 1. To install
     ```
@@ -94,15 +98,143 @@ The best documentation can be found over at [rust-clippy](https://github.com/rus
     cargo clippy
     ```
 
-Clippy has an ever growing list of checks, that are managed in [lint files](https://rust-lang-nursery.github.io/rust-clippy/master/index.html).
+## Change requirements
 
-### Making a pull-request
+Please consider the following when making a change:
+
+* Almost all changes that modify the Rust code must be accompanied with a test.
+
+* Almost all features and changes must update the documentation.
+  mdBook has the [mdBook Guide](https://rust-lang.github.io/mdBook/) whose source is at <https://github.com/rust-lang/mdBook/tree/master/guide>.
+
+* Almost all Rust items should be documented with doc comments.
+  See the [Rustdoc Book](https://doc.rust-lang.org/rustdoc/) for more information on writing doc comments.
+
+* Breaking the API can only be done in major SemVer releases.
+  These are done very infrequently, so it is preferred to avoid these when possible.
+  See [SemVer Compatibility](https://doc.rust-lang.org/cargo/reference/semver.html) for more information on what a SemVer breaking change is.
+
+  (Note: At this time, some SemVer breaking changes are inevitable due to the current code structure.
+  An example is adding new fields to the config structures.
+  These are intended to be fixed in the next major release.)
+
+* Similarly, the CLI interface is considered to be stable.
+  Care should be taken to avoid breaking existing workflows.
+
+* Check out the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) for guidelines on designing the API.
+
+## Tests
+
+The main test harness is described in the [testsuite documentation](tests/testsuite/README.md). There are several different commands to run different kinds of tests:
+
+- `cargo test --workspace` — This runs all of the unit and integration tests, except for the GUI tests.
+- `cargo test --test gui` — This runs the [GUI test harness](#browser-compatibility-and-testing). This does not get run automatically due to its extra requirements.
+- `npm run lint` — [Checks the `.js` files](#checking-changes-in-js-files)
+- `cargo test --workspace --no-default-features` — Testing without default features helps check that all feature checks are implemented correctly.
+- `cargo clippy --workspace --all-targets --no-deps -- -D warnings` — This makes sure that there are no clippy warnings.
+- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --document-private-items --no-deps` — This verifies that there aren't any rustdoc warnings.
+- `cargo fmt --check` — Verifies that everything is formatted correctly.
+- `cargo +stable semver-checks` — Verifies that no SemVer breaking changes have been made. You must install [`cargo-semver-checks`](https://crates.io/crates/cargo-semver-checks) first.
+
+To help simplify running all these commands, you can run the following cargo command:
+
+```sh
+cargo xtask test-all
+```
+
+It is useful to run all tests before submitting a PR. While developing I recommend to run some subset of that command based on what you are working on. There are individual arguments for each one. For example:
+
+```sh
+cargo xtask test-workspace clippy doc eslint fmt gui semver-checks
+```
+
+While developing, remove any of those arguments that are not relevant to what you are changing, or are really slow.
+
+## Making a pull-request
 
 When you feel comfortable that your changes could be integrated into mdBook, you can create a pull-request on GitHub.
 One of the core maintainers will then approve the changes or request some changes before it gets merged.
 
-If you want to make your pull-request even better, you might want to run [Clippy](https://github.com/Manishearth/rust-clippy)
-and [rustfmt](https://github.com/rust-lang-nursery/rustfmt) on the code first.
-This is not a requirement though and will never block a pull-request from being merged.
-
 That's it, happy contributions! :tada: :tada: :tada:
+
+## Browser compatibility and testing
+
+Currently we don't have a strict browser compatibility matrix due to our limited resources.
+We generally strive to keep mdBook compatible with a relatively recent browser on all of the most major platforms.
+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.
+
+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. The books that the tests use are located in the `tests/gui/books` directory. 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
+
+The following are instructions for updating [highlight.js](https://highlightjs.org/).
+
+1. Clone the repository at <https://github.com/highlightjs/highlight.js>
+1. Check out a tagged release (like `10.1.1`).
+1. Run `npm install`
+1. Run `node tools/build.js :common apache armasm coffeescript d handlebars haskell http julia nginx nim nix properties r scala x86asm yaml`
+1. Compare the language list that it spits out to the one in [`syntax-highlighting.md`](https://github.com/camelid/mdBook/blob/master/guide/src/format/theme/syntax-highlighting.md). If any are missing, add them to the list and rebuild (and update these docs). If any are added to the common set, add them to `syntax-highlighting.md`.
+1. Copy `build/highlight.min.js` to mdbook's directory [`highlight.js`](https://github.com/rust-lang/mdBook/blob/master/src/theme/highlight.js).
+1. Be sure to check the highlight.js [CHANGES](https://github.com/highlightjs/highlight.js/blob/main/CHANGES.md) for any breaking changes. Breaking changes that would affect users will need to wait until the next major release.
+1. Build mdbook with the new file and build some books with the new version and compare the output with a variety of languages to see if anything changes. The [syntax GUI test](https://github.com/rust-lang/mdBook/tree/master/tests/gui/books/highlighting) contains a chapter with many languages to examine. Update the test (`highlighting.goml`) to add any new languages.
+
+## Publishing new releases
+
+Instructions for mdBook maintainers to publish a new release:
+
+1. Create a PR that bumps the version and updates the changelog:
+    1. `git fetch upstream`
+    2. `git checkout -B bump-version upstream/master`
+    3. `cargo xtask bump <BUMP>`
+       - This will update the version of all the crates.
+       - `cargo set-version` must first be installed with `cargo install cargo-edit`.
+       - Replace `<BUMP>` with the kind of bump (patch, alpha, etc.)
+    4. `cargo xtask changelog`
+       - This will update `CHANGELOG.md` to add a list of all changes at the top. You will need to move those into the appropriate categories. Most changes that are generally not relevant to a user should be removed. Rewrite the descriptions so that a user can reasonably figure out what it means.
+    5. `git add --update  .`
+    6. `git commit`
+    7. `git push`
+2. After the PR has been merged, create a release in GitHub. This can either be done in the GitHub web UI, or on the command-line:
+   ```bash
+   MDBOOK_VERS="`cargo read-manifest | jq -r .version`" ; \
+    gh release create -R rust-lang/mdbook v$MDBOOK_VERS \
+        --title v$MDBOOK_VERS \
+        --notes "See https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#mdbook-${MDBOOK_VERS//.} for a complete list of changes."
+   ```

Cargo.toml

@@ -1,67 +1,157 @@
+[workspace]
+members = [
+    ".",
+    "crates/*",
+    "examples/remove-emphasis/mdbook-remove-emphasis", "guide/guide-helper",
+]
+
+[workspace.lints.clippy]
+all = { level = "allow", priority = -2 }
+correctness = { level = "warn", priority = -1 }
+complexity = { level = "warn", priority = -1 }
+exhaustive_enums = "warn"
+exhaustive_structs = "warn"
+manual_non_exhaustive = "warn"
+
+[workspace.lints.rust]
+missing_docs = "warn"
+rust_2018_idioms = "warn"
+unreachable_pub = "warn"
+
+[workspace.package]
+edition = "2024"
+license = "MPL-2.0"
+repository = "https://github.com/rust-lang/mdBook"
+rust-version = "1.88.0" # Keep in sync with installation.md and .github/workflows/main.yml
+
+[workspace.dependencies]
+anyhow = "1.0.100"
+axum = "0.8.6"
+clap = { version = "4.5.50", features = ["cargo", "wrap_help"] }
+clap_complete = "4.5.59"
+ego-tree = "0.10.0"
+elasticlunr-rs = "3.0.2"
+font-awesome-as-a-crate = "0.3.0"
+futures-util = "0.3.31"
+glob = "0.3.3"
+handlebars = "6.3.2"
+hex = "0.4.3"
+html5ever = "0.35.0"
+indexmap = "2.12.0"
+ignore = "0.4.24"
+mdbook-core = { path = "crates/mdbook-core", version = "0.5.0-beta.1" }
+mdbook-driver = { path = "crates/mdbook-driver", version = "0.5.0-beta.1" }
+mdbook-html = { path = "crates/mdbook-html", version = "0.5.0-beta.1" }
+mdbook-markdown = { path = "crates/mdbook-markdown", version = "0.5.0-beta.1" }
+mdbook-preprocessor = { path = "crates/mdbook-preprocessor", version = "0.5.0-beta.1" }
+mdbook-renderer = { path = "crates/mdbook-renderer", version = "0.5.0-beta.1" }
+mdbook-summary = { path = "crates/mdbook-summary", version = "0.5.0-beta.1" }
+memchr = "2.7.6"
+notify = "8.2.0"
+notify-debouncer-mini = "0.7.0"
+opener = "0.8.3"
+pathdiff = "0.2.3"
+pulldown-cmark = { version = "0.13.0", default-features = false, features = ["html"] } # Do not update, part of the public api.
+regex = "1.12.2"
+select = "0.6.1"
+semver = "1.0.27"
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.145"
+sha2 = "0.10.9"
+shlex = "1.3.0"
+snapbox = "0.6.22"
+tempfile = "3.23.0"
+tokio = "1.48.0"
+toml = "0.9.8"
+topological-sort = "0.2.2"
+tower-http = "0.6.6"
+tracing = "0.1.41"
+tracing-subscriber = { version = "0.3.20", features = ["env-filter"] }
+walkdir = "2.5.0"
+
 [package]
 name = "mdbook"
-version = "0.3.2"
+version = "0.5.0-beta.1"
 authors = [
     "Mathieu David <mathieudavid@mathieudavid.org>",
     "Michael-F-Bryan <michaelfbryan@gmail.com>",
     "Matt Ickstadt <mattico8@gmail.com>"
 ]
-documentation = "http://rust-lang-nursery.github.io/mdBook/index.html"
-edition = "2018"
-exclude = ["/book-example/*"]
+documentation = "https://rust-lang.github.io/mdBook/index.html"
+edition.workspace = true
+exclude = ["/guide/*"]
 keywords = ["book", "gitbook", "rustbook", "markdown"]
-license = "MPL-2.0"
+license.workspace = true
 readme = "README.md"
-repository = "https://github.com/rust-lang-nursery/mdBook"
+repository.workspace = true
 description = "Creates a book from markdown files"
+rust-version.workspace = true
 
 [dependencies]
-chrono = "0.4"
-clap = "2.24"
-env_logger = "0.6"
-error-chain = "0.12"
-handlebars = { version = "2.0", default-features = false, features = ["no_dir_source"] }
-itertools = "0.8"
-lazy_static = "1.0"
-log = "0.4"
-memchr = "2.0"
-open = "1.1"
-pulldown-cmark = "0.5"
-regex = "1.0.0"
-serde = "1.0"
-serde_derive = "1.0"
-serde_json = "1.0"
-shlex = "0.1"
-tempfile = "3.0"
-toml = "0.5.1"
-toml-query = "0.9"
+anyhow.workspace = true
+clap.workspace = true
+clap_complete.workspace = true
+mdbook-core.workspace = true
+mdbook-driver.workspace = true
+mdbook-html.workspace = true
+mdbook-markdown.workspace = true
+mdbook-preprocessor.workspace = true
+mdbook-renderer.workspace = true
+mdbook-summary.workspace = true
+opener.workspace = true
+toml.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
 
 # Watch feature
-notify = { version = "4.0", optional = true }
-gitignore = { version = "1.0", optional = true }
+ignore = { workspace = true, optional = true }
+notify = { workspace = true, optional = true }
+notify-debouncer-mini = { workspace = true, optional = true }
+pathdiff = { workspace = true, optional = true }
+walkdir = { workspace = true, optional = true }
 
 # Serve feature
-iron = { version = "0.6", optional = true }
-staticfile = { version = "0.5", optional = true }
-ws = { version = "0.9", optional = true}
-
-# Search feature
-elasticlunr-rs = { version = "2.3", optional = true, default-features = false }
-ammonia = { version = "3", optional = true }
+axum = { workspace = true, features = ["ws"], optional = true }
+futures-util = { workspace = true, optional = true }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"], optional = true }
+tower-http = { workspace = true, features = ["fs", "trace"], optional = true }
 
 [dev-dependencies]
-select = "0.4"
-pretty_assertions = "0.6"
-walkdir = "2.0"
+glob.workspace = true
+regex.workspace = true
+select.workspace = true
+semver.workspace = true
+serde_json.workspace = true
+snapbox = { workspace = true, features = ["diff", "dir", "term-svg", "regex", "json"] }
+tempfile.workspace = true
+walkdir.workspace = true
 
 [features]
-default = ["output", "watch", "serve", "search"]
-debug = []
-output = []
-watch = ["notify", "gitignore"]
-serve = ["iron", "staticfile", "ws"]
-search = ["elasticlunr-rs", "ammonia"]
+default = ["watch", "serve", "search"]
+watch = ["dep:notify", "dep:notify-debouncer-mini", "dep:ignore", "dep:pathdiff", "dep:walkdir"]
+serve = ["dep:futures-util", "dep:tokio", "dep:axum", "dep:tower-http"]
+search = ["mdbook-html/search"]
 
 [[bin]]
 doc = false
 name = "mdbook"
+
+[[example]]
+name = "nop-preprocessor"
+test = true
+
+[[example]]
+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"]
+
+[lints]
+workspace = true

README.md

@@ -1,230 +1,20 @@
 # mdBook
 
-[![Build Status](https://github.com/rust-lang-nursery/mdBook/workflows/CI/badge.svg)](https://github.com/rust-lang-nursery/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-nursery/mdBook.svg)](LICENSE)
+[![LICENSE](https://img.shields.io/github/license/rust-lang/mdBook.svg)](LICENSE)
 
 mdBook is a utility to create modern online books from Markdown files.
 
+Check out the **[User Guide]** for a list of features and installation and usage information.
+The User Guide also serves as a demonstration to showcase what a book looks like.
 
-## What does it look like?
-
-The [User Guide] for mdBook has been written in Markdown and is using mdBook to
-generate the online book-like website you can read. The documentation uses the
-latest version on GitHub and showcases the available features.
-
-## Installation
-
-There are multiple ways to install mdBook.
-
-1. **Binaries**
-
-   Binaries are available for download [here][releases]. Make sure to put the
-   path to the binary into your `PATH`.
-
-2. **From Crates.io**
-
-   This requires at least [Rust] 1.35 and Cargo to be installed. Once you have installed
-   Rust, type the following in the terminal:
-
-   ```
-   cargo install mdbook
-   ```
-
-   This will download and compile mdBook for you, the only thing left to do is
-   to add the Cargo bin directory to your `PATH`.
-
-   **Note for automatic deployment**
-
-   If you are using a script to do automatic deployments using Travis or
-   another CI server, we recommend that you specify a semver version range for
-   mdBook when you install it through your script!
-
-   This will constrain the server to install the latest **non-breaking**
-   version of mdBook and will prevent your books from failing to build because
-   we released a new version. For example:
-
-   ```
-   cargo install mdbook --vers "^0.1.0"
-   ```
-
-3. **From Git**
-
-   The version published to crates.io will ever so slightly be behind the
-   version hosted here on GitHub. If you need the latest version you can build
-   the git version of mdBook yourself. Cargo makes this ***super easy***!
-
-   ```
-   cargo install --git https://github.com/rust-lang-nursery/mdBook.git mdbook
-   ```
-
-   Again, make sure to add the Cargo bin directory to your `PATH`.
-
-4. **For Contributions**
-
-   If you want to contribute to mdBook you will have to clone the repository on
-   your local machine:
-
-   ```
-   git clone https://github.com/rust-lang-nursery/mdBook.git
-   ```
-
-   `cd` into `mdBook/` and run
-
-   ```
-   cargo build
-   ```
-
-   The resulting binary can be found in `mdBook/target/debug/` under the name
-   `mdBook` or `mdBook.exe`.
-
-
-## Usage
-
-mdBook will primarily be used as a command line tool, even though it exposes
-all its functionality as a Rust crate for integration in other projects.
-
-Here are the main commands you will want to run. For a more exhaustive
-explanation, check out the [User Guide].
-
-- `mdbook init`
-
-    The init command will create a directory with the minimal boilerplate to
-    start with.
-
-    ```
-    book-test/
-    ├── book
-    └── src
-        ├── chapter_1.md
-        └── SUMMARY.md
-    ```
-
-    `book` and `src` are both directories. `src` contains the markdown files
-    that will be used to render the output to the `book` directory.
-
-    Please, take a look at the [CLI docs] for more information and some neat tricks.
-
-- `mdbook build`
-
-    This is the command you will run to render your book, it reads the
-    `SUMMARY.md` file to understand the structure of your book, takes the
-    markdown files in the source directory as input and outputs static html
-    pages that you can upload to a server.
-
-- `mdbook watch`
-
-    When you run this command, mdbook will watch your markdown files to rebuild
-    the book on every change. This avoids having to come back to the terminal
-    to type `mdbook build` over and over again.
-
-- `mdbook serve`
-
-    Does the same thing as `mdbook watch` but additionally serves the book at
-    `http://localhost:3000` (port is changeable) and reloads the browser when a
-    change occurs.
-
-- `mdbook clean`
-
-    Delete directory in which generated book is located.
-
-### 3rd Party Plugins
-
-The way a book is loaded and rendered can be configured by the user via third
-party plugins. These plugins are just programs which will be invoked during the
-build process and are split into roughly two categories, *preprocessors* and
-*renderers*.
-
-Preprocessors are used to transform a book before it is sent to a renderer.
-One example would be to replace all occurrences of
-`{{#include some_file.ext}}` with the contents of that file. Some existing
-preprocessors are:
-
-- `index` - a built-in preprocessor (enabled by default) which will transform
-  all `README.md` chapters to `index.md` so `foo/README.md` can be accessed via
-  the url `foo/` when published to a browser
-- `links` - a built-in preprocessor (enabled by default) for expanding the
-  `{{# playpen}}` and `{{# include}}` helpers in a chapter.
-
-Renderers are given the final book so they can do something with it. This is
-typically used for, as the name suggests, rendering the document in a particular
-format, however there's nothing stopping a renderer from doing static analysis
-of a book in order to validate links or run tests. Some existing renderers are:
-
-- `html` - the built-in renderer which will generate a HTML version of the book
-- `markdown` - the built-in renderer (disabled by default) which will run
-  preprocessors then output the resulting Markdown. Useful for debugging
-  preprocessors.
-- [`linkcheck`] - a backend which will check that all links are valid
-- [`epub`] - an experimental EPUB generator
-
-> **Note for Developers:** Feel free to send us a PR if you've developed your
-> own plugin and want it mentioned here.
-
-A preprocessor or renderer is enabled by installing the appropriate program and
-then mentioning it in the book's `book.toml` file.
-
-```console
-$ cargo install mdbook-linkcheck
-$ edit book.toml && cat book.toml
-[book]
-title = "My Awesome Book"
-authors = ["Michael-F-Bryan"]
-
-[output.html]
-
-[output.linkcheck]  # enable the "mdbook-linkcheck" renderer
-
-$ mdbook build
-2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
-2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
-2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend
-```
-
-For more information on the plugin system, consult the [User Guide].
-
-### As a library
-
-Aside from the command line interface, this crate can also be used as a
-library. This means that you could integrate it in an existing project, like a
-web-app for example. Since the command line interface is just a wrapper around
-the library functionality, when you use this crate as a library you have full
-access to all the functionality of the command line interface with an easy to
-use API and more!
-
-See the [User Guide] and the [API docs] for more information.
-
-## Contributions
-
-Contributions are highly appreciated and encouraged! Don't hesitate to
-participate to discussions in the issues, propose new features and ask for
-help.
-
-If you are just starting out with Rust, there are a series of issus that are
-tagged [E-Easy] and **we will gladly mentor you** so that you can successfully
-go through the process of fixing a bug or adding a new feature! Let us know if
-you need any help.
-
-For more info about contributing, check out our [contribution guide] who helps
-you go through the build and contribution process!
-
-There is also a [rendered version][master-docs] of the latest API docs
-available, for those hacking on `master`.
-
+If you are interested in contributing to the development of mdBook, check out the [Contribution Guide].
 
 ## License
 
 All the code in this repository is released under the ***Mozilla Public License v2.0***, for more information take a look at the [LICENSE] file.
 
-
-[User Guide]: https://rust-lang-nursery.github.io/mdBook/
-[API docs]: https://docs.rs/mdbook/*/mdbook/
-[E-Easy]: https://github.com/rust-lang-nursery/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy
-[contribution guide]: https://github.com/rust-lang-nursery/mdBook/blob/master/CONTRIBUTING.md
-[LICENSE]: https://github.com/rust-lang-nursery/mdBook/blob/master/LICENSE
-[releases]: https://github.com/rust-lang-nursery/mdBook/releases
-[Rust]: https://www.rust-lang.org/
-[CLI docs]: http://rust-lang-nursery.github.io/mdBook/cli/init.html
-[master-docs]: http://rust-lang-nursery.github.io/mdBook/
-[`linkcheck`]: https://crates.io/crates/mdbook-linkcheck
-[`epub`]: https://crates.io/crates/mdbook-epub
+[User Guide]: https://rust-lang.github.io/mdBook/
+[contribution guide]: https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md
+[LICENSE]: https://github.com/rust-lang/mdBook/blob/master/LICENSE

book-example/book.toml

@@ -1,21 +0,0 @@
-[book]
-title = "mdBook Documentation"
-description = "Create book from markdown files. Like Gitbook but implemented in Rust"
-authors = ["Mathieu David", "Michael-F-Bryan"]
-language = "en"
-
-[output.html]
-mathjax-support = true
-
-[output.html.playpen]
-editable = true
-line-numbers = true
-
-[output.html.search]
-limit-results = 20
-use-boolean-and = true
-boost-title = 2
-boost-hierarchy = 2
-boost-paragraph = 1
-expand = true
-heading-split-level = 2

book-example/src/README.md

@@ -1,25 +0,0 @@
-# mdBook
-
-**mdBook** is a command line tool and Rust crate to create books using Markdown
-files. It's very similar to Gitbook but written in
-[Rust](http://www.rust-lang.org).
-
-What you are reading serves as an example of the output of mdBook and at the
-same time as a high-level documentation.
-
-mdBook is free and open source, you can find the source code on
-[GitHub](https://github.com/rust-lang-nursery/mdBook). Issues and feature
-requests can be posted on the [GitHub issue
-tracker](https://github.com/rust-lang-nursery/mdBook/issues).
-
-## API docs
-
-Alongside this book you can also read the [API
-docs](https://docs.rs/mdbook/*/mdbook/) generated by Rustdoc if you would like
-to use mdBook as a crate or write a new renderer and need a more low-level
-overview.
-
-## License
-
-mdBook, all the source code, is released under the [Mozilla Public License
-v2.0](https://www.mozilla.org/MPL/2.0/).

book-example/src/SUMMARY.md

@@ -1,27 +0,0 @@
-# Summary
-
-- [mdBook](README.md)
-- [Command Line Tool](cli/README.md)
-    - [init](cli/init.md)
-    - [build](cli/build.md)
-    - [watch](cli/watch.md)
-    - [serve](cli/serve.md)
-    - [test](cli/test.md)
-    - [clean](cli/clean.md)
-- [Format](format/README.md)
-    - [SUMMARY.md](format/summary.md)
-    - [Configuration](format/config.md)
-    - [Theme](format/theme/README.md)
-        - [index.hbs](format/theme/index-hbs.md)
-        - [Syntax highlighting](format/theme/syntax-highlighting.md)
-        - [Editor](format/theme/editor.md)
-    - [MathJax Support](format/mathjax.md)
-    - [mdBook specific features](format/mdbook.md)
-- [Continuous Integration](continuous-integration.md)
-- [For Developers](for_developers/README.md)
-    - [Preprocessors](for_developers/preprocessors.md)
-    - [Alternative Backends](for_developers/backends.md)
-
------------
-
-[Contributors](misc/contributors.md)

book-example/src/cli/README.md

@@ -1,55 +0,0 @@
-# Command Line Tool
-
-mdBook can be used either as a command line tool or a [Rust
-crate](https://crates.io/crates/mdbook). Let's focus on the command line tool
-capabilities first.
-
-## Install From Binaries
-
-Precompiled binaries are provided for major platforms on a best-effort basis.
-Visit [the releases page](https://github.com/rust-lang-nursery/mdBook/releases)
-to download the appropriate version for your platform.
-
-## Install From Source
-
-mdBook can also be installed from source
-
-### Pre-requisite
-
-mdBook is written in **[Rust](https://www.rust-lang.org/)** and therefore needs
-to be compiled with **Cargo**. If you haven't already installed Rust, please go
-ahead and [install it](https://www.rust-lang.org/tools/install) now.
-
-### Install Crates.io version
-
-Installing mdBook is relatively easy if you already have Rust and Cargo
-installed. You just have to type this snippet in your terminal:
-
-```bash
-cargo install mdbook
-```
-
-This will fetch the source code for the latest release from
-[Crates.io](https://crates.io/) and compile it. You will have to add Cargo's
-`bin` directory to your `PATH`.
-
-Run `mdbook help` in your terminal to verify if it works. Congratulations, you
-have installed mdBook!
-
-
-### Install Git version
-
-The **[git version](https://github.com/rust-lang-nursery/mdBook)** contains all
-the latest bug-fixes and features, that will be released in the next version on
-**Crates.io**, if you can't wait until the next release. You can build the git
-version yourself. Open your terminal and navigate to the directory of you
-choice. We need to clone the git repository and then build it with Cargo.
-
-```bash
-git clone --depth=1 https://github.com/rust-lang-nursery/mdBook.git
-cd mdBook
-cargo build --release
-```
-
-The executable `mdbook` will be in the `./target/release` folder, this should be
-added to the path.

book-example/src/cli/serve.md

@@ -1,48 +0,0 @@
-# The serve command
-
-The serve command is used to preview a book by serving it over HTTP at
-`localhost:3000` by default. Additionally it watches the book's directory for
-changes, rebuilding the book and refreshing clients for each change. A websocket
-connection is used to trigger the client-side refresh.
-
-***Note:*** *The `serve` command is for testing a book's HTML output, and is not
-intended to be a complete HTTP server for a website.*
-
-#### Specify a directory
-
-The `serve` command can take a directory as an argument to use as the book's
-root instead of the current working directory.
-
-```bash
-mdbook serve path/to/book
-```
-
-#### Server options
-
-`serve` has four options: the HTTP port, the WebSocket port, the HTTP hostname
-to listen on, and the hostname for the browser to connect to for WebSockets.
-
-For example: suppose you have an nginx server for SSL termination which has a
-public address of 192.168.1.100 on port 80 and proxied that to 127.0.0.1 on port
-8000\. To run use the nginx proxy do:
-
-```bash
-mdbook serve path/to/book -p 8000 -n 127.0.0.1 --websocket-hostname 192.168.1.100
-```
-
-If you were to want live reloading for this you would need to proxy the
-websocket calls through nginx as well from `192.168.1.100:<WS_PORT>` to
-`127.0.0.1:<WS_PORT>`. The `-w` flag allows for the websocket port to be
-configured.
-
-#### --open
-
-When you use the `--open` (`-o`) flag, mdbook will open the book in your
-default web browser after starting the server.
-
-#### --dest-dir
-
-The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. Relative paths are interpreted relative to the book's root directory. If
-not specified it will default to the value of the `build.build-dir` key in
-`book.toml`, or to `./book`.

book-example/src/cli/watch.md

@@ -1,27 +0,0 @@
-# The watch command
-
-The `watch` command is useful when you want your book to be rendered on every
-file change. You could repeatedly issue `mdbook build` every time a file is
-changed. But using `mdbook watch` once will watch your files and will trigger a
-build automatically whenever you modify a file.
-
-#### Specify a directory
-
-The `watch` command can take a directory as an argument to use as the book's
-root instead of the current working directory.
-
-```bash
-mdbook watch path/to/book
-```
-
-#### --open
-
-When you use the `--open` (`-o`) option, mdbook will open the rendered book in
-your default web browser.
-
-#### --dest-dir
-
-The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. Relative paths are interpreted relative to the book's root directory. If
-not specified it will default to the value of the `build.build-dir` key in
-`book.toml`, or to `./book`.

book-example/src/continuous-integration.md

@@ -1,89 +0,0 @@
-# Running `mdbook` in Continuous Integration
-
-While the following examples use Travis CI, their principles should
-straightforwardly transfer to other continuous integration providers as well.
-
-## Ensuring Your Book Builds and Tests Pass
-
-Here is a sample Travis CI `.travis.yml` configuration that ensures `mdbook
-build` and `mdbook test` run successfully. The key to fast CI turnaround times
-is caching `mdbook` installs, so that you aren't compiling `mdbook` on every CI
-run.
-
-```yaml
-language: rust
-sudo: false
-
-cache:
-  - cargo
-
-rust:
-  - stable
-
-before_script:
-  - (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update)
-  - (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.3" mdbook)
-  - cargo install-update -a
-
-script:
-  - mdbook build path/to/mybook && mdbook test path/to/mybook
-```
-
-## Deploying Your Book to GitHub Pages
-
-Following these instructions will result in your book being published to GitHub
-pages after a successful CI run on your repository's `master` branch.
-
-First, create a new GitHub "Personal Access Token" with the "public_repo"
-permissions (or "repo" for private repositories). Go to your repository's Travis
-CI settings page and add an environment variable named `GITHUB_TOKEN` that is
-marked secure and *not* shown in the logs.
-
-Then, append this snippet to your `.travis.yml` and update the path to the
-`book` directory:
-
-```yaml
-deploy:
-  provider: pages
-  skip-cleanup: true
-  github-token: $GITHUB_TOKEN
-  local-dir: path/to/mybook/book
-  keep-history: false
-  on:
-    branch: master
-```
-
-That's it!
-
-### Deploying to GitHub Pages manually
-
-If your CI doesn't support GitHub pages, or you're deploying somewhere else
-with integrations such as Github Pages:
- *note: you may want to use different tmp dirs*:
-
-```console
-$> git worktree add /tmp/book gh-pages
-$> mdbook build
-$> rm -rf /tmp/book/* # this won't delete the .git directory
-$> cp -rp book/* /tmp/book/
-$> cd /tmp/book
-$> git add -A
-$> git commit 'new book message'
-$> git push origin gh-pages
-$> cd -
-```
-
-Or put this into a Makefile rule:
-
-```makefile
-.PHONY: deploy
-deploy: book
-	@echo "====> deploying to github"
-	git worktree add /tmp/book gh-pages
-	rm -rf /tmp/book/*
-	cp -rp book/* /tmp/book/
-	cd /tmp/book && \
-		git add -A && \
-		git commit -m "deployed on $(shell date) by ${USER}" && \
-		git push origin gh-pages
-```

book-example/src/for_developers/preprocessors.md

@@ -1,115 +0,0 @@
-# Preprocessors
-
-A *preprocessor* is simply a bit of code which gets run immediately after the
-book is loaded and before it gets rendered, allowing you to update and mutate
-the book. Possible use cases are:
-
-- Creating custom helpers like `\{{#include /path/to/file.md}}`
-- Updating links so `[some chapter](some_chapter.md)` is automatically changed
-  to `[some chapter](some_chapter.html)` for the HTML renderer
-- Substituting in latex-style expressions (`$$ \frac{1}{3} $$`) with their
-  mathjax equivalents
-
-
-## Hooking Into MDBook
-
-MDBook uses a fairly simple mechanism for discovering third party plugins.
-A new table is added to `book.toml` (e.g. `preprocessor.foo` for the `foo`
-preprocessor) and then `mdbook` will try to invoke the `mdbook-foo` program as
-part of the build process.
-
-While preprocessors can be hard-coded to specify which backend it should be run
-for (e.g. it doesn't make sense for MathJax to be used for non-HTML renderers)
-with the `preprocessor.foo.renderer` key.
-
-```toml
-[book]
-title = "My Book"
-authors = ["Michael-F-Bryan"]
-
-[preprocessor.foo]
-# The command can also be specified manually
-command = "python3 /path/to/foo.py"
-# Only run the `foo` preprocessor for the HTML and EPUB renderer
-renderer = ["html", "epub"]
-```
-
-In typical unix style, all inputs to the plugin will be written to `stdin` as
-JSON and `mdbook` will read from `stdout` if it is expecting output.
-
-The easiest way to get started is by creating your own implementation of the
-`Preprocessor` trait (e.g. in `lib.rs`) and then creating a shell binary which
-translates inputs to the correct `Preprocessor` method. For convenience, there
-is [an example no-op preprocessor] in the `examples/` directory which can easily
-be adapted for other preprocessors.
-
-<details>
-<summary>Example no-op preprocessor</summary>
-
-```rust
-// nop-preprocessors.rs
-
-{{#include ../../../examples/nop-preprocessor.rs}}
-```
-</details>
-
-## Hints For Implementing A Preprocessor
-
-By pulling in `mdbook` as a library, preprocessors can have access to the
-existing infrastructure for dealing with books.
-
-For example, a custom preprocessor could use the
-[`CmdPreprocessor::parse_input()`] function to deserialize the JSON written to
-`stdin`. Then each chapter of the `Book` can be mutated in-place via
-[`Book::for_each_mut()`], and then written to `stdout` with the `serde_json`
-crate.
-
-Chapters can be accessed either directly (by recursively iterating over
-chapters) or via the `Book::for_each_mut()` convenience method.
-
-The `chapter.content` is just a string which happens to be markdown. While it's
-entirely possible to use regular expressions or do a manual find & replace,
-you'll probably want to process the input into something more computer-friendly.
-The [`pulldown-cmark`][pc] crate implements a production-quality event-based
-Markdown parser, with the [`pulldown-cmark-to-cmark`][pctc] allowing you to
-translate events back into markdown text.
-
-The following code block shows how to remove all emphasis from markdown,
-without accidentally breaking the document.
-
-```rust
-fn remove_emphasis(
-    num_removed_items: &mut usize,
-    chapter: &mut Chapter,
-) -> Result<String> {
-    let mut buf = String::with_capacity(chapter.content.len());
-
-    let events = Parser::new(&chapter.content).filter(|e| {
-        let should_keep = match *e {
-            Event::Start(Tag::Emphasis)
-            | Event::Start(Tag::Strong)
-            | Event::End(Tag::Emphasis)
-            | Event::End(Tag::Strong) => false,
-            _ => true,
-        };
-        if !should_keep {
-            *num_removed_items += 1;
-        }
-        should_keep
-    });
-
-    cmark(events, &mut buf, None).map(|_| buf).map_err(|err| {
-        Error::from(format!("Markdown serialization failed: {}", err))
-    })
-}
-```
-
-For everything else, have a look [at the complete example][example].
-
-[preprocessor-docs]: https://docs.rs/mdbook/latest/mdbook/preprocess/trait.Preprocessor.html
-[pc]: https://crates.io/crates/pulldown-cmark
-[pctc]: https://crates.io/crates/pulldown-cmark-to-cmark
-[example]: https://github.com/rust-lang-nursery/mdBook/blob/master/examples/nop-preprocessor.rs
-[an example no-op preprocessor]: https://github.com/rust-lang-nursery/mdBook/blob/master/examples/nop-preprocessor.rs
-[`CmdPreprocessor::parse_input()`]: https://docs.rs/mdbook/latest/mdbook/preprocess/trait.Preprocessor.html#method.parse_input
-[`Book::for_each_mut()`]: https://docs.rs/mdbook/latest/mdbook/book/struct.Book.html#method.for_each_mut

book-example/src/format/config.md

@@ -1,333 +0,0 @@
-# Configuration
-
-You can configure the parameters for your book in the ***book.toml*** file.
-
-Here is an example of what a ***book.toml*** file might look like:
-
-```toml
-[book]
-title = "Example book"
-author = "John Doe"
-description = "The example book covers examples."
-
-[build]
-build-dir = "my-example-book"
-create-missing = false
-
-[preprocessor.index]
-
-[preprocessor.links]
-
-[output.html]
-additional-css = ["custom.css"]
-
-[output.html.search]
-limit-results = 15
-```
-
-## Supported configuration options
-
-It is important to note that **any** relative path specified in the
-configuration will always be taken relative from the root of the book where the
-configuration file is located.
-
-### General metadata
-
-This is general information about your book.
-
-- **title:** The title of the book
-- **authors:** The author(s) of the book
-- **description:** A description for the book, which is added as meta
-  information in the html `<head>` of each page
-- **src:** By default, the source directory is found in the directory named
-  `src` directly under the root folder. But this is configurable with the `src`
-  key in the configuration file.
-- **language:** The main language of the book, which is used as a language attribute `<html lang="en">` for example.
-
-**book.toml**
-```toml
-[book]
-title = "Example book"
-authors = ["John Doe", "Jane Doe"]
-description = "The example book covers examples."
-src = "my-src"  # the source files will be found in `root/my-src` instead of `root/src`
-language = "en"
-```
-
-### Build options
-
-This controls the build process of your book.
-
-- **build-dir:** The directory to put the rendered book in. By default this is
-  `book/` in the book's root directory.
-- **create-missing:** By default, any missing files specified in `SUMMARY.md`
-  will be created when the book is built (i.e. `create-missing = true`). If this
-  is `false` then the build process will instead exit with an error if any files
-  do not exist.
-- **use-default-preprocessors:** Disable the default preprocessors of (`links` &
-  `index`) by setting this option to `false`.
-
-  If you have the same, and/or other preprocessors declared via their table
-  of configuration, they will run instead.
-
-  - For clarity, with no preprocessor configuration, the default `links` and
-    `index` will run.
-  - Setting `use-default-preprocessors = false` will disable these
-    default preprocessors from running.
-  - Adding `[preprocessor.links]`, for example, will ensure, regardless of
-    `use-default-preprocessors` that `links` it will run.
-
-## Configuring Preprocessors
-
-The following preprocessors are available and included by default:
-
-- `links`: Expand the `{{ #playpen }}`, `{{ #include }}`, and `{{ #rustdoc_include }}` handlebars
-  helpers in a chapter to include the contents of a file.
-- `index`: Convert all chapter files named `README.md` into `index.md`. That is
-  to say, all `README.md` would be rendered to an index file `index.html` in the
-  rendered book.
-
-
-**book.toml**
-```toml
-[build]
-build-dir = "build"
-create-missing = false
-
-[preprocessor.links]
-
-[preprocessor.index]
-```
-
-### Custom Preprocessor Configuration
-
-Like renderers, preprocessor will need to be given its own table (e.g.
-`[preprocessor.mathjax]`). In the section, you may then pass extra
-configuration to the preprocessor by adding key-value pairs to the table.
-
-For example
-
-```toml
-[preprocessor.links]
-# set the renderers this preprocessor will run for
-renderers = ["html"]
-some_extra_feature = true
-```
-
-#### Locking a Preprocessor dependency to a renderer
-
-You can explicitly specify that a preprocessor should run for a renderer by
-binding the two together.
-
-```toml
-[preprocessor.mathjax]
-renderers = ["html"]  # mathjax only makes sense with the HTML renderer
-```
-
-### Provide Your Own Command
-
-By default when you add a `[preprocessor.foo]` table to your `book.toml` file,
-`mdbook` will try to invoke the `mdbook-foo` executable. If you want to use a
-different program name or pass in command-line arguments, this behaviour can
-be overridden by adding a `command` field.
-
-```toml
-[preprocessor.random]
-command = "python random.py"
-```
-
-## Configuring Renderers
-
-### HTML renderer options
-
-The HTML renderer has a couple of options as well. All the options for the
-renderer need to be specified under the TOML table `[output.html]`.
-
-The following configuration options are available:
-
-- **theme:** mdBook comes with a default theme and all the resource files needed
-  for it. But if this option is set, mdBook will selectively overwrite the theme
-  files with the ones found in the specified folder.
-- **default-theme:** The theme color scheme to select by default in the
-  'Change Theme' dropdown. Defaults to `light`.
-- **preferred-dark-theme:** The default dark theme. This theme will be used if
-  the browser requests the dark version of the site via the
-  ['prefers-color-scheme'](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
-  CSS media query. Defaults to the same theme as `default-theme`.
-- **curly-quotes:** Convert straight quotes to curly quotes, except for those
-  that occur in code blocks and code spans. Defaults to `false`.
-- **mathjax-support:** Adds support for [MathJax](mathjax.md). Defaults to
-  `false`.
-- **google-analytics:** If you use Google Analytics, this option lets you enable
-  it by simply specifying your ID in the configuration file.
-- **additional-css:** If you need to slightly change the appearance of your book
-  without overwriting the whole style, you can specify a set of stylesheets that
-  will be loaded after the default ones where you can surgically change the
-  style.
-- **additional-js:** If you need to add some behaviour to your book without
-  removing the current behaviour, you can specify a set of JavaScript files that
-  will be loaded alongside the default one.
-- **no-section-label:** mdBook by defaults adds section label in table of
-  contents column. For example, "1.", "2.1". Set this option to true to disable
-  those labels. Defaults to `false`.
-- **fold:** A subtable for configuring sidebar section-folding behavior.
-- **playpen:** A subtable for configuring various playpen settings.
-- **search:** A subtable for configuring the in-browser search functionality.
-  mdBook must be compiled with the `search` feature enabled (on by default).
-- **git-repository-url:**  A url to the git repository for the book. If provided
-  an icon link will be output in the menu bar of the book.
-- **git-repository-icon:** The FontAwesome icon class to use for the git
-  repository link. Defaults to `fa-github`.
-  
-Available configuration options for the `[output.html.fold]` table:
-
-- **enable:** Enable section-folding. When off, all folds are open.
-  Defaults to `false`.
-- **level:** The higher the more folded regions are open. When level is 0, all
-  folds are closed. Defaults to `0`.
-
-Available configuration options for the `[output.html.playpen]` table:
-
-- **editable:** Allow editing the source code. Defaults to `false`.
-- **copyable:** Display the copy button on code snippets. Defaults to `true`.
-- **copy-js:** Copy JavaScript files for the editor to the output directory.
-  Defaults to `true`.
-- **line-numbers** Display line numbers on editable sections of code. Requires both `editable` and `copy-js` to be `true`. Defaults to `false`.
-
-[Ace]: https://ace.c9.io/
-
-Available configuration options for the `[output.html.search]` table:
-
-- **enable:** Enables the search feature. Defaults to `true`.
-- **limit-results:** The maximum number of search results. Defaults to `30`.
-- **teaser-word-count:** The number of words used for a search result teaser.
-  Defaults to `30`.
-- **use-boolean-and:** Define the logical link between multiple search words. If
-  true, all search words must appear in each result. Defaults to `false`.
-- **boost-title:** Boost factor for the search result score if a search word
-  appears in the header. Defaults to `2`.
-- **boost-hierarchy:** Boost factor for the search result score if a search word
-  appears in the hierarchy. The hierarchy contains all titles of the parent
-  documents and all parent headings. Defaults to `1`.
-- **boost-paragraph:** Boost factor for the search result score if a search word
-  appears in the text. Defaults to `1`.
-- **expand:** True if search should match longer results e.g. search `micro`
-  should match `microwave`. Defaults to `true`.
-- **heading-split-level:** Search results will link to a section of the document
-  which contains the result. Documents are split into sections by headings this
-  level or less. Defaults to `3`. (`### This is a level 3 heading`)
-- **copy-js:** Copy JavaScript files for the search implementation to the output
-  directory. Defaults to `true`.
-
-This shows all available HTML output options in the **book.toml**:
-
-```toml
-[book]
-title = "Example book"
-authors = ["John Doe", "Jane Doe"]
-description = "The example book covers examples."
-
-[output.html]
-theme = "my-theme"
-default-theme = "light"
-preferred-dark-theme = "navy"
-curly-quotes = true
-mathjax-support = false
-google-analytics = "123456"
-additional-css = ["custom.css", "custom2.css"]
-additional-js = ["custom.js"]
-no-section-label = false
-git-repository-url = "https://github.com/rust-lang-nursery/mdBook"
-git-repository-icon = "fa-github"
-
-[output.html.fold]
-enable = false
-level = 0
-
-[output.html.playpen]
-editable = false
-copy-js = true
-line-numbers = false
-
-[output.html.search]
-enable = true
-limit-results = 30
-teaser-word-count = 30
-use-boolean-and = true
-boost-title = 2
-boost-hierarchy = 1
-boost-paragraph = 1
-expand = true
-heading-split-level = 3
-copy-js = true
-```
-
-### Markdown Renderer
-
-The Markdown renderer will run preprocessors and then output the resulting
-Markdown. This is mostly useful for debugging preprocessors, especially in
-conjunction with `mdbook test` to see the Markdown that `mdbook` is passing
-to `rustdoc`.
-
-The Markdown renderer is included with `mdbook` but disabled by default.
-Enable it by adding an emtpy table to your `book.toml` as follows:
-
-```toml
-[output.markdown]
-```
-
-There are no configuration options for the Markdown renderer at this time;
-only whether it is enabled or disabled.
-
-See [the preprocessors documentation](#configuring-preprocessors) for how to
-specify which preprocessors should run before the Markdown renderer.
-
-### Custom Renderers
-
-A custom renderer can be enabled by adding a `[output.foo]` table to your
-`book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will
-instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
-rendering.
-
-Custom renderers will have access to all configuration within their table
-(i.e. anything under `[output.foo]`), and the command to be invoked can be
-manually specified with the `command` field.
-
-## Environment Variables
-
-All configuration values can be overridden from the command line by setting the
-corresponding environment variable. Because many operating systems restrict
-environment variables to be alphanumeric characters or `_`, the configuration
-key needs to be formatted slightly differently to the normal `foo.bar.baz` form.
-
-Variables starting with `MDBOOK_` are used for configuration. The key is created
-by removing the `MDBOOK_` prefix and turning the resulting string into
-`kebab-case`. Double underscores (`__`) separate nested keys, while a single
-underscore (`_`) is replaced with a dash (`-`).
-
-For example:
-
-- `MDBOOK_foo` -> `foo`
-- `MDBOOK_FOO` -> `foo`
-- `MDBOOK_FOO__BAR` -> `foo.bar`
-- `MDBOOK_FOO_BAR` -> `foo-bar`
-- `MDBOOK_FOO_bar__baz` -> `foo-bar.baz`
-
-So by setting the `MDBOOK_BOOK__TITLE` environment variable you can override the
-book's title without needing to touch your `book.toml`.
-
-> **Note:** To facilitate setting more complex config items, the value of an
-> environment variable is first parsed as JSON, falling back to a string if the
-> parse fails.
->
-> This means, if you so desired, you could override all book metadata when
-> building the book with something like
->
-> ```shell
-> $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
-> $ mdbook build
-> ```
-
-The latter case may be useful in situations where `mdbook` is invoked from a
-script or CI, where it sometimes isn't possible to update the `book.toml` before
-building.

book-example/src/format/mdbook.md

@@ -1,194 +0,0 @@
-# mdBook-specific markdown
-
-## Hiding code lines
-
-There is a feature in mdBook that lets you hide code lines by prepending them
-with a `#` [in the same way that Rustdoc does][rustdoc-hide].
-
-[rustdoc-hide]: https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html#hiding-portions-of-the-example
-
-```bash
-# fn main() {
-    let x = 5;
-    let y = 6;
-
-    println!("{}", x + y);
-# }
-```
-
-Will render as
-
-```rust
-# fn main() {
-    let x = 5;
-    let y = 7;
-
-    println!("{}", x + y);
-# }
-```
-
-## Including files
-
-With the following syntax, you can include files into your book:
-
-```hbs
-\{{#include file.rs}}
-```
-
-The path to the file has to be relative from the current source file.
-
-mdBook will interpret included files as markdown. Since the include command
-is usually used for inserting code snippets and examples, you will often
-wrap the command with ```` ``` ```` to display the file contents without
-interpretting them.
-
-````hbs
-```
-\{{#include file.rs}}
-```
-````
-
-## Including portions of a file
-Often you only need a specific part of the file e.g. relevant lines for an
-example. We support four different modes of partial includes:
-
-```hbs
-\{{#include file.rs:2}}
-\{{#include file.rs::10}}
-\{{#include file.rs:2:}}
-\{{#include file.rs:2:10}}
-```
-
-The first command only includes the second line from file `file.rs`. The second
-command includes all lines up to line 10, i.e. the lines from 11 till the end of
-the file are omitted. The third command includes all lines from line 2, i.e. the
-first line is omitted. The last command includes the excerpt of `file.rs`
-consisting of lines 2 to 10.
-
-To avoid breaking your book when modifying included files, you can also
-include a specific section using anchors instead of line numbers.
-An anchor is a pair of matching lines. The line beginning an anchor must
-match the regex "ANCHOR:\s*[\w_-]+" and similarly the ending line must match
-the regex "ANCHOR_END:\s*[\w_-]+". This allows you to put anchors in
-any kind of commented line.
-
-Consider the following file to include:
-```rs
-/* ANCHOR: all */
-
-// ANCHOR: component
-struct Paddle {
-    hello: f32,
-}
-// ANCHOR_END: component
-
-////////// ANCHOR: system
-impl System for MySystem { ... }
-////////// ANCHOR_END: system
-
-/* ANCHOR_END: all */
-```
-
-Then in the book, all you have to do is:
-````hbs
-Here is a component:
-```rust,no_run,noplaypen
-\{{#include file.rs:component}}
-```
-
-Here is a system:
-```rust,no_run,noplaypen
-\{{#include file.rs:system}}
-```
-
-This is the full file.
-```rust,no_run,noplaypen
-\{{#include file.rs:all}}
-```
-````
-
-Lines containing anchor patterns inside the included anchor are ignored.
-
-## Including a file but initially hiding all except specified lines
-
-The `rustdoc_include` helper is for including code from external Rust files that contain complete
-examples, but only initially showing particular lines specified with line numbers or anchors in the
-same way as with `include`.
-
-The lines not in the line number range or between the anchors will still be included, but they will
-be prefaced with `#`. This way, a reader can expand the snippet to see the complete example, and
-Rustdoc will use the complete example when you run `mdbook test`.
-
-For example, consider a file named `file.rs` that contains this Rust program:
-
-```rust
-fn main() {
-    let x = add_one(2);
-    assert_eq!(x, 3);
-}
-
-fn add_one(num: i32) -> i32 {
-    num + 1
-}
-```
-
-We can include a snippet that initially shows only line 2 by using this syntax:
-
-````hbs
-To call the `add_one` function, we pass it an `i32` and bind the returned value to `x`:
-
-```rust
-\{{#rustdoc_include file.rs:2}}
-```
-````
-
-This would have the same effect as if we had manually inserted the code and hidden all but line 2
-using `#`:
-
-````hbs
-To call the `add_one` function, we pass it an `i32` and bind the returned value to `x`:
-
-```rust
-# fn main() {
-    let x = add_one(2);
-#     assert_eq!(x, 3);
-# }
-#
-# fn add_one(num: i32) -> i32 {
-#     num + 1
-#}
-```
-````
-
-That is, it looks like this (click the "expand" icon to see the rest of the file):
-
-```rust
-# fn main() {
-    let x = add_one(2);
-#     assert_eq!(x, 3);
-# }
-#
-# fn add_one(num: i32) -> i32 {
-#     num + 1
-#}
-```
-
-## Inserting runnable Rust files
-
-With the following syntax, you can insert runnable Rust files into your book:
-
-```hbs
-\{{#playpen file.rs}}
-```
-
-The path to the Rust file has to be relative from the current source file.
-
-When play is clicked, the code snippet will be sent to the [Rust Playpen] to be
-compiled and run. The result is sent back and displayed directly underneath the
-code.
-
-Here is what a rendered code snippet looks like:
-
-{{#playpen example.rs}}
-
-[Rust Playpen]: https://play.rust-lang.org/

book-example/src/format/summary.md

@@ -1,38 +0,0 @@
-# SUMMARY.md
-
-The summary file is used by mdBook to know what chapters to include, in what
-order they should appear, what their hierarchy is and where the source files
-are. Without this file, there is no book.
-
-Even though `SUMMARY.md` is a markdown file, the formatting is very strict to
-allow for easy parsing. Let's see how you should format your `SUMMARY.md` file.
-
-#### Allowed elements
-
-1. ***Title*** It's common practice to begin with a title, generally <code
-   class="language-markdown"># Summary</code>. But it is not mandatory, the
-   parser just ignores it. So you can too if you feel like it.
-
-2. ***Prefix Chapter*** Before the main numbered chapters you can add a couple
-   of elements that will not be numbered. This is useful for forewords,
-   introductions, etc. There are however some constraints. You can not nest
-   prefix chapters, they should all be on the root level. And you can not add
-   prefix chapters once you have added numbered chapters.
-   ```markdown
-   [Title of prefix element](relative/path/to/markdown.md)
-   ```
-
-3. ***Numbered Chapter*** Numbered chapters are the main content of the book,
-   they will be numbered and can be nested, resulting in a nice hierarchy
-   (chapters, sub-chapters, etc.)
-   ```markdown
-   - [Title of the Chapter](relative/path/to/markdown.md)
-   ```
-   You can either use `-` or `*` to indicate a numbered chapter.
-
-4. ***Suffix Chapter*** After the numbered chapters you can add a couple of
-   non-numbered chapters. They are the same as prefix chapters but come after
-   the numbered chapters instead of before.
-
-All other elements are unsupported and will be ignored at best or result in an
-error.

book-example/src/format/theme/README.md

@@ -1,34 +0,0 @@
-# Theme
-
-The default renderer uses a [handlebars](http://handlebarsjs.com/) template to
-render your markdown files and comes with a default theme included in the mdBook
-binary.
-
-The theme is totally customizable, you can selectively replace every file from
-the theme by your own by adding a `theme` directory next to `src` folder in your
-project root. Create a new file with the name of the file you want to override
-and now that file will be used instead of the default file.
-
-Here are the files you can override:
-
-- ***index.hbs*** is the handlebars template.
-- ***book.css*** is the style used in the output. If you want to change the
-  design of your book, this is probably the file you want to modify. Sometimes
-  in conjunction with `index.hbs` when you want to radically change the layout.
-- ***book.js*** is mostly used to add client side functionality, like hiding /
-  un-hiding the sidebar, changing the theme, ...
-- ***highlight.js*** is the JavaScript that is used to highlight code snippets,
-  you should not need to modify this.  
-- ***highlight.css*** is the theme used for the code highlighting
-- ***favicon.png*** the favicon that will be used
-
-Generally, when you want to tweak the theme, you don't need to override all the
-files. If you only need changes in the stylesheet, there is no point in
-overriding all the other files. Because custom files take precedence over
-built-in ones, they will not get updated with new fixes / features.
-
-**Note:** When you override a file, it is possible that you break some
-functionality. Therefore I recommend to use the file from the default theme as
-template and only add / modify what you need. You can copy the default theme
-into your source directory automatically by using `mdbook init --theme` just
-remove the files you don't want to override.

book-example/src/format/theme/editor.md

@@ -1,46 +0,0 @@
-# Editor
-
-In addition to providing runnable code playpens, mdBook optionally allows them
-to be editable. In order to enable editable code blocks, the following needs to
-be added to the ***book.toml***:
-
-```toml
-[output.html.playpen]
-editable = true
-```
-
-To make a specific block available for editing, the attribute `editable` needs
-to be added to it:
-
-<pre><code class="language-markdown">```rust,editable
-fn main() {
-    let number = 5;
-    print!("{}", number);
-}
-```</code></pre>
-
-The above will result in this editable playpen:
-
-```rust,editable
-fn main() {
-    let number = 5;
-    print!("{}", number);
-}
-```
-
-Note the new `Undo Changes` button in the editable playpens.
-
-## Customizing the Editor
-
-By default, the editor is the [Ace](https://ace.c9.io/) editor, but, if desired,
-the functionality may be overriden by providing a different folder:
-
-```toml
-[output.html.playpen]
-editable = true
-editor = "/path/to/editor"
-```
-
-Note that for the editor changes to function correctly, the `book.js` inside of
-the `theme` folder will need to be overriden as it has some couplings with the
-default Ace editor.

book-example/src/format/theme/syntax-highlighting.md

@@ -1,70 +0,0 @@
-# Syntax Highlighting
-
-For syntax highlighting I use [Highlight.js](https://highlightjs.org) with a
-custom theme.
-
-Automatic language detection has been turned off, so you will probably want to
-specify the programming language you use like this
-
-<pre><code class="language-markdown">```rust
-fn main() {
-    // Some code
-}
-```</code></pre>
-
-## Custom theme
-Like the rest of the theme, the files used for syntax highlighting can be
-overridden with your own.
-
-- ***highlight.js*** normally you shouldn't have to overwrite this file, unless
-  you want to use a more recent version.
-- ***highlight.css*** theme used by highlight.js for syntax highlighting.
-
-If you want to use another theme for `highlight.js` download it from their
-website, or make it yourself, rename it to `highlight.css` and put it in
-`src/theme` (or the equivalent if you changed your source folder)
-
-Now your theme will be used instead of the default theme.
-
-## Hiding code lines
-
-There is a feature in mdBook that lets you hide code lines by prepending them
-with a `#`.
-
-
-```bash
-# fn main() {
-    let x = 5;
-    let y = 6;
-
-    println!("{}", x + y);
-# }
-```
-
-Will render as
-
-```rust
-# fn main() {
-    let x = 5;
-    let y = 7;
-
-    println!("{}", x + y);
-# }
-```
-
-**At the moment, this only works for code examples that are annotated with
-`rust`. Because it would collide with semantics of some programming languages.
-In the future, we want to make this configurable through the `book.toml` so that
-everyone can benefit from it.**
-
-
-## Improve default theme
-
-If you think the default theme doesn't look quite right for a specific language,
-or could be improved. Feel free to [submit a new
-issue](https://github.com/rust-lang-nursery/mdBook/issues) explaining what you
-have in mind and I will take a look at it.
-
-You could also create a pull-request with the proposed improvements.
-
-Overall the theme should be light and sober, without to many flashy colors.

book-example/src/misc/introduction.md

@@ -1,3 +0,0 @@
-# Introduction
-
-A frontmatter chapter.

ci/deploy-gh-pages.sh

@@ -1,14 +0,0 @@
-#!/usr/bin/env bash
-# Updates gh-pages with latest docs.
-set -ex
-
-cargo run -- build book-example
-cd book-example/book
-touch .nojekyll
-git init
-git config --local user.email ""
-git config --local user.name "GitHub Deployer"
-git add .
-git commit -m "Deploy to gh-pages"
-remote="https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
-git push "$remote" HEAD:gh-pages --force

ci/install-hub.sh

@@ -1,24 +0,0 @@
-#!/usr/bin/env bash
-# Installs the `hub` executable into hub/bin
-set -ex
-case $1 in
-  ubuntu*)
-    curl -LsSf https://github.com/github/hub/releases/download/v2.12.8/hub-linux-amd64-2.12.8.tgz -o hub.tgz
-    mkdir hub
-    tar -xzvf hub.tgz --strip=1 -C hub
-    ;;
-  macos*)
-    curl -LsSf https://github.com/github/hub/releases/download/v2.12.8/hub-darwin-amd64-2.12.8.tgz -o hub.tgz
-    mkdir hub
-    tar -xzvf hub.tgz --strip=1 -C hub
-    ;;
-  windows*)
-    curl -LsSf https://github.com/github/hub/releases/download/v2.12.8/hub-windows-amd64-2.12.8.zip -o hub.zip
-    7z x hub.zip -ohub
-    ;;
-  *)
-    echo "OS should be first parameter, was: $1"
-    ;;
-esac
-
-echo "##[add-path]$PWD/hub/bin"

ci/install-rust.sh

@@ -12,7 +12,31 @@ TOOLCHAIN="$1"
 
 rustup set profile minimal
 rustup component remove --toolchain=$TOOLCHAIN rust-docs || echo "already removed"
-rustup update $TOOLCHAIN
+rustup update --no-self-update $TOOLCHAIN
+if [ -n "$2" ]
+then
+    TARGET="$2"
+    HOST=$(rustc -Vv | grep ^host: | sed -e "s/host: //g")
+    if [ "$HOST" != "$TARGET" ]
+    then
+        rustup component add llvm-tools-preview --toolchain=$TOOLCHAIN
+        rustup component add rust-std-$TARGET --toolchain=$TOOLCHAIN
+    fi
+    if [[ $TARGET == *"musl" ]]
+    then
+        # This is needed by libdbus-sys.
+        sudo apt update -y && sudo apt install musl-dev musl-tools -y
+    fi
+    if [[ $TARGET == "aarch64-unknown-linux-musl" ]]
+    then
+        echo CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=rust-lld >> $GITHUB_ENV
+        # This `CC` is some nonsense needed for libdbus-sys (via opener).
+        # I don't know if this is really the right thing to do, but it seems to work.
+        sudo apt install gcc-aarch64-linux-gnu -y
+        echo CC=aarch64-linux-gnu-gcc >> $GITHUB_ENV
+    fi
+fi
+
 rustup default $TOOLCHAIN
 rustup -V
 rustc -Vv

ci/install-rustup.sh

@@ -1,26 +0,0 @@
-#!/usr/bin/env bash
-# Install/update rustup.
-# The first argument should be the toolchain to install.
-#
-# It is helpful to have this as a separate script due to some issues on
-# Windows where immediately after `rustup self update`, rustup can fail with
-# "Device or resource busy".
-
-set -ex
-if [ -z "$1" ]
-then
-    echo "First parameter must be toolchain to install."
-    exit 1
-fi
-TOOLCHAIN="$1"
-
-# Install/update rustup.
-if command -v rustup
-then
-    echo `command -v rustup` `rustup -V` already installed
-    rustup self update
-else
-    # macOS currently does not have rust pre-installed.
-    curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain $TOOLCHAIN --profile=minimal
-    echo "##[add-path]$HOME/.cargo/bin"
-fi

ci/make-release-asset.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Builds the release and creates an archive and optionally deploys to GitHub.
+set -ex
+
+if [[ -z "$GITHUB_REF" ]]
+then
+  echo "GITHUB_REF must be set"
+  exit 1
+fi
+# Strip mdbook-refs/tags/ from the start of the ref.
+TAG=${GITHUB_REF#*/tags/}
+
+host=$(rustc -Vv | grep ^host: | sed -e "s/host: //g")
+target=$2
+export CARGO_PROFILE_RELEASE_LTO=true
+cargo build --locked --bin mdbook --release --target $target
+cd target/$target/release
+case $1 in
+  ubuntu*)
+    asset="mdbook-$TAG-$target.tar.gz"
+    tar czf ../../$asset mdbook
+    ;;
+  macos*)
+    asset="mdbook-$TAG-$target.tar.gz"
+    # There is a bug with BSD tar on macOS where the first 8MB of the file are
+    # sometimes all NUL bytes. See https://github.com/actions/cache/issues/403
+    # and https://github.com/rust-lang/cargo/issues/8603 for some more
+    # information. An alternative solution here is to install GNU tar, but
+    # flushing the disk cache seems to work, too.
+    sudo /usr/sbin/purge
+    tar czf ../../$asset mdbook
+    ;;
+  windows*)
+    asset="mdbook-$TAG-$target.zip"
+    7z a ../../$asset mdbook.exe
+    ;;
+  *)
+    echo "OS should be first parameter, was: $1"
+    ;;
+esac
+cd ../..
+
+if [[ -z "$GITHUB_ENV" ]]
+then
+  echo "GITHUB_ENV not set, run: gh release upload $TAG target/$asset"
+else
+  echo "MDBOOK_TAG=$TAG" >> $GITHUB_ENV
+  echo "MDBOOK_ASSET=target/$asset" >> $GITHUB_ENV
+fi

ci/make-release.sh

@@ -1,36 +0,0 @@
-#!/usr/bin/env bash
-# Builds the release and creates an archive and optionally deploys to GitHub.
-set -ex
-
-if [[ -z "$GITHUB_REF" ]]
-then
-  echo "GITHUB_REF must be set"
-  exit 1
-fi
-# Strip mdbook-refs/tags/ from the start of the ref.
-TAG=${GITHUB_REF#*/tags/}
-
-host=$(rustc -Vv | grep ^host: | sed -e "s/host: //g")
-cargo rustc --bin mdbook --release -- -C lto
-cd target/release
-case $1 in
-  ubuntu* | macos*)
-    asset="mdbook-$TAG-$host.tar.gz"
-    tar czf ../../$asset mdbook
-    ;;
-  windows*)
-    asset="mdbook-$TAG-$host.zip"
-    7z a ../../$asset mdbook.exe
-    ;;
-  *)
-    echo "OS should be first parameter, was: $1"
-    ;;
-esac
-cd ../..
-
-if [[ -z "$GITHUB_TOKEN" ]]
-then
-  echo "$GITHUB_TOKEN not set, skipping deploy."
-else
-  hub release edit -m "" --attach $asset $TAG
-fi

ci/publish-guide.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# This publishes the user guide to GitHub Pages.
+#
+# If this is a pre-release, then it goes in a separate directory called "pre-release".
+# Commits are amended to avoid keeping history which can balloon the repo size.
+set -ex
+
+cargo run --no-default-features -F search -- build guide
+
+VERSION=$(cargo metadata --format-version 1 --no-deps | jq '.packages[] | select(.name == "mdbook") | .version')
+
+if [[ "$VERSION" == *-* ]]; then
+    PRERELEASE=true
+else
+    PRERELEASE=false
+fi
+
+git fetch origin gh-pages
+git worktree add gh-pages gh-pages
+git config user.name "Deploy from CI"
+git config user.email ""
+cd gh-pages
+if [[ "$PRERELEASE" == "true" ]]
+then
+    rm -rf pre-release
+    mv ../guide/book pre-release
+    git add pre-release
+    git commit --amend -m "Deploy $GITHUB_SHA pre-release to gh-pages"
+else
+    # Delete everything except pre-release and .git.
+    find . -mindepth 1 -maxdepth 1 -not -name "pre-release" -not -name ".git" -exec rm -rf {} +
+    # Copy the guide here.
+    find ../guide/book/ -mindepth 1 -maxdepth 1 -exec mv {} . \;
+    git add .
+    git commit --amend -m "Deploy $GITHUB_SHA to gh-pages"
+fi
+
+git push --force origin +gh-pages

ci/update-dependencies.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Updates all compatible Cargo dependencies.
+#
+# I wasn't able to get Renovate to update compatible dependencies in a way
+# that I like, so this script takes care of it. This uses `cargo upgrade` to
+# ensure that `Cargo.toml` also gets updated. This also makes sure that all
+# transitive dependencies are updated.
+
+set -ex
+
+git fetch origin update-dependencies
+if git checkout update-dependencies
+then
+    git reset --hard origin/master
+else
+    git checkout -b update-dependencies
+fi
+
+cat > commit-message << 'EOF'
+Update cargo dependencies
+
+```
+EOF
+cargo upgrade >> commit-message
+echo '```' >> commit-message
+if git diff --quiet
+then
+    echo "No changes detected, exiting."
+    exit 0
+fi
+# Also update any transitive dependencies.
+cargo update
+
+git config user.name "github-actions[bot]"
+git config user.email "github-actions[bot]@users.noreply.github.com"
+
+git add Cargo.toml Cargo.lock
+git commit -F commit-message
+
+git push --force origin update-dependencies
+
+gh pr create --fill \
+    --head update-dependencies \
+    --base master

crates/mdbook-compare/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "mdbook-compare"
+publish = false
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+
+[lints]
+workspace = true

crates/mdbook-compare/README.md

@@ -0,0 +1,26 @@
+# mdbook-compare
+
+This is a simple utility to compare the output of two different versions of mdbook.
+
+To use this:
+
+1. Install [`tidy`](https://www.html-tidy.org/).
+2. Install or build the initial version of mdbook that you want to compare.
+3. Install or build the new version of mdbook that you want to compare.
+4. Run `mdbook-compare` with the arguments to the mdbook executables and the books to build.
+
+```sh
+cargo run --manifest-path /path/to/mdBook/Cargo.toml -p mdbook-compare -- \
+    /path/to/orig/mdbook /path/to/my-book /path/to/new/mdbook /path/to/my-book
+```
+
+It takes two separate paths for the book to use for "before" and "after" in case you need to customize the book to run on older versions. If you don't need that, then you can use the same directory for both the before and after.
+
+`mdbook-compare` will do the following:
+
+1. Clean up any book directories.
+2. Build the book with the first mdbook.
+3. Build the book with the second mdbook.
+4. The output of those two commands are stored in directories called `compare1` and `compare2`.
+5. The HTML in those directories is normalized using `tidy`.
+6. Runs `git diff` to compare the output.

crates/mdbook-compare/src/main.rs

@@ -0,0 +1,113 @@
+//! Utility to compare the output of two different versions of mdbook.
+
+use std::path::Path;
+use std::process::Command;
+
+macro_rules! error {
+    ($msg:literal $($arg:tt)*) => {
+        eprint!("error: ");
+        eprintln!($msg $($arg)*);
+        std::process::exit(1);
+    };
+}
+
+fn main() {
+    let mut args = std::env::args().skip(1);
+    let (Some(mdbook1), Some(book1), Some(mdbook2), Some(book2)) =
+        (args.next(), args.next(), args.next(), args.next())
+    else {
+        eprintln!("error: Expected four arguments: <exe1> <dir1> <exe2> <dir2>");
+        std::process::exit(1);
+    };
+    let mdbook1 = Path::new(&mdbook1);
+    let mdbook2 = Path::new(&mdbook2);
+    let book1 = Path::new(&book1);
+    let book2 = Path::new(&book2);
+    let compare1 = Path::new("compare1");
+    let compare2 = Path::new("compare2");
+    clean(compare1);
+    clean(compare2);
+    clean(&book1.join("book"));
+    clean(&book2.join("book"));
+    build(mdbook1, book1);
+    std::fs::rename(book1.join("book"), compare1).unwrap();
+    build(mdbook2, book2);
+    std::fs::rename(book2.join("book"), compare2).unwrap();
+    diff(compare1, compare2);
+}
+
+fn clean(path: &Path) {
+    if path.exists() {
+        println!("removing {path:?}");
+        std::fs::remove_dir_all(path).unwrap();
+    }
+}
+
+fn build(mdbook: &Path, book: &Path) {
+    println!("running `{mdbook:?} build` in `{book:?}`");
+    let status = Command::new(mdbook)
+        .arg("build")
+        .current_dir(book)
+        .status()
+        .unwrap_or_else(|e| {
+            error!("expected {mdbook:?} executable to exist: {e}");
+        });
+    if !status.success() {
+        error!("process {mdbook:?} failed");
+    }
+    process(&book.join("book"));
+}
+
+fn process(path: &Path) {
+    for entry in std::fs::read_dir(path).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+        if path.is_dir() {
+            process(&path);
+        } else {
+            if path.extension().is_some_and(|ext| ext == "html") {
+                tidy(&path);
+                process_html(&path);
+            } else {
+                std::fs::remove_file(path).unwrap();
+            }
+        }
+    }
+}
+
+fn process_html(path: &Path) {
+    let content = std::fs::read_to_string(path).unwrap();
+    let Some(start_index) = content.find("<main>") else {
+        return;
+    };
+    let end_index = content.rfind("</main>").unwrap();
+    let new_content = &content[start_index..end_index + 8];
+    std::fs::write(path, new_content).unwrap();
+}
+
+fn tidy(path: &Path) {
+    // quiet, no wrap, modify in place
+    let args = "-q -w 0 -m --custom-tags yes --drop-empty-elements no";
+    println!("running `tidy {args}` in `{path:?}`");
+    let status = Command::new("tidy")
+        .args(args.split(' '))
+        .arg(path)
+        .status()
+        .expect("tidy should be installed");
+    if !status.success() {
+        // Exit code 1 is a warning.
+        if status.code() != Some(1) {
+            error!("tidy failed: {status}");
+        }
+    }
+}
+
+fn diff(a: &Path, b: &Path) {
+    let args = "diff --no-index";
+    println!("running `git {args} {a:?} {b:?}`");
+    Command::new("git")
+        .args(args.split(' '))
+        .args([a, b])
+        .status()
+        .unwrap();
+}

crates/mdbook-core/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "mdbook-core"
+version = "0.5.0-beta.1"
+description = "The base support library for mdbook, intended for internal use only"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+regex.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+toml.workspace = true
+tracing.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+
+[lints]
+workspace = true

crates/mdbook-core/README.md

@@ -0,0 +1,13 @@
+# mdbook-core
+
+[![Documentation](https://img.shields.io/docsrs/mdbook-core)](https://docs.rs/mdbook-core)
+[![crates.io](https://img.shields.io/crates/v/mdbook-core.svg)](https://crates.io/crates/mdbook-core)
+[![Changelog](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md)
+
+This is the base support library for [mdBook](https://rust-lang.github.io/mdBook/). It is intended for internal use only. Other mdBook crates depend on this for any types that are shared across the crates.
+
+> This crate is maintained by the mdBook team, primarily for use by mdBook and not intended for external use (except as a transitive dependency). This crate may make major changes to its APIs or be deprecated without warning.
+
+## License
+
+[Mozilla Public License, version 2.0](https://github.com/rust-lang/mdBook/blob/master/LICENSE)

crates/mdbook-core/src/book.rs

@@ -0,0 +1,288 @@
+//! A tree structure representing a book.
+
+use serde::{Deserialize, Serialize};
+use std::collections::VecDeque;
+use std::fmt::{self, Display, Formatter};
+use std::ops::{Deref, DerefMut};
+use std::path::PathBuf;
+
+#[cfg(test)]
+mod tests;
+
+/// A tree structure representing a book.
+///
+/// A book is just a collection of [`BookItems`] which are accessible by
+/// either iterating (immutably) over the book with [`iter()`], or recursively
+/// applying a closure to each item to mutate the chapters, using
+/// [`for_each_mut()`].
+///
+/// [`iter()`]: #method.iter
+/// [`for_each_mut()`]: #method.for_each_mut
+#[allow(
+    clippy::exhaustive_structs,
+    reason = "This cannot be extended without breaking preprocessors."
+)]
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct Book {
+    /// The items in this book.
+    pub items: Vec<BookItem>,
+}
+
+impl Book {
+    /// Create an empty book.
+    pub fn new() -> Self {
+        Default::default()
+    }
+
+    /// Creates a new book with the given items.
+    pub fn new_with_items(items: Vec<BookItem>) -> Book {
+        Book { items }
+    }
+
+    /// Get a depth-first iterator over the items in the book.
+    pub fn iter(&self) -> BookItems<'_> {
+        BookItems {
+            items: self.items.iter().collect(),
+        }
+    }
+
+    /// A depth-first iterator over each [`Chapter`], skipping draft chapters.
+    pub fn chapters(&self) -> impl Iterator<Item = &Chapter> {
+        self.iter().filter_map(|item| match item {
+            BookItem::Chapter(ch) if !ch.is_draft_chapter() => Some(ch),
+            _ => None,
+        })
+    }
+
+    /// Recursively apply a closure to each item in the book, allowing you to
+    /// mutate them.
+    ///
+    /// # Note
+    ///
+    /// Unlike the `iter()` method, this requires a closure instead of returning
+    /// an iterator. This is because using iterators can possibly allow you
+    /// to have iterator invalidation errors.
+    pub fn for_each_mut<F>(&mut self, mut func: F)
+    where
+        F: FnMut(&mut BookItem),
+    {
+        for_each_mut(&mut func, &mut self.items);
+    }
+
+    /// Recursively apply a closure to each non-draft chapter in the book,
+    /// allowing you to mutate them.
+    pub fn for_each_chapter_mut<F>(&mut self, mut func: F)
+    where
+        F: FnMut(&mut Chapter),
+    {
+        for_each_mut(
+            &mut |item| {
+                let BookItem::Chapter(ch) = item else {
+                    return;
+                };
+                if ch.is_draft_chapter() {
+                    return;
+                }
+                func(ch)
+            },
+            &mut self.items,
+        );
+    }
+
+    /// Append a `BookItem` to the `Book`.
+    pub fn push_item<I: Into<BookItem>>(&mut self, item: I) -> &mut Self {
+        self.items.push(item.into());
+        self
+    }
+}
+
+fn for_each_mut<'a, F, I>(func: &mut F, items: I)
+where
+    F: FnMut(&mut BookItem),
+    I: IntoIterator<Item = &'a mut BookItem>,
+{
+    for item in items {
+        if let BookItem::Chapter(ch) = item {
+            for_each_mut(func, &mut ch.sub_items);
+        }
+
+        func(item);
+    }
+}
+
+/// Enum representing any type of item which can be added to a book.
+#[allow(
+    clippy::exhaustive_enums,
+    reason = "This cannot be extended without breaking preprocessors."
+)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum BookItem {
+    /// A nested chapter.
+    Chapter(Chapter),
+    /// A section separator.
+    Separator,
+    /// A part title.
+    PartTitle(String),
+}
+
+impl From<Chapter> for BookItem {
+    fn from(other: Chapter) -> BookItem {
+        BookItem::Chapter(other)
+    }
+}
+
+/// The representation of a "chapter", usually mapping to a single file on
+/// disk however it may contain multiple sub-chapters.
+#[allow(
+    clippy::exhaustive_structs,
+    reason = "This cannot be extended without breaking preprocessors."
+)]
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct Chapter {
+    /// The chapter's name.
+    pub name: String,
+    /// The chapter's contents.
+    pub content: String,
+    /// The chapter's section number, if it has one.
+    pub number: Option<SectionNumber>,
+    /// Nested items.
+    pub sub_items: Vec<BookItem>,
+    /// The chapter's location, relative to the `SUMMARY.md` file.
+    ///
+    /// **Note**: After the index preprocessor runs, any README files will be
+    /// modified to be `index.md`. If you need access to the actual filename
+    /// on disk, use [`Chapter::source_path`] instead.
+    ///
+    /// This is `None` for a draft chapter.
+    pub path: Option<PathBuf>,
+    /// The chapter's source file, relative to the `SUMMARY.md` file.
+    ///
+    /// **Note**: Beware that README files will internally be treated as
+    /// `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, 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>,
+}
+
+impl Chapter {
+    /// Create a new chapter with the provided content.
+    pub fn new<P: Into<PathBuf>>(
+        name: &str,
+        content: String,
+        p: P,
+        parent_names: Vec<String>,
+    ) -> Chapter {
+        let path: PathBuf = p.into();
+        Chapter {
+            name: name.to_string(),
+            content,
+            path: Some(path.clone()),
+            source_path: Some(path),
+            parent_names,
+            ..Default::default()
+        }
+    }
+
+    /// Create a new draft chapter that is not attached to a source markdown file (and thus
+    /// has no content).
+    pub fn new_draft(name: &str, parent_names: Vec<String>) -> Self {
+        Chapter {
+            name: name.to_string(),
+            content: String::new(),
+            path: None,
+            source_path: None,
+            parent_names,
+            ..Default::default()
+        }
+    }
+
+    /// Check if the chapter is a draft chapter, meaning it has no path to a source markdown file.
+    pub fn is_draft_chapter(&self) -> bool {
+        self.path.is_none()
+    }
+}
+
+impl Display for Chapter {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        if let Some(ref section_number) = self.number {
+            write!(f, "{section_number} ")?;
+        }
+
+        write!(f, "{}", self.name)
+    }
+}
+
+/// A section number like "1.2.3", basically just a newtype'd `Vec<u32>` with
+/// a pretty `Display` impl.
+#[derive(Debug, PartialEq, Clone, Default, Serialize, Deserialize)]
+pub struct SectionNumber(Vec<u32>);
+
+impl SectionNumber {
+    /// Creates a new [`SectionNumber`].
+    pub fn new(numbers: impl Into<Vec<u32>>) -> SectionNumber {
+        SectionNumber(numbers.into())
+    }
+}
+
+impl Display for SectionNumber {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        if self.0.is_empty() {
+            write!(f, "0")
+        } else {
+            for item in &self.0 {
+                write!(f, "{item}.")?;
+            }
+            Ok(())
+        }
+    }
+}
+
+impl Deref for SectionNumber {
+    type Target = Vec<u32>;
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl DerefMut for SectionNumber {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}
+
+impl FromIterator<u32> for SectionNumber {
+    fn from_iter<I: IntoIterator<Item = u32>>(it: I) -> Self {
+        SectionNumber(it.into_iter().collect())
+    }
+}
+
+/// A depth-first iterator over the items in a book.
+///
+/// # Note
+///
+/// This struct shouldn't be created directly, instead prefer the
+/// [`Book::iter()`] method.
+pub struct BookItems<'a> {
+    items: VecDeque<&'a BookItem>,
+}
+
+impl<'a> Iterator for BookItems<'a> {
+    type Item = &'a BookItem;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        let item = self.items.pop_front();
+
+        if let Some(BookItem::Chapter(ch)) = item {
+            // if we wanted a breadth-first iterator we'd `extend()` here
+            for sub_item in ch.sub_items.iter().rev() {
+                self.items.push_front(sub_item);
+            }
+        }
+
+        item
+    }
+}

crates/mdbook-core/src/book/tests.rs

@@ -0,0 +1,123 @@
+use super::*;
+
+#[test]
+fn section_number_has_correct_dotted_representation() {
+    let inputs = vec![
+        (vec![0], "0."),
+        (vec![1, 3], "1.3."),
+        (vec![1, 2, 3], "1.2.3."),
+    ];
+
+    for (input, should_be) in inputs {
+        let section_number = SectionNumber(input).to_string();
+        assert_eq!(section_number, should_be);
+    }
+}
+
+#[test]
+fn book_iter_iterates_over_sequential_items() {
+    let items = vec![
+        BookItem::Chapter(Chapter {
+            name: String::from("Chapter 1"),
+            content: String::from("# Chapter 1"),
+            ..Default::default()
+        }),
+        BookItem::Separator,
+    ];
+    let book = Book::new_with_items(items);
+
+    let should_be: Vec<_> = book.items.iter().collect();
+
+    let got: Vec<_> = book.iter().collect();
+
+    assert_eq!(got, should_be);
+}
+
+#[test]
+fn for_each_mut_visits_all_items() {
+    let items = vec![
+        BookItem::Chapter(Chapter {
+            name: String::from("Chapter 1"),
+            content: String::from("# Chapter 1"),
+            number: None,
+            path: Some(PathBuf::from("Chapter_1/index.md")),
+            source_path: Some(PathBuf::from("Chapter_1/index.md")),
+            parent_names: Vec::new(),
+            sub_items: vec![
+                BookItem::Chapter(Chapter::new(
+                    "Hello World",
+                    String::new(),
+                    "Chapter_1/hello.md",
+                    Vec::new(),
+                )),
+                BookItem::Separator,
+                BookItem::Chapter(Chapter::new(
+                    "Goodbye World",
+                    String::new(),
+                    "Chapter_1/goodbye.md",
+                    Vec::new(),
+                )),
+            ],
+        }),
+        BookItem::Separator,
+    ];
+    let mut book = Book::new_with_items(items);
+
+    let num_items = book.iter().count();
+    let mut visited = 0;
+
+    book.for_each_mut(|_| visited += 1);
+
+    assert_eq!(visited, num_items);
+}
+
+#[test]
+fn iterate_over_nested_book_items() {
+    let items = vec![
+        BookItem::Chapter(Chapter {
+            name: String::from("Chapter 1"),
+            content: String::from("# Chapter 1"),
+            number: None,
+            path: Some(PathBuf::from("Chapter_1/index.md")),
+            source_path: Some(PathBuf::from("Chapter_1/index.md")),
+            parent_names: Vec::new(),
+            sub_items: vec![
+                BookItem::Chapter(Chapter::new(
+                    "Hello World",
+                    String::new(),
+                    "Chapter_1/hello.md",
+                    Vec::new(),
+                )),
+                BookItem::Separator,
+                BookItem::Chapter(Chapter::new(
+                    "Goodbye World",
+                    String::new(),
+                    "Chapter_1/goodbye.md",
+                    Vec::new(),
+                )),
+            ],
+        }),
+        BookItem::Separator,
+    ];
+    let book = Book::new_with_items(items);
+
+    let got: Vec<_> = book.iter().collect();
+
+    assert_eq!(got.len(), 5);
+
+    // checking the chapter names are in the order should be sufficient here...
+    let chapter_names: Vec<String> = got
+        .into_iter()
+        .filter_map(|i| match *i {
+            BookItem::Chapter(ref ch) => Some(ch.name.clone()),
+            _ => None,
+        })
+        .collect();
+    let should_be: Vec<_> = vec![
+        String::from("Chapter 1"),
+        String::from("Hello World"),
+        String::from("Goodbye World"),
+    ];
+
+    assert_eq!(chapter_names, should_be);
+}

crates/mdbook-core/src/lib.rs

@@ -0,0 +1,16 @@
+//! The base support library for mdbook, intended for internal use only.
+
+/// The current version of `mdbook`.
+///
+/// This is provided as a way for custom preprocessors and renderers to do
+/// compatibility checks.
+pub const MDBOOK_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+pub mod book;
+pub mod config;
+pub mod utils;
+
+/// The error types used in mdbook.
+pub mod errors {
+    pub use anyhow::{Error, Result};
+}

crates/mdbook-core/src/utils/fs.rs

@@ -0,0 +1,273 @@
+//! Filesystem utilities and helpers.
+
+use anyhow::{Context, Result};
+use std::fs;
+use std::path::{Component, Path, PathBuf};
+use tracing::debug;
+
+/// Reads a file into a string.
+///
+/// Equivalent to [`std::fs::read_to_string`] with better error messages.
+pub fn read_to_string<P: AsRef<Path>>(path: P) -> Result<String> {
+    let path = path.as_ref();
+    fs::read_to_string(path).with_context(|| format!("failed to read `{}`", path.display()))
+}
+
+/// Writes a file to disk.
+///
+/// Equivalent to [`std::fs::write`] with better error messages. This will
+/// also create the parent directory if it doesn't exist.
+pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> Result<()> {
+    let path = path.as_ref();
+    debug!("Writing `{}`", path.display());
+    if let Some(parent) = path.parent() {
+        create_dir_all(parent)?;
+    }
+    fs::write(path, contents.as_ref())
+        .with_context(|| format!("failed to write `{}`", path.display()))
+}
+
+/// Equivalent to [`std::fs::create_dir_all`] with better error messages.
+pub fn create_dir_all(p: impl AsRef<Path>) -> Result<()> {
+    let p = p.as_ref();
+    fs::create_dir_all(p)
+        .with_context(|| format!("failed to create directory `{}`", p.display()))?;
+    Ok(())
+}
+
+/// Takes a path and returns a path containing just enough `../` to point to
+/// the root of the given path.
+///
+/// This is mostly interesting for a relative path to point back to the
+/// directory from where the path starts.
+///
+/// ```rust
+/// # use std::path::Path;
+/// # use mdbook_core::utils::fs::path_to_root;
+/// let path = Path::new("some/relative/path");
+/// assert_eq!(path_to_root(path), "../../");
+/// ```
+///
+/// **note:** it's not very fool-proof, if you find a situation where
+/// it doesn't return the correct path.
+/// Consider [submitting a new issue](https://github.com/rust-lang/mdBook/issues)
+/// or a [pull-request](https://github.com/rust-lang/mdBook/pulls) to improve it.
+pub fn path_to_root<P: Into<PathBuf>>(path: P) -> String {
+    // Remove filename and add "../" for every directory
+
+    path.into()
+        .parent()
+        .expect("")
+        .components()
+        .fold(String::new(), |mut s, c| {
+            match c {
+                Component::Normal(_) => s.push_str("../"),
+                _ => {
+                    debug!("Other path component... {:?}", c);
+                }
+            }
+            s
+        })
+}
+
+/// Removes all the content of a directory but not the directory itself.
+pub fn remove_dir_content(dir: &Path) -> Result<()> {
+    for item in fs::read_dir(dir)
+        .with_context(|| format!("failed to read directory `{}`", dir.display()))?
+        .flatten()
+    {
+        let item = item.path();
+        if item.is_dir() {
+            fs::remove_dir_all(&item)
+                .with_context(|| format!("failed to remove `{}`", item.display()))?;
+        } else {
+            fs::remove_file(&item)
+                .with_context(|| format!("failed to remove `{}`", item.display()))?;
+        }
+    }
+    Ok(())
+}
+
+/// Copies all files of a directory to another one except the files
+/// with the extensions given in the `ext_blacklist` array
+pub fn copy_files_except_ext(
+    from: &Path,
+    to: &Path,
+    recursive: bool,
+    avoid_dir: Option<&PathBuf>,
+    ext_blacklist: &[&str],
+) -> Result<()> {
+    debug!(
+        "Copying all files from {} to {} (blacklist: {:?}), avoiding {:?}",
+        from.display(),
+        to.display(),
+        ext_blacklist,
+        avoid_dir
+    );
+
+    // Check that from and to are different
+    if from == to {
+        return Ok(());
+    }
+
+    for entry in fs::read_dir(from)? {
+        let entry = entry?.path();
+        let metadata = entry
+            .metadata()
+            .with_context(|| format!("Failed to read {entry:?}"))?;
+
+        let entry_file_name = entry.file_name().unwrap();
+        let target_file_path = to.join(entry_file_name);
+
+        // If the entry is a dir and the recursive option is enabled, call itself
+        if metadata.is_dir() && recursive {
+            if entry == to.as_os_str() {
+                continue;
+            }
+
+            if let Some(avoid) = avoid_dir {
+                if entry == *avoid {
+                    continue;
+                }
+            }
+
+            // check if output dir already exists
+            if !target_file_path.exists() {
+                fs::create_dir(&target_file_path)?;
+            }
+
+            copy_files_except_ext(&entry, &target_file_path, true, avoid_dir, ext_blacklist)?;
+        } else if metadata.is_file() {
+            // Check if it is in the blacklist
+            if let Some(ext) = entry.extension() {
+                if ext_blacklist.contains(&ext.to_str().unwrap()) {
+                    continue;
+                }
+            }
+            debug!("Copying {entry:?} to {target_file_path:?}");
+            copy(&entry, &target_file_path)?;
+        }
+    }
+    Ok(())
+}
+
+/// Copies a file.
+fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> Result<()> {
+    let from = from.as_ref();
+    let to = to.as_ref();
+    return copy_inner(from, to)
+        .with_context(|| format!("failed to copy `{}` to `{}`", from.display(), to.display()));
+
+    // This is a workaround for an issue with the macOS file watcher.
+    // Rust's `std::fs::copy` function uses `fclonefileat`, which creates
+    // clones on APFS. Unfortunately fs events seem to trigger on both
+    // sides of the clone, and there doesn't seem to be a way to differentiate
+    // which side it is.
+    // https://github.com/notify-rs/notify/issues/465#issuecomment-1657261035
+    // contains more information.
+    //
+    // This is essentially a copy of the simple copy code path in Rust's
+    // standard library.
+    #[cfg(target_os = "macos")]
+    fn copy_inner(from: &Path, to: &Path) -> Result<()> {
+        use std::fs::OpenOptions;
+        use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
+
+        let mut reader = std::fs::File::open(from)?;
+        let metadata = reader.metadata()?;
+        if !metadata.is_file() {
+            anyhow::bail!(
+                "expected a file, `{}` appears to be {:?}",
+                from.display(),
+                metadata.file_type()
+            );
+        }
+        let perm = metadata.permissions();
+        let mut writer = OpenOptions::new()
+            .mode(perm.mode())
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .open(to)?;
+        let writer_metadata = writer.metadata()?;
+        if writer_metadata.is_file() {
+            // Set the correct file permissions, in case the file already existed.
+            // Don't set the permissions on already existing non-files like
+            // pipes/FIFOs or device nodes.
+            writer.set_permissions(perm)?;
+        }
+        std::io::copy(&mut reader, &mut writer)?;
+        Ok(())
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    fn copy_inner(from: &Path, to: &Path) -> Result<()> {
+        fs::copy(from, to)?;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Result;
+    use std::path::Path;
+
+    #[cfg(target_os = "windows")]
+    fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> Result<()> {
+        std::os::windows::fs::symlink_file(src, dst)
+    }
+
+    #[cfg(not(target_os = "windows"))]
+    fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> Result<()> {
+        std::os::unix::fs::symlink(src, dst)
+    }
+
+    #[test]
+    fn copy_files_except_ext_test() {
+        let tmp = match tempfile::TempDir::new() {
+            Ok(t) => t,
+            Err(e) => panic!("Could not create a temp dir: {e}"),
+        };
+
+        // Create a couple of files
+        write(tmp.path().join("file.txt"), "").unwrap();
+        write(tmp.path().join("file.md"), "").unwrap();
+        write(tmp.path().join("file.png"), "").unwrap();
+        write(tmp.path().join("sub_dir/file.png"), "").unwrap();
+        write(tmp.path().join("sub_dir_exists/file.txt"), "").unwrap();
+        if let Err(err) = symlink(tmp.path().join("file.png"), tmp.path().join("symlink.png")) {
+            panic!("Could not symlink file.png: {err}");
+        }
+
+        // Create output dir
+        create_dir_all(tmp.path().join("output")).unwrap();
+        create_dir_all(tmp.path().join("output/sub_dir_exists")).unwrap();
+
+        if let Err(e) =
+            copy_files_except_ext(tmp.path(), &tmp.path().join("output"), true, None, &["md"])
+        {
+            panic!("Error while executing the function:\n{e:?}");
+        }
+
+        // Check if the correct files where created
+        if !tmp.path().join("output/file.txt").exists() {
+            panic!("output/file.txt should exist")
+        }
+        if tmp.path().join("output/file.md").exists() {
+            panic!("output/file.md should not exist")
+        }
+        if !tmp.path().join("output/file.png").exists() {
+            panic!("output/file.png should exist")
+        }
+        if !tmp.path().join("output/sub_dir/file.png").exists() {
+            panic!("output/sub_dir/file.png should exist")
+        }
+        if !tmp.path().join("output/sub_dir_exists/file.txt").exists() {
+            panic!("output/sub_dir/file.png should exist")
+        }
+        if !tmp.path().join("output/symlink.png").exists() {
+            panic!("output/symlink.png should exist")
+        }
+    }
+}

crates/mdbook-core/src/utils/html.rs

@@ -0,0 +1,78 @@
+//! Utilities for dealing with HTML.
+
+use std::borrow::Cow;
+
+/// Escape characters to make it safe for an HTML string.
+pub fn escape_html_attribute(text: &str) -> Cow<'_, str> {
+    let needs_escape: &[char] = &['<', '>', '\'', '"', '\\', '&'];
+    let mut s = text;
+    let mut output = String::new();
+    while let Some(next) = s.find(needs_escape) {
+        output.push_str(&s[..next]);
+        match s.as_bytes()[next] {
+            b'<' => output.push_str("&lt;"),
+            b'>' => output.push_str("&gt;"),
+            b'\'' => output.push_str("&#39;"),
+            b'"' => output.push_str("&quot;"),
+            b'\\' => output.push_str("&#92;"),
+            b'&' => output.push_str("&amp;"),
+            _ => unreachable!(),
+        }
+        s = &s[next + 1..];
+    }
+    if output.is_empty() {
+        Cow::Borrowed(text)
+    } else {
+        output.push_str(s);
+        Cow::Owned(output)
+    }
+}
+
+/// Escape `<`, `>`, and '&' for HTML.
+pub fn escape_html(text: &str) -> Cow<'_, str> {
+    let needs_escape: &[char] = &['<', '>', '&'];
+    let mut s = text;
+    let mut output = String::new();
+    while let Some(next) = s.find(needs_escape) {
+        output.push_str(&s[..next]);
+        match s.as_bytes()[next] {
+            b'<' => output.push_str("&lt;"),
+            b'>' => output.push_str("&gt;"),
+            b'&' => output.push_str("&amp;"),
+            _ => unreachable!(),
+        }
+        s = &s[next + 1..];
+    }
+    if output.is_empty() {
+        Cow::Borrowed(text)
+    } else {
+        output.push_str(s);
+        Cow::Owned(output)
+    }
+}
+
+#[test]
+fn attributes_are_escaped() {
+    assert_eq!(escape_html_attribute(""), "");
+    assert_eq!(escape_html_attribute("<"), "&lt;");
+    assert_eq!(escape_html_attribute(">"), "&gt;");
+    assert_eq!(escape_html_attribute("<>"), "&lt;&gt;");
+    assert_eq!(escape_html_attribute("<test>"), "&lt;test&gt;");
+    assert_eq!(escape_html_attribute("a<test>b"), "a&lt;test&gt;b");
+    assert_eq!(escape_html_attribute("'"), "&#39;");
+    assert_eq!(escape_html_attribute("\\"), "&#92;");
+    assert_eq!(escape_html_attribute("&"), "&amp;");
+}
+
+#[test]
+fn html_is_escaped() {
+    assert_eq!(escape_html(""), "");
+    assert_eq!(escape_html("<"), "&lt;");
+    assert_eq!(escape_html(">"), "&gt;");
+    assert_eq!(escape_html("&"), "&amp;");
+    assert_eq!(escape_html("<>"), "&lt;&gt;");
+    assert_eq!(escape_html("<test>"), "&lt;test&gt;");
+    assert_eq!(escape_html("a<test>b"), "a&lt;test&gt;b");
+    assert_eq!(escape_html("'"), "'");
+    assert_eq!(escape_html("\\"), "\\");
+}

crates/mdbook-core/src/utils/mod.rs

@@ -0,0 +1,37 @@
+//! Various helpers and utilities.
+
+use anyhow::Error;
+use std::fmt::Write;
+use tracing::error;
+
+pub mod fs;
+mod html;
+mod toml_ext;
+
+pub(crate) use self::toml_ext::TomlExt;
+
+pub use self::html::{escape_html, escape_html_attribute};
+
+/// Defines a `static` with a [`regex::Regex`].
+#[macro_export]
+macro_rules! static_regex {
+    ($name:ident, $regex:literal) => {
+        static $name: std::sync::LazyLock<regex::Regex> =
+            std::sync::LazyLock::new(|| regex::Regex::new($regex).unwrap());
+    };
+    ($name:ident, bytes, $regex:literal) => {
+        static $name: std::sync::LazyLock<regex::bytes::Regex> =
+            std::sync::LazyLock::new(|| regex::bytes::Regex::new($regex).unwrap());
+    };
+}
+
+/// Prints a "backtrace" of some `Error`.
+pub fn log_backtrace(e: &Error) {
+    let mut message = format!("{e}");
+
+    for cause in e.chain().skip(1) {
+        write!(message, "\n\tCaused by: {cause}").unwrap();
+    }
+
+    error!("{message}");
+}

crates/mdbook-core/src/utils/toml_ext.rs

@@ -0,0 +1,94 @@
+//! Helper for working with toml types.
+
+use toml::value::{Table, Value};
+
+/// Helper for working with toml types.
+pub(crate) trait TomlExt {
+    /// Read a dotted key.
+    fn read(&self, key: &str) -> Option<&Value>;
+    /// Insert with a dotted key.
+    fn insert(&mut self, key: &str, value: Value);
+}
+
+impl TomlExt for Value {
+    fn read(&self, key: &str) -> Option<&Value> {
+        if let Some((head, tail)) = split(key) {
+            self.get(head)?.read(tail)
+        } else {
+            self.get(key)
+        }
+    }
+
+    fn insert(&mut self, key: &str, value: Value) {
+        if !self.is_table() {
+            *self = Value::Table(Table::new());
+        }
+
+        let table = self.as_table_mut().expect("unreachable");
+
+        if let Some((head, tail)) = split(key) {
+            table
+                .entry(head)
+                .or_insert_with(|| Value::Table(Table::new()))
+                .insert(tail, value);
+        } else {
+            table.insert(key.to_string(), value);
+        }
+    }
+}
+
+fn split(key: &str) -> Option<(&str, &str)> {
+    let ix = key.find('.')?;
+
+    let (head, tail) = key.split_at(ix);
+    // splitting will leave the "."
+    let tail = &tail[1..];
+
+    Some((head, tail))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn read_simple_table() {
+        let src = "[table]";
+        let value: Value = toml::from_str(src).unwrap();
+
+        let got = value.read("table").unwrap();
+
+        assert!(got.is_table());
+    }
+
+    #[test]
+    fn read_nested_item() {
+        let src = "[table]\nnested=true";
+        let value: Value = toml::from_str(src).unwrap();
+
+        let got = value.read("table.nested").unwrap();
+
+        assert_eq!(got, &Value::Boolean(true));
+    }
+
+    #[test]
+    fn insert_item_at_top_level() {
+        let mut value = Value::Table(Table::default());
+        let item = Value::Boolean(true);
+
+        value.insert("first", item.clone());
+
+        assert_eq!(value.get("first").unwrap(), &item);
+    }
+
+    #[test]
+    fn insert_nested_item() {
+        let mut value = Value::Table(Table::default());
+        let item = Value::Boolean(true);
+
+        value.insert("first.second", item.clone());
+
+        let inserted = value.read("first.second").unwrap();
+        assert_eq!(inserted, &item);
+    }
+}

crates/mdbook-driver/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "mdbook-driver"
+version = "0.5.0-beta.1"
+description = "High-level library for running mdBook"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+indexmap.workspace = true
+mdbook-core.workspace = true
+mdbook-html.workspace = true
+mdbook-markdown.workspace = true
+mdbook-preprocessor.workspace = true
+mdbook-renderer.workspace = true
+mdbook-summary.workspace = true
+regex.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+shlex.workspace = true
+tempfile.workspace = true
+toml.workspace = true
+topological-sort.workspace = true
+tracing.workspace = true
+
+[lints]
+workspace = true
+
+[features]
+search = ["mdbook-html/search"]

crates/mdbook-driver/README.md

@@ -0,0 +1,13 @@
+# mdbook-driver
+
+[![Documentation](https://img.shields.io/docsrs/mdbook-driver)](https://docs.rs/mdbook-driver)
+[![crates.io](https://img.shields.io/crates/v/mdbook-driver.svg)](https://crates.io/crates/mdbook-driver)
+[![Changelog](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md)
+
+This is the high-level Rust library for running [mdBook](https://rust-lang.github.io/mdBook/). New books can be created using [`BookBuilder`](https://docs.rs/mdbook-driver/latest/mdbook_driver/init/struct.BookBuilder.html). The primary type [`MDBook`](https://docs.rs/mdbook-driver/latest/mdbook_driver/struct.MDBook.html) can be used to manage and render books.
+
+> This crate is maintained by the mdBook team for use by the wider ecosystem. This crate follows [semver compatibility](https://doc.rust-lang.org/cargo/reference/semver.html) for its APIs.
+
+## License
+
+[Mozilla Public License, version 2.0](https://github.com/rust-lang/mdBook/blob/master/LICENSE)

crates/mdbook-driver/src/builtin_preprocessors/cmd.rs

@@ -0,0 +1,183 @@
+use anyhow::{Context, Result, ensure};
+use mdbook_core::book::Book;
+use mdbook_preprocessor::{Preprocessor, PreprocessorContext};
+use std::io::Write;
+use std::path::PathBuf;
+use std::process::{Child, Stdio};
+use tracing::{debug, trace, warn};
+
+/// A custom preprocessor which will shell out to a 3rd-party program.
+///
+/// See <https://rust-lang.github.io/mdBook/for_developers/preprocessors.html>
+/// for a description of the preprocessor protocol.
+#[derive(Debug, Clone, PartialEq)]
+pub struct CmdPreprocessor {
+    name: String,
+    cmd: String,
+    root: PathBuf,
+    optional: bool,
+}
+
+impl CmdPreprocessor {
+    /// Create a new `CmdPreprocessor`.
+    pub fn new(name: String, cmd: String, root: PathBuf, optional: bool) -> CmdPreprocessor {
+        CmdPreprocessor {
+            name,
+            cmd,
+            root,
+            optional,
+        }
+    }
+
+    fn write_input_to_child(&self, child: &mut Child, book: &Book, ctx: &PreprocessorContext) {
+        let stdin = child.stdin.take().expect("Child has stdin");
+
+        if let Err(e) = self.write_input(stdin, book, ctx) {
+            // Looks like the backend hung up before we could finish
+            // sending it the render context. Log the error and keep going
+            warn!("Error writing the RenderContext to the backend, {}", e);
+        }
+    }
+
+    fn write_input<W: Write>(
+        &self,
+        writer: W,
+        book: &Book,
+        ctx: &PreprocessorContext,
+    ) -> Result<()> {
+        serde_json::to_writer(writer, &(ctx, book)).map_err(Into::into)
+    }
+
+    /// The command this `Preprocessor` will invoke.
+    pub fn cmd(&self) -> &str {
+        &self.cmd
+    }
+}
+
+impl Preprocessor for CmdPreprocessor {
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn run(&self, ctx: &PreprocessorContext, book: Book) -> Result<Book> {
+        let mut cmd = crate::compose_command(&self.cmd, &ctx.root)?;
+
+        let mut child = match cmd
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit())
+            .current_dir(&self.root)
+            .spawn()
+        {
+            Ok(c) => c,
+            Err(e) => {
+                crate::handle_command_error(
+                    e,
+                    self.optional,
+                    "preprocessor",
+                    "preprocessor",
+                    &self.name,
+                    &self.cmd,
+                )?;
+                // This should normally not be reached, since the validation
+                // for NotFound should have already happened when running the
+                // "supports" command.
+                return Ok(book);
+            }
+        };
+
+        self.write_input_to_child(&mut child, &book, ctx);
+
+        let output = child.wait_with_output().with_context(|| {
+            format!(
+                "Error waiting for the \"{}\" preprocessor to complete",
+                self.name
+            )
+        })?;
+
+        trace!("{} exited with output: {:?}", self.cmd, output);
+        ensure!(
+            output.status.success(),
+            format!(
+                "The \"{}\" preprocessor exited unsuccessfully with {} status",
+                self.name, output.status
+            )
+        );
+
+        serde_json::from_slice(&output.stdout).with_context(|| {
+            format!(
+                "Unable to parse the preprocessed book from \"{}\" processor",
+                self.name
+            )
+        })
+    }
+
+    fn supports_renderer(&self, renderer: &str) -> Result<bool> {
+        debug!(
+            "Checking if the \"{}\" preprocessor supports \"{}\"",
+            self.name(),
+            renderer
+        );
+
+        let mut cmd = crate::compose_command(&self.cmd, &self.root)?;
+
+        match cmd
+            .arg("supports")
+            .arg(renderer)
+            .stdin(Stdio::null())
+            .stdout(Stdio::inherit())
+            .stderr(Stdio::inherit())
+            .current_dir(&self.root)
+            .status()
+        {
+            Ok(status) => Ok(status.code() == Some(0)),
+            Err(e) => {
+                crate::handle_command_error(
+                    e,
+                    self.optional,
+                    "preprocessor",
+                    "preprocessor",
+                    &self.name,
+                    &self.cmd,
+                )?;
+                Ok(false)
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::MDBook;
+    use std::path::Path;
+
+    fn guide() -> MDBook {
+        let example = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../guide");
+        MDBook::load(example).unwrap()
+    }
+
+    #[test]
+    fn round_trip_write_and_parse_input() {
+        let md = guide();
+        let cmd = CmdPreprocessor::new(
+            "test".to_string(),
+            "test".to_string(),
+            md.root.clone(),
+            false,
+        );
+        let ctx = PreprocessorContext::new(
+            md.root.clone(),
+            md.config.clone(),
+            "some-renderer".to_string(),
+        );
+
+        let mut buffer = Vec::new();
+        cmd.write_input(&mut buffer, &md.book, &ctx).unwrap();
+
+        let (got_ctx, got_book) = mdbook_preprocessor::parse_input(buffer.as_slice()).unwrap();
+
+        assert_eq!(got_book, md.book);
+        assert_eq!(got_ctx, ctx);
+    }
+}

crates/mdbook-driver/src/builtin_preprocessors/index.rs

@@ -1,18 +1,19 @@
-use regex::Regex;
+use anyhow::Result;
+use mdbook_core::book::{Book, BookItem};
+use mdbook_core::static_regex;
+use mdbook_preprocessor::{Preprocessor, PreprocessorContext};
 use std::path::Path;
-
-use crate::errors::*;
-
-use super::{Preprocessor, PreprocessorContext};
-use crate::book::{Book, BookItem};
+use tracing::warn;
 
 /// A preprocessor for converting file name `README.md` to `index.md` since
 /// `README.md` is the de facto index file in markdown-based documentation.
 #[derive(Default)]
+#[non_exhaustive]
 pub struct IndexPreprocessor;
 
 impl IndexPreprocessor {
-    pub(crate) const NAME: &'static str = "index";
+    /// Name of this preprocessor.
+    pub const NAME: &'static str = "index";
 
     /// Create a new `IndexPreprocessor`.
     pub fn new() -> Self {
@@ -29,13 +30,15 @@ impl Preprocessor for IndexPreprocessor {
         let source_dir = ctx.root.join(&ctx.config.book.src);
         book.for_each_mut(|section: &mut BookItem| {
             if let BookItem::Chapter(ref mut ch) = *section {
-                if is_readme_file(&ch.path) {
-                    let index_md = source_dir.join(ch.path.with_file_name("index.md"));
-                    if index_md.exists() {
-                        warn_readme_name_conflict(&ch.path, &index_md);
-                    }
+                if let Some(ref mut path) = ch.path {
+                    if is_readme_file(&path) {
+                        let mut index_md = source_dir.join(path.with_file_name("index.md"));
+                        if index_md.exists() {
+                            warn_readme_name_conflict(&path, &&mut index_md);
+                        }
 
-                    ch.path.set_file_name("index.md");
+                        path.set_file_name("index.md");
+                    }
                 }
             }
         });
@@ -65,10 +68,9 @@ fn warn_readme_name_conflict<P: AsRef<Path>>(readme_path: P, index_path: P) {
 }
 
 fn is_readme_file<P: AsRef<Path>>(path: P) -> bool {
-    lazy_static! {
-        static ref RE: Regex = Regex::new(r"(?i)^readme$").unwrap();
-    }
-    RE.is_match(
+    static_regex!(README, r"(?i)^readme$");
+
+    README.is_match(
         path.as_ref()
             .file_stem()
             .and_then(std::ffi::OsStr::to_str)

crates/mdbook-driver/src/builtin_preprocessors/links.rs

@@ -1,15 +1,18 @@
-use crate::errors::*;
-use crate::utils::{
+use self::take_lines::{
     take_anchored_lines, take_lines, take_rustdoc_include_anchored_lines,
     take_rustdoc_include_lines,
 };
-use regex::{CaptureMatches, Captures, Regex};
-use std::fs;
+use anyhow::{Context, Result};
+use mdbook_core::book::{Book, BookItem};
+use mdbook_core::static_regex;
+use mdbook_core::utils::fs;
+use mdbook_preprocessor::{Preprocessor, PreprocessorContext};
+use regex::{CaptureMatches, Captures};
 use std::ops::{Bound, Range, RangeBounds, RangeFrom, RangeFull, RangeTo};
 use std::path::{Path, PathBuf};
+use tracing::{error, warn};
 
-use super::{Preprocessor, PreprocessorContext};
-use crate::book::{Book, BookItem};
+mod take_lines;
 
 const ESCAPE_CHAR: char = '\\';
 const MAX_LINK_NESTED_DEPTH: usize = 10;
@@ -17,17 +20,20 @@ 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.
-/// - `{{# playpen}}` - Insert runnable Rust files
+/// - `{{# playground}}` - Insert runnable Rust files
+/// - `{{# title}}` - Override \<title\> of a webpage.
 #[derive(Default)]
+#[non_exhaustive]
 pub struct LinkPreprocessor;
 
 impl LinkPreprocessor {
-    pub(crate) const NAME: &'static str = "links";
+    /// Name of this preprocessor.
+    pub const NAME: &'static str = "links";
 
     /// Create a new `LinkPreprocessor`.
     pub fn new() -> Self {
@@ -45,14 +51,22 @@ impl Preprocessor for LinkPreprocessor {
 
         book.for_each_mut(|section: &mut BookItem| {
             if let BookItem::Chapter(ref mut ch) = *section {
-                let base = ch
-                    .path
-                    .parent()
-                    .map(|dir| src_dir.join(dir))
-                    .expect("All book items have a parent");
+                if let Some(ref chapter_path) = ch.path {
+                    let base = chapter_path
+                        .parent()
+                        .map(|dir| src_dir.join(dir))
+                        .expect("All book items have a parent");
 
-                let content = replace_all(&ch.content, base, &ch.path, 0);
-                ch.content = content;
+                    let mut chapter_title = ch.name.clone();
+                    let content =
+                        replace_all(&ch.content, base, chapter_path, 0, &mut chapter_title);
+                    ch.content = content;
+                    if chapter_title != ch.name {
+                        ctx.chapter_titles
+                            .borrow_mut()
+                            .insert(chapter_path.clone(), chapter_title);
+                    }
+                }
             }
         });
 
@@ -60,7 +74,13 @@ impl Preprocessor for LinkPreprocessor {
     }
 }
 
-fn replace_all<P1, P2>(s: &str, path: P1, source: P2, depth: usize) -> String
+fn replace_all<P1, P2>(
+    s: &str,
+    path: P1,
+    source: P2,
+    depth: usize,
+    chapter_title: &mut String,
+) -> String
 where
     P1: AsRef<Path>,
     P2: AsRef<Path>,
@@ -76,11 +96,17 @@ where
     for link in find_links(s) {
         replaced.push_str(&s[previous_end_index..link.start_index]);
 
-        match link.render_with_path(&path) {
+        match link.render_with_path(path, chapter_title) {
             Ok(new_content) => {
                 if depth < MAX_LINK_NESTED_DEPTH {
                     if let Some(rel_path) = link.link_type.relative_path(path) {
-                        replaced.push_str(&replace_all(&new_content, rel_path, source, depth + 1));
+                        replaced.push_str(&replace_all(
+                            &new_content,
+                            rel_path,
+                            source,
+                            depth + 1,
+                            chapter_title,
+                        ));
                     } else {
                         replaced.push_str(&new_content);
                     }
@@ -94,7 +120,7 @@ where
             }
             Err(e) => {
                 error!("Error updating \"{}\", {}", link.link_text, e);
-                for cause in e.iter().skip(1) {
+                for cause in e.chain().skip(1) {
                     warn!("Caused By: {}", cause);
                 }
 
@@ -113,8 +139,9 @@ where
 enum LinkType<'a> {
     Escaped,
     Include(PathBuf, RangeOrAnchor),
-    Playpen(PathBuf, Vec<&'a str>),
+    Playground(PathBuf, Vec<&'a str>),
     RustdocInclude(PathBuf, RangeOrAnchor),
+    Title(&'a str),
 }
 
 #[derive(PartialEq, Debug, Clone)]
@@ -182,8 +209,9 @@ impl<'a> LinkType<'a> {
         match self {
             LinkType::Escaped => None,
             LinkType::Include(p, _) => Some(return_relative_path(base, &p)),
-            LinkType::Playpen(p, _) => Some(return_relative_path(base, &p)),
+            LinkType::Playground(p, _) => Some(return_relative_path(base, &p)),
             LinkType::RustdocInclude(p, _) => Some(return_relative_path(base, &p)),
+            LinkType::Title(_) => None,
         }
     }
 }
@@ -254,6 +282,9 @@ struct Link<'a> {
 impl<'a> Link<'a> {
     fn from_capture(cap: Captures<'a>) -> Option<Link<'a>> {
         let link_type = match (cap.get(0), cap.get(1), cap.get(2)) {
+            (_, Some(typ), Some(title)) if typ.as_str() == "title" => {
+                Some(LinkType::Title(title.as_str()))
+            }
             (_, Some(typ), Some(rest)) => {
                 let mut path_props = rest.as_str().split_whitespace();
                 let file_arg = path_props.next();
@@ -261,7 +292,15 @@ impl<'a> Link<'a> {
 
                 match (typ.as_str(), file_arg) {
                     ("include", Some(pth)) => Some(parse_include_path(pth)),
-                    ("playpen", Some(pth)) => Some(LinkType::Playpen(pth.into(), props)),
+                    ("playground", Some(pth)) => Some(LinkType::Playground(pth.into(), props)),
+                    ("playpen", Some(pth)) => {
+                        warn!(
+                            "the {{{{#playpen}}}} expression has been \
+                            renamed to {{{{#playground}}}}, \
+                            please update your book to use the new name"
+                        );
+                        Some(LinkType::Playground(pth.into(), props))
+                    }
                     ("rustdoc_include", Some(pth)) => Some(parse_rustdoc_include_path(pth)),
                     _ => None,
                 }
@@ -282,11 +321,15 @@ impl<'a> Link<'a> {
         })
     }
 
-    fn render_with_path<P: AsRef<Path>>(&self, base: P) -> Result<String> {
+    fn render_with_path<P: AsRef<Path>>(
+        &self,
+        base: P,
+        chapter_title: &mut String,
+    ) -> Result<String> {
         let base = base.as_ref();
         match self.link_type {
             // omit the escape char
-            LinkType::Escaped => Ok((&self.link_text[1..]).to_owned()),
+            LinkType::Escaped => Ok(self.link_text[1..].to_owned()),
             LinkType::Include(ref pat, ref range_or_anchor) => {
                 let target = base.join(pat);
 
@@ -295,7 +338,7 @@ impl<'a> Link<'a> {
                         RangeOrAnchor::Range(range) => take_lines(&s, range.clone()),
                         RangeOrAnchor::Anchor(anchor) => take_anchored_lines(&s, anchor),
                     })
-                    .chain_err(|| {
+                    .with_context(|| {
                         format!(
                             "Could not read file for link {} ({})",
                             self.link_text,
@@ -315,7 +358,7 @@ impl<'a> Link<'a> {
                             take_rustdoc_include_anchored_lines(&s, anchor)
                         }
                     })
-                    .chain_err(|| {
+                    .with_context(|| {
                         format!(
                             "Could not read file for link {} ({})",
                             self.link_text,
@@ -323,10 +366,10 @@ impl<'a> Link<'a> {
                         )
                     })
             }
-            LinkType::Playpen(ref pat, ref attrs) => {
+            LinkType::Playground(ref pat, ref attrs) => {
                 let target = base.join(pat);
 
-                let contents = fs::read_to_string(&target).chain_err(|| {
+                let mut contents = fs::read_to_string(&target).with_context(|| {
                     format!(
                         "Could not read file for link {} ({})",
                         self.link_text,
@@ -334,13 +377,20 @@ impl<'a> Link<'a> {
                     )
                 })?;
                 let ftype = if !attrs.is_empty() { "rust," } else { "rust" };
+                if !contents.ends_with('\n') {
+                    contents.push('\n');
+                }
                 Ok(format!(
-                    "```{}{}\n{}\n```\n",
+                    "```{}{}\n{}```\n",
                     ftype,
                     attrs.join(","),
                     contents
                 ))
             }
+            LinkType::Title(title) => {
+                *chapter_title = title.to_owned();
+                Ok(String::new())
+            }
         }
     }
 }
@@ -360,22 +410,19 @@ impl<'a> Iterator for LinkIter<'a> {
 }
 
 fn find_links(contents: &str) -> LinkIter<'_> {
-    // lazily compute following regex
-    // r"\\\{\{#.*\}\}|\{\{#([a-zA-Z0-9]+)\s*([a-zA-Z0-9_.\-:/\\\s]+)\}\}")?;
-    lazy_static! {
-        static ref RE: Regex = Regex::new(
-            r"(?x)                     # insignificant whitespace mode
-            \\\{\{\#.*\}\}             # match escaped link
-            |                          # or
-            \{\{\s*                    # link opening parens and whitespace
-            \#([a-zA-Z0-9_]+)          # link type
-            \s+                        # separating whitespace
-            ([a-zA-Z0-9\s_.\-:/\\]+)   # link target path and space separated properties
-            \s*\}\}                    # whitespace and link closing parens"
-        )
-        .unwrap();
-    }
-    LinkIter(RE.captures_iter(contents))
+    static_regex!(
+        LINK,
+        r"(?x)              # insignificant whitespace mode
+        \\\{\{\#.*\}\}      # match escaped link
+        |                   # or
+        \{\{\s*             # link opening parens and whitespace
+        \#([a-zA-Z0-9_]+)   # link type
+        \s+                 # separating whitespace
+        ([^}]+)             # link target path and space separated properties
+        \}\}                # link closing parens"
+    );
+
+    LinkIter(LINK.captures_iter(contents))
 }
 
 #[cfg(test)]
@@ -394,7 +441,21 @@ mod tests {
         ```hbs
         {{#include file.rs}} << an escaped link!
         ```";
-        assert_eq!(replace_all(start, "", "", 0), end);
+        let mut chapter_title = "test_replace_all_escaped".to_owned();
+        assert_eq!(replace_all(start, "", "", 0, &mut chapter_title), end);
+    }
+
+    #[test]
+    fn test_set_chapter_title() {
+        let start = r"{{#title My Title}}
+        # My Chapter
+        ";
+        let end = r"
+        # My Chapter
+        ";
+        let mut chapter_title = "test_set_chapter_title".to_owned();
+        assert_eq!(replace_all(start, "", "", 0, &mut chapter_title), end);
+        assert_eq!(chapter_title, "My Title");
     }
 
     #[test]
@@ -405,7 +466,7 @@ mod tests {
 
     #[test]
     fn test_find_links_partial_link() {
-        let s = "Some random text with {{#playpen...";
+        let s = "Some random text with {{#playground...";
         assert!(find_links(s).collect::<Vec<_>>() == vec![]);
         let s = "Some random text with {{#include...";
         assert!(find_links(s).collect::<Vec<_>>() == vec![]);
@@ -415,47 +476,65 @@ mod tests {
 
     #[test]
     fn test_find_links_empty_link() {
-        let s = "Some random text with {{#playpen}} and {{#playpen   }} {{}} {{#}}...";
+        let s = "Some random text with {{#playground}} and {{#playground   }} {{}} {{#}}...";
         assert!(find_links(s).collect::<Vec<_>>() == vec![]);
     }
 
     #[test]
     fn test_find_links_unknown_link_type() {
-        let s = "Some random text with {{#playpenz ar.rs}} and {{#incn}} {{baz}} {{#bar}}...";
+        let s = "Some random text with {{#playgroundz ar.rs}} and {{#incn}} {{baz}} {{#bar}}...";
         assert!(find_links(s).collect::<Vec<_>>() == vec![]);
     }
 
     #[test]
     fn test_find_links_simple_link() {
-        let s = "Some random text with {{#playpen file.rs}} and {{#playpen test.rs }}...";
+        let s = "Some random text with {{#playground file.rs}} and {{#playground test.rs }}...";
 
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
 
         assert_eq!(
             res,
             vec![
                 Link {
                     start_index: 22,
-                    end_index: 42,
-                    link_type: LinkType::Playpen(PathBuf::from("file.rs"), vec![]),
-                    link_text: "{{#playpen file.rs}}",
+                    end_index: 45,
+                    link_type: LinkType::Playground(PathBuf::from("file.rs"), vec![]),
+                    link_text: "{{#playground file.rs}}",
                 },
                 Link {
-                    start_index: 47,
-                    end_index: 68,
-                    link_type: LinkType::Playpen(PathBuf::from("test.rs"), vec![]),
-                    link_text: "{{#playpen test.rs }}",
+                    start_index: 50,
+                    end_index: 74,
+                    link_type: LinkType::Playground(PathBuf::from("test.rs"), vec![]),
+                    link_text: "{{#playground test.rs }}",
                 },
             ]
         );
     }
 
+    #[test]
+    fn test_find_links_with_special_characters() {
+        let s = "Some random text with {{#playground foo-bar\\baz/_c++.rs}}...";
+
+        let res = find_links(s).collect::<Vec<_>>();
+        println!("\nOUTPUT: {res:?}\n");
+
+        assert_eq!(
+            res,
+            vec![Link {
+                start_index: 22,
+                end_index: 57,
+                link_type: LinkType::Playground(PathBuf::from("foo-bar\\baz/_c++.rs"), vec![]),
+                link_text: "{{#playground foo-bar\\baz/_c++.rs}}",
+            },]
+        );
+    }
+
     #[test]
     fn test_find_links_with_range() {
         let s = "Some random text with {{#include file.rs:10:20}}...";
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![Link {
@@ -474,7 +553,7 @@ mod tests {
     fn test_find_links_with_line_number() {
         let s = "Some random text with {{#include file.rs:10}}...";
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![Link {
@@ -493,7 +572,7 @@ mod tests {
     fn test_find_links_with_from_range() {
         let s = "Some random text with {{#include file.rs:10:}}...";
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![Link {
@@ -512,7 +591,7 @@ mod tests {
     fn test_find_links_with_to_range() {
         let s = "Some random text with {{#include file.rs::20}}...";
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![Link {
@@ -531,7 +610,7 @@ mod tests {
     fn test_find_links_with_full_range() {
         let s = "Some random text with {{#include file.rs::}}...";
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![Link {
@@ -550,7 +629,7 @@ mod tests {
     fn test_find_links_with_no_range_specified() {
         let s = "Some random text with {{#include file.rs}}...";
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![Link {
@@ -569,7 +648,7 @@ mod tests {
     fn test_find_links_with_anchor() {
         let s = "Some random text with {{#include file.rs:anchor}}...";
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![Link {
@@ -586,46 +665,46 @@ mod tests {
 
     #[test]
     fn test_find_links_escaped_link() {
-        let s = "Some random text with escaped playpen \\{{#playpen file.rs editable}} ...";
+        let s = "Some random text with escaped playground \\{{#playground file.rs editable}} ...";
 
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
 
         assert_eq!(
             res,
             vec![Link {
-                start_index: 38,
-                end_index: 68,
+                start_index: 41,
+                end_index: 74,
                 link_type: LinkType::Escaped,
-                link_text: "\\{{#playpen file.rs editable}}",
+                link_text: "\\{{#playground file.rs editable}}",
             }]
         );
     }
 
     #[test]
-    fn test_find_playpens_with_properties() {
-        let s = "Some random text with escaped playpen {{#playpen file.rs editable }} and some \
-                 more\n text {{#playpen my.rs editable no_run should_panic}} ...";
+    fn test_find_playgrounds_with_properties() {
+        let s = "Some random text with escaped playground {{#playground file.rs editable }} and some \
+                 more\n text {{#playground my.rs editable no_run should_panic}} ...";
 
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(
             res,
             vec![
                 Link {
-                    start_index: 38,
-                    end_index: 68,
-                    link_type: LinkType::Playpen(PathBuf::from("file.rs"), vec!["editable"]),
-                    link_text: "{{#playpen file.rs editable }}",
+                    start_index: 41,
+                    end_index: 74,
+                    link_type: LinkType::Playground(PathBuf::from("file.rs"), vec!["editable"]),
+                    link_text: "{{#playground file.rs editable }}",
                 },
                 Link {
-                    start_index: 89,
-                    end_index: 136,
-                    link_type: LinkType::Playpen(
+                    start_index: 95,
+                    end_index: 145,
+                    link_type: LinkType::Playground(
                         PathBuf::from("my.rs"),
                         vec!["editable", "no_run", "should_panic"],
                     ),
-                    link_text: "{{#playpen my.rs editable no_run should_panic}}",
+                    link_text: "{{#playground my.rs editable no_run should_panic}}",
                 },
             ]
         );
@@ -633,18 +712,18 @@ mod tests {
 
     #[test]
     fn test_find_all_link_types() {
-        let s = "Some random text with escaped playpen {{#include file.rs}} and \\{{#contents are \
-                 insignifficant in escaped link}} some more\n text  {{#playpen my.rs editable \
+        let s = "Some random text with escaped playground {{#include file.rs}} and \\{{#contents are \
+                 insignifficant in escaped link}} some more\n text  {{#playground my.rs editable \
                  no_run should_panic}} ...";
 
         let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {:?}\n", res);
+        println!("\nOUTPUT: {res:?}\n");
         assert_eq!(res.len(), 3);
         assert_eq!(
             res[0],
             Link {
-                start_index: 38,
-                end_index: 58,
+                start_index: 41,
+                end_index: 61,
                 link_type: LinkType::Include(
                     PathBuf::from("file.rs"),
                     RangeOrAnchor::Range(LineRange::from(..))
@@ -655,8 +734,8 @@ mod tests {
         assert_eq!(
             res[1],
             Link {
-                start_index: 63,
-                end_index: 112,
+                start_index: 66,
+                end_index: 115,
                 link_type: LinkType::Escaped,
                 link_text: "\\{{#contents are insignifficant in escaped link}}",
             }
@@ -664,13 +743,13 @@ mod tests {
         assert_eq!(
             res[2],
             Link {
-                start_index: 130,
-                end_index: 177,
-                link_type: LinkType::Playpen(
+                start_index: 133,
+                end_index: 183,
+                link_type: LinkType::Playground(
                     PathBuf::from("my.rs"),
                     vec!["editable", "no_run", "should_panic"]
                 ),
-                link_text: "{{#playpen my.rs editable no_run should_panic}}",
+                link_text: "{{#playground my.rs editable no_run should_panic}}",
             }
         );
     }

crates/mdbook-driver/src/builtin_preprocessors/links/take_lines.rs

@@ -1,31 +1,34 @@
-use itertools::Itertools;
-use regex::Regex;
+use mdbook_core::static_regex;
 use std::ops::Bound::{Excluded, Included, Unbounded};
 use std::ops::RangeBounds;
 
 /// Take a range of lines from a string.
-pub fn take_lines<R: RangeBounds<usize>>(s: &str, range: R) -> String {
+pub(super) fn take_lines<R: RangeBounds<usize>>(s: &str, range: R) -> String {
     let start = match range.start_bound() {
         Excluded(&n) => n + 1,
         Included(&n) => n,
         Unbounded => 0,
     };
-    let mut lines = s.lines().skip(start);
+    let lines = s.lines().skip(start);
     match range.end_bound() {
-        Excluded(end) => lines.take(end.saturating_sub(start)).join("\n"),
-        Included(end) => lines.take((end + 1).saturating_sub(start)).join("\n"),
-        Unbounded => lines.join("\n"),
+        Excluded(end) => lines
+            .take(end.saturating_sub(start))
+            .collect::<Vec<_>>()
+            .join("\n"),
+        Included(end) => lines
+            .take((end + 1).saturating_sub(start))
+            .collect::<Vec<_>>()
+            .join("\n"),
+        Unbounded => lines.collect::<Vec<_>>().join("\n"),
     }
 }
 
-lazy_static! {
-    static ref ANCHOR_START: Regex = Regex::new(r"ANCHOR:\s*(?P<anchor_name>[\w_-]+)").unwrap();
-    static ref ANCHOR_END: Regex = Regex::new(r"ANCHOR_END:\s*(?P<anchor_name>[\w_-]+)").unwrap();
-}
+static_regex!(ANCHOR_START, r"ANCHOR:\s*(?P<anchor_name>[\w_-]+)");
+static_regex!(ANCHOR_END, r"ANCHOR_END:\s*(?P<anchor_name>[\w_-]+)");
 
 /// Take anchored lines from a string.
 /// Lines containing anchor are ignored.
-pub fn take_anchored_lines(s: &str, anchor: &str) -> String {
+pub(super) fn take_anchored_lines(s: &str, anchor: &str) -> String {
     let mut retained = Vec::<&str>::new();
     let mut anchor_found = false;
 
@@ -43,11 +46,9 @@ pub fn take_anchored_lines(s: &str, anchor: &str) -> String {
                     }
                 }
             }
-        } else {
-            if let Some(cap) = ANCHOR_START.captures(l) {
-                if &cap["anchor_name"] == anchor {
-                    anchor_found = true;
-                }
+        } else if let Some(cap) = ANCHOR_START.captures(l) {
+            if &cap["anchor_name"] == anchor {
+                anchor_found = true;
             }
         }
     }
@@ -59,7 +60,7 @@ pub fn take_anchored_lines(s: &str, anchor: &str) -> String {
 /// For any lines not in the range, include them but use `#` at the beginning. This will hide the
 /// lines from initial display but include them when expanding the code snippet or testing with
 /// rustdoc.
-pub fn take_rustdoc_include_lines<R: RangeBounds<usize>>(s: &str, range: R) -> String {
+pub(super) fn take_rustdoc_include_lines<R: RangeBounds<usize>>(s: &str, range: R) -> String {
     let mut output = String::with_capacity(s.len());
 
     for (index, line) in s.lines().enumerate() {
@@ -67,7 +68,7 @@ pub fn take_rustdoc_include_lines<R: RangeBounds<usize>>(s: &str, range: R) -> S
             output.push_str("# ");
         }
         output.push_str(line);
-        output.push_str("\n");
+        output.push('\n');
     }
     output.pop();
     output
@@ -77,7 +78,7 @@ pub fn take_rustdoc_include_lines<R: RangeBounds<usize>>(s: &str, range: R) -> S
 /// For any lines not between the anchors, include them but use `#` at the beginning. This will
 /// hide the lines from initial display but include them when expanding the code snippet or testing
 /// with rustdoc.
-pub fn take_rustdoc_include_anchored_lines(s: &str, anchor: &str) -> String {
+pub(super) fn take_rustdoc_include_anchored_lines(s: &str, anchor: &str) -> String {
     let mut output = String::with_capacity(s.len());
     let mut within_anchored_section = false;
 
@@ -92,20 +93,18 @@ pub fn take_rustdoc_include_anchored_lines(s: &str, anchor: &str) -> String {
                 None => {
                     if !ANCHOR_START.is_match(l) {
                         output.push_str(l);
-                        output.push_str("\n");
+                        output.push('\n');
                     }
                 }
             }
-        } else {
-            if let Some(cap) = ANCHOR_START.captures(l) {
-                if &cap["anchor_name"] == anchor {
-                    within_anchored_section = true;
-                }
-            } else if !ANCHOR_END.is_match(l) {
-                output.push_str("# ");
-                output.push_str(l);
-                output.push_str("\n");
+        } else if let Some(cap) = ANCHOR_START.captures(l) {
+            if &cap["anchor_name"] == anchor {
+                within_anchored_section = true;
             }
+        } else if !ANCHOR_END.is_match(l) {
+            output.push_str("# ");
+            output.push_str(l);
+            output.push('\n');
         }
     }
 
@@ -121,6 +120,7 @@ mod tests {
     };
 
     #[test]
+    #[allow(clippy::reversed_empty_ranges)] // Intentionally checking that those are correctly handled
     fn take_lines_test() {
         let s = "Lorem\nipsum\ndolor\nsit\namet";
         assert_eq!(take_lines(s, 1..3), "ipsum\ndolor");
@@ -162,6 +162,7 @@ mod tests {
     }
 
     #[test]
+    #[allow(clippy::reversed_empty_ranges)] // Intentionally checking that those are correctly handled
     fn take_rustdoc_include_lines_test() {
         let s = "Lorem\nipsum\ndolor\nsit\namet";
         assert_eq!(

crates/mdbook-driver/src/builtin_preprocessors/mod.rs

@@ -0,0 +1,9 @@
+//! Built-in preprocessors.
+
+pub use self::cmd::CmdPreprocessor;
+pub use self::index::IndexPreprocessor;
+pub use self::links::LinkPreprocessor;
+
+mod cmd;
+mod index;
+mod links;

crates/mdbook-driver/src/builtin_renderers/markdown_renderer.rs

@@ -1,13 +1,12 @@
-use crate::book::BookItem;
-use crate::errors::*;
-use crate::renderer::{RenderContext, Renderer};
-use crate::utils;
+use anyhow::{Context, Result};
+use mdbook_core::utils::fs;
+use mdbook_renderer::{RenderContext, Renderer};
+use tracing::trace;
 
-use std::fs;
-
-#[derive(Default)]
 /// A renderer to output the Markdown after the preprocessors have run. Mostly useful
 /// when debugging preprocessors.
+#[derive(Default)]
+#[non_exhaustive]
 pub struct MarkdownRenderer;
 
 impl MarkdownRenderer {
@@ -27,19 +26,20 @@ impl Renderer for MarkdownRenderer {
         let book = &ctx.book;
 
         if destination.exists() {
-            utils::fs::remove_dir_content(destination)
-                .chain_err(|| "Unable to remove stale Markdown output")?;
+            fs::remove_dir_content(destination)
+                .with_context(|| "Unable to remove stale Markdown output")?;
         }
 
         trace!("markdown render");
-        for item in book.iter() {
-            if let BookItem::Chapter(ref ch) = *item {
-                utils::fs::write_file(&ctx.destination, &ch.path, ch.content.as_bytes())?;
-            }
+        for ch in book.chapters() {
+            let path = ctx
+                .destination
+                .join(ch.path.as_ref().expect("Checked path exists before"));
+            fs::write(path, &ch.content)?;
         }
 
-        fs::create_dir_all(&destination)
-            .chain_err(|| "Unexpected error when constructing destination path")?;
+        fs::create_dir_all(destination)
+            .with_context(|| "Unexpected error when constructing destination path")?;
 
         Ok(())
     }

crates/mdbook-driver/src/builtin_renderers/mod.rs

@@ -0,0 +1,88 @@
+//! Built-in renderers.
+//!
+//! The HTML renderer can be found in the [`mdbook_html`] crate.
+
+use anyhow::{Context, Result, bail};
+use mdbook_core::utils::fs;
+use mdbook_renderer::{RenderContext, Renderer};
+use std::process::Stdio;
+use tracing::{error, info, trace, warn};
+
+pub use self::markdown_renderer::MarkdownRenderer;
+
+mod markdown_renderer;
+
+/// A generic renderer which will shell out to an arbitrary executable.
+///
+/// See <https://rust-lang.github.io/mdBook/for_developers/backends.html>
+/// for a description of the renderer protocol.
+#[derive(Debug, Clone, PartialEq)]
+pub struct CmdRenderer {
+    name: String,
+    cmd: String,
+}
+
+impl CmdRenderer {
+    /// Create a new `CmdRenderer` which will invoke the provided `cmd` string.
+    pub fn new(name: String, cmd: String) -> CmdRenderer {
+        CmdRenderer { name, cmd }
+    }
+}
+
+impl Renderer for CmdRenderer {
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn render(&self, ctx: &RenderContext) -> Result<()> {
+        info!("Invoking the \"{}\" renderer", self.name);
+
+        let optional_key = format!("output.{}.optional", self.name);
+        let optional = match ctx.config.get(&optional_key) {
+            Ok(Some(value)) => value,
+            Err(e) => bail!("expected bool for `{optional_key}`: {e}"),
+            Ok(None) => false,
+        };
+
+        let _ = fs::create_dir_all(&ctx.destination);
+
+        let mut cmd = crate::compose_command(&self.cmd, &ctx.root)?;
+        let mut child = match cmd
+            .stdin(Stdio::piped())
+            .stdout(Stdio::inherit())
+            .stderr(Stdio::inherit())
+            .current_dir(&ctx.destination)
+            .spawn()
+        {
+            Ok(c) => c,
+            Err(e) => {
+                return crate::handle_command_error(
+                    e, optional, "output", "backend", &self.name, &self.cmd,
+                );
+            }
+        };
+
+        let mut stdin = child.stdin.take().expect("Child has stdin");
+        if let Err(e) = serde_json::to_writer(&mut stdin, &ctx) {
+            // Looks like the backend hung up before we could finish
+            // sending it the render context. Log the error and keep going
+            warn!("Error writing the RenderContext to the backend, {}", e);
+        }
+
+        // explicitly close the `stdin` file handle
+        drop(stdin);
+
+        let status = child
+            .wait()
+            .with_context(|| "Error waiting for the backend to complete")?;
+
+        trace!("{} exited with output: {:?}", self.cmd, status);
+
+        if !status.success() {
+            error!("Renderer exited with non-zero return code.");
+            bail!("The \"{}\" renderer failed", self.name);
+        } else {
+            Ok(())
+        }
+    }
+}

crates/mdbook-driver/src/init.rs

@@ -1,11 +1,12 @@
-use std::fs::{self, File};
-use std::io::Write;
-use std::path::PathBuf;
+//! Support for initializing a new book.
 
 use super::MDBook;
-use crate::config::Config;
-use crate::errors::*;
-use crate::theme;
+use anyhow::{Context, Result};
+use mdbook_core::config::Config;
+use mdbook_core::utils::fs;
+use mdbook_html::theme::Theme;
+use std::path::PathBuf;
+use tracing::{debug, error, info, trace};
 
 /// A helper for setting up a new book and its directory structure.
 #[derive(Debug, Clone, PartialEq)]
@@ -28,7 +29,7 @@ impl BookBuilder {
         }
     }
 
-    /// Set the `Config` to be used.
+    /// Set the [`Config`] to be used.
     pub fn with_config(&mut self, cfg: Config) -> &mut BookBuilder {
         self.config = cfg;
         self
@@ -64,19 +65,19 @@ impl BookBuilder {
         info!("Creating a new book with stub content");
 
         self.create_directory_structure()
-            .chain_err(|| "Unable to create directory structure")?;
+            .with_context(|| "Unable to create directory structure")?;
 
         self.create_stub_files()
-            .chain_err(|| "Unable to create stub files")?;
+            .with_context(|| "Unable to create stub files")?;
 
         if self.create_gitignore {
             self.build_gitignore()
-                .chain_err(|| "Unable to create .gitignore")?;
+                .with_context(|| "Unable to create .gitignore")?;
         }
 
         if self.copy_theme {
             self.copy_across_theme()
-                .chain_err(|| "Unable to copy across the theme")?;
+                .with_context(|| "Unable to copy across the theme")?;
         }
 
         self.write_book_toml()?;
@@ -97,73 +98,26 @@ impl BookBuilder {
     fn write_book_toml(&self) -> Result<()> {
         debug!("Writing book.toml");
         let book_toml = self.root.join("book.toml");
-        let cfg = toml::to_vec(&self.config).chain_err(|| "Unable to serialize the config")?;
+        let cfg =
+            toml::to_string(&self.config).with_context(|| "Unable to serialize the config")?;
 
-        File::create(book_toml)
-            .chain_err(|| "Couldn't create book.toml")?
-            .write_all(&cfg)
-            .chain_err(|| "Unable to write config to book.toml")?;
+        fs::write(&book_toml, cfg)?;
         Ok(())
     }
 
     fn copy_across_theme(&self) -> Result<()> {
         debug!("Copying theme");
 
-        let themedir = self
-            .config
-            .html_config()
-            .and_then(|html| html.theme)
-            .unwrap_or_else(|| self.config.book.src.join("theme"));
-        let themedir = self.root.join(themedir);
-
-        if !themedir.exists() {
-            debug!(
-                "{} does not exist, creating the directory",
-                themedir.display()
-            );
-            fs::create_dir(&themedir)?;
-        }
-
-        let mut index = File::create(themedir.join("index.hbs"))?;
-        index.write_all(theme::INDEX)?;
-
-        let cssdir = themedir.join("css");
-        fs::create_dir(&cssdir)?;
-
-        let mut general_css = File::create(cssdir.join("general.css"))?;
-        general_css.write_all(theme::GENERAL_CSS)?;
-
-        let mut chrome_css = File::create(cssdir.join("chrome.css"))?;
-        chrome_css.write_all(theme::CHROME_CSS)?;
-
-        let mut print_css = File::create(cssdir.join("print.css"))?;
-        print_css.write_all(theme::PRINT_CSS)?;
-
-        let mut variables_css = File::create(cssdir.join("variables.css"))?;
-        variables_css.write_all(theme::VARIABLES_CSS)?;
-
-        let mut favicon = File::create(themedir.join("favicon.png"))?;
-        favicon.write_all(theme::FAVICON)?;
-
-        let mut js = File::create(themedir.join("book.js"))?;
-        js.write_all(theme::JS)?;
-
-        let mut highlight_css = File::create(themedir.join("highlight.css"))?;
-        highlight_css.write_all(theme::HIGHLIGHT_CSS)?;
-
-        let mut highlight_js = File::create(themedir.join("highlight.js"))?;
-        highlight_js.write_all(theme::HIGHLIGHT_JS)?;
-
+        let html_config = self.config.html_config().unwrap_or_default();
+        Theme::copy_theme(&html_config, &self.root)?;
         Ok(())
     }
 
     fn build_gitignore(&self) -> Result<()> {
-        debug!("Creating .gitignore");
-
-        let mut f = File::create(self.root.join(".gitignore"))?;
-
-        writeln!(f, "{}", self.config.build.build_dir.display())?;
-
+        fs::write(
+            self.root.join(".gitignore"),
+            format!("{}", self.config.build.build_dir.display()),
+        )?;
         Ok(())
     }
 
@@ -174,14 +128,14 @@ impl BookBuilder {
         let summary = src_dir.join("SUMMARY.md");
         if !summary.exists() {
             trace!("No summary found creating stub summary and chapter_1.md.");
-            let mut f = File::create(&summary).chain_err(|| "Unable to create SUMMARY.md")?;
-            writeln!(f, "# Summary")?;
-            writeln!(f)?;
-            writeln!(f, "- [Chapter 1](./chapter_1.md)")?;
+            fs::write(
+                summary,
+                "# Summary\n\
+                 \n\
+                 - [Chapter 1](./chapter_1.md)\n",
+            )?;
 
-            let chapter_1 = src_dir.join("chapter_1.md");
-            let mut f = File::create(&chapter_1).chain_err(|| "Unable to create chapter_1.md")?;
-            writeln!(f, "# Chapter 1")?;
+            fs::write(src_dir.join("chapter_1.md"), "# Chapter 1\n")?;
         } else {
             trace!("Existing summary found, no need to create stub files.");
         }
@@ -193,10 +147,10 @@ impl BookBuilder {
         fs::create_dir_all(&self.root)?;
 
         let src = self.root.join(&self.config.book.src);
-        fs::create_dir_all(&src)?;
+        fs::create_dir_all(src)?;
 
         let build = self.root.join(&self.config.build.build_dir);
-        fs::create_dir_all(&build)?;
+        fs::create_dir_all(build)?;
 
         Ok(())
     }

crates/mdbook-driver/src/lib.rs

@@ -0,0 +1,131 @@
+//! High-level library for running mdBook.
+//!
+//! This is the high-level library for running
+//! [mdBook](https://rust-lang.github.io/mdBook/). There are several
+//! reasons for using the programmatic API (over the CLI):
+//!
+//! - Integrate mdBook in a current project.
+//! - Extend the capabilities of mdBook.
+//! - Do some processing or test before building your book.
+//! - Accessing the public API to help create a new Renderer.
+//!
+//! ## Additional crates
+//!
+//! In addition to `mdbook-driver`, there are several other crates available
+//! for using and extending mdBook:
+//!
+//! - [`mdbook_preprocessor`]: Provides support for implementing preprocessors.
+//! - [`mdbook_renderer`]: Provides support for implementing renderers.
+//! - [`mdbook_markdown`]: The Markdown renderer.
+//! - [`mdbook_summary`]: The `SUMMARY.md` parser.
+//! - [`mdbook_html`]: The HTML renderer.
+//! - [`mdbook_core`]: An internal library that is used by the other crates
+//!   for shared types. Types from this crate are rexported from the other
+//!   crates as appropriate.
+//!
+//! ## Cargo features
+//!
+//! The following cargo features are available:
+//!
+//! - `search`: Enables the search index in the HTML renderer.
+//!
+//! ## Examples
+//!
+//! If creating a new book from scratch, you'll want to get a [`init::BookBuilder`] via
+//! the [`MDBook::init()`] method.
+//!
+//! ```rust,no_run
+//! use mdbook_driver::MDBook;
+//! use mdbook_driver::config::Config;
+//!
+//! let root_dir = "/path/to/book/root";
+//!
+//! // create a default config and change a couple things
+//! let mut cfg = Config::default();
+//! cfg.book.title = Some("My Book".to_string());
+//! cfg.book.authors.push("Michael-F-Bryan".to_string());
+//!
+//! MDBook::init(root_dir)
+//!     .create_gitignore(true)
+//!     .with_config(cfg)
+//!     .build()
+//!     .expect("Book generation failed");
+//! ```
+//!
+//! You can also load an existing book and build it.
+//!
+//! ```rust,no_run
+//! use mdbook_driver::MDBook;
+//!
+//! let root_dir = "/path/to/book/root";
+//!
+//! let mut md = MDBook::load(root_dir)
+//!     .expect("Unable to load the book");
+//! md.build().expect("Building failed");
+//! ```
+
+pub mod builtin_preprocessors;
+pub mod builtin_renderers;
+pub mod init;
+mod load;
+mod mdbook;
+
+use anyhow::{Context, Result, bail};
+pub use mdbook::MDBook;
+pub use mdbook_core::{book, config, errors};
+use shlex::Shlex;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use tracing::{error, warn};
+
+/// Creates a [`Command`] for command renderers and preprocessors.
+fn compose_command(cmd: &str, root: &Path) -> Result<Command> {
+    let mut words = Shlex::new(cmd);
+    let exe = match words.next() {
+        Some(e) => PathBuf::from(e),
+        None => bail!("Command string was empty"),
+    };
+
+    let exe = if exe.components().count() == 1 {
+        // Search PATH for the executable.
+        exe
+    } else {
+        // Relative path is relative to book root.
+        root.join(&exe)
+    };
+
+    let mut cmd = Command::new(exe);
+
+    for arg in words {
+        cmd.arg(arg);
+    }
+
+    Ok(cmd)
+}
+
+/// Handles a failure for a preprocessor or renderer.
+fn handle_command_error(
+    error: std::io::Error,
+    optional: bool,
+    key: &str,
+    what: &str,
+    name: &str,
+    cmd: &str,
+) -> Result<()> {
+    if let std::io::ErrorKind::NotFound = error.kind() {
+        if optional {
+            warn!(
+                "The command `{cmd}` for {what} `{name}` was not found, \
+                 but is marked as optional.",
+            );
+            return Ok(());
+        } else {
+            error!(
+                "The command `{cmd}` wasn't found, is the `{name}` {what} installed? \
+                If you want to ignore this error when the `{name}` {what} is not installed, \
+                set `optional = true` in the `[{key}.{name}]` section of the book.toml configuration file.",
+            );
+        }
+    }
+    Err(error).with_context(|| format!("Unable to run the {what} `{name}`"))?
+}

crates/mdbook-driver/src/load.rs

@@ -0,0 +1,309 @@
+use anyhow::{Context, Result};
+use mdbook_core::book::{Book, BookItem, Chapter};
+use mdbook_core::config::BuildConfig;
+use mdbook_core::utils::{escape_html, fs};
+use mdbook_summary::{Link, Summary, SummaryItem, parse_summary};
+use std::path::Path;
+use tracing::debug;
+
+/// Load a book into memory from its `src/` directory.
+pub(crate) fn load_book<P: AsRef<Path>>(src_dir: P, cfg: &BuildConfig) -> Result<Book> {
+    let src_dir = src_dir.as_ref();
+    let summary_md = src_dir.join("SUMMARY.md");
+
+    let summary_content = fs::read_to_string(&summary_md)?;
+    let summary = parse_summary(&summary_content)
+        .with_context(|| format!("Summary parsing failed for file={summary_md:?}"))?;
+
+    if cfg.create_missing {
+        create_missing(src_dir, &summary).with_context(|| "Unable to create missing chapters")?;
+    }
+
+    load_book_from_disk(&summary, src_dir)
+}
+
+fn create_missing(src_dir: &Path, summary: &Summary) -> Result<()> {
+    let mut items: Vec<_> = summary
+        .prefix_chapters
+        .iter()
+        .chain(summary.numbered_chapters.iter())
+        .chain(summary.suffix_chapters.iter())
+        .collect();
+
+    while let Some(next) = items.pop() {
+        if let SummaryItem::Link(ref link) = *next {
+            if let Some(ref location) = link.location {
+                let filename = src_dir.join(location);
+                if !filename.exists() {
+                    if let Some(parent) = filename.parent() {
+                        if !parent.exists() {
+                            fs::create_dir_all(parent)?;
+                        }
+                    }
+                    debug!("Creating missing file {}", filename.display());
+                    let title = escape_html(&link.name);
+                    fs::write(&filename, format!("# {title}\n"))?;
+                }
+            }
+
+            items.extend(&link.nested_items);
+        }
+    }
+
+    Ok(())
+}
+
+/// Use the provided `Summary` to load a `Book` from disk.
+///
+/// You need to pass in the book's source directory because all the links in
+/// `SUMMARY.md` give the chapter locations relative to it.
+pub(crate) fn load_book_from_disk<P: AsRef<Path>>(summary: &Summary, src_dir: P) -> Result<Book> {
+    debug!("Loading the book from disk");
+    let src_dir = src_dir.as_ref();
+
+    let prefix = summary.prefix_chapters.iter();
+    let numbered = summary.numbered_chapters.iter();
+    let suffix = summary.suffix_chapters.iter();
+
+    let summary_items = prefix.chain(numbered).chain(suffix);
+
+    let mut chapters = Vec::new();
+
+    for summary_item in summary_items {
+        let chapter = load_summary_item(summary_item, src_dir, Vec::new())?;
+        chapters.push(chapter);
+    }
+
+    Ok(Book::new_with_items(chapters))
+}
+
+fn load_summary_item<P: AsRef<Path> + Clone>(
+    item: &SummaryItem,
+    src_dir: P,
+    parent_names: Vec<String>,
+) -> Result<BookItem> {
+    match item {
+        SummaryItem::Separator => Ok(BookItem::Separator),
+        SummaryItem::Link(link) => load_chapter(link, src_dir, parent_names).map(BookItem::Chapter),
+        SummaryItem::PartTitle(title) => Ok(BookItem::PartTitle(title.clone())),
+        _ => panic!("SummaryItem {item:?} not covered"),
+    }
+}
+
+fn load_chapter<P: AsRef<Path>>(
+    link: &Link,
+    src_dir: P,
+    parent_names: Vec<String>,
+) -> Result<Chapter> {
+    let src_dir = src_dir.as_ref();
+
+    let mut ch = if let Some(ref link_location) = link.location {
+        debug!("Loading {} ({})", link.name, link_location.display());
+
+        let location = if link_location.is_absolute() {
+            link_location.clone()
+        } else {
+            src_dir.join(link_location)
+        };
+
+        let mut content = std::fs::read_to_string(&location)
+            .with_context(|| format!("failed to read chapter `{}`", link_location.display()))?;
+
+        if content.as_bytes().starts_with(b"\xef\xbb\xbf") {
+            content.replace_range(..3, "");
+        }
+
+        let stripped = location
+            .strip_prefix(src_dir)
+            .expect("Chapters are always inside a book");
+
+        Chapter::new(&link.name, content, stripped, parent_names.clone())
+    } else {
+        Chapter::new_draft(&link.name, parent_names.clone())
+    };
+
+    let mut sub_item_parents = parent_names;
+
+    ch.number = link.number.clone();
+
+    sub_item_parents.push(link.name.clone());
+    let sub_items = link
+        .nested_items
+        .iter()
+        .map(|i| load_summary_item(i, src_dir, sub_item_parents.clone()))
+        .collect::<Result<Vec<_>>>()?;
+
+    ch.sub_items = sub_items;
+
+    Ok(ch)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use mdbook_core::book::SectionNumber;
+    use std::path::PathBuf;
+    use tempfile::{Builder as TempFileBuilder, TempDir};
+
+    const DUMMY_SRC: &str = "
+# Dummy Chapter
+
+this is some dummy text.
+
+And here is some \
+                                     more text.
+";
+
+    /// Create a dummy `Link` in a temporary directory.
+    fn dummy_link() -> (Link, TempDir) {
+        let temp = TempFileBuilder::new().prefix("book").tempdir().unwrap();
+
+        let chapter_path = temp.path().join("chapter_1.md");
+        fs::write(&chapter_path, DUMMY_SRC).unwrap();
+
+        let link = Link::new("Chapter 1", chapter_path);
+
+        (link, temp)
+    }
+
+    /// Create a nested `Link` written to a temporary directory.
+    fn nested_links() -> (Link, TempDir) {
+        let (mut root, temp_dir) = dummy_link();
+
+        let second_path = temp_dir.path().join("second.md");
+        fs::write(&second_path, "Hello World!").unwrap();
+
+        let mut second = Link::new("Nested Chapter 1", &second_path);
+        second.number = Some(SectionNumber::new([1, 2]));
+
+        root.nested_items.push(second.clone().into());
+        root.nested_items.push(SummaryItem::Separator);
+        root.nested_items.push(second.into());
+
+        (root, temp_dir)
+    }
+
+    #[test]
+    fn load_a_single_chapter_from_disk() {
+        let (link, temp_dir) = dummy_link();
+        let should_be = Chapter::new(
+            "Chapter 1",
+            DUMMY_SRC.to_string(),
+            "chapter_1.md",
+            Vec::new(),
+        );
+
+        let got = load_chapter(&link, temp_dir.path(), Vec::new()).unwrap();
+        assert_eq!(got, should_be);
+    }
+
+    #[test]
+    fn load_a_single_chapter_with_utf8_bom_from_disk() {
+        let temp_dir = TempFileBuilder::new().prefix("book").tempdir().unwrap();
+
+        let chapter_path = temp_dir.path().join("chapter_1.md");
+        fs::write(&chapter_path, format!("\u{feff}{DUMMY_SRC}")).unwrap();
+
+        let link = Link::new("Chapter 1", chapter_path);
+
+        let should_be = Chapter::new(
+            "Chapter 1",
+            DUMMY_SRC.to_string(),
+            "chapter_1.md",
+            Vec::new(),
+        );
+
+        let got = load_chapter(&link, temp_dir.path(), Vec::new()).unwrap();
+        assert_eq!(got, should_be);
+    }
+
+    #[test]
+    fn cant_load_a_nonexistent_chapter() {
+        let link = Link::new("Chapter 1", "/foo/bar/baz.md");
+
+        let got = load_chapter(&link, "", Vec::new());
+        assert!(got.is_err());
+    }
+
+    #[test]
+    fn load_recursive_link_with_separators() {
+        let (root, temp) = nested_links();
+
+        let mut nested = Chapter::new(
+            "Nested Chapter 1",
+            String::from("Hello World!"),
+            "second.md",
+            vec![String::from("Chapter 1")],
+        );
+        nested.number = Some(SectionNumber::new([1, 2]));
+        let mut chapter =
+            Chapter::new("Chapter 1", String::from(DUMMY_SRC), "chapter_1.md", vec![]);
+        chapter.sub_items = vec![
+            BookItem::Chapter(nested.clone()),
+            BookItem::Separator,
+            BookItem::Chapter(nested),
+        ];
+        let should_be = BookItem::Chapter(chapter);
+
+        let got = load_summary_item(&SummaryItem::Link(root), temp.path(), Vec::new()).unwrap();
+        assert_eq!(got, should_be);
+    }
+
+    #[test]
+    fn load_a_book_with_a_single_chapter() {
+        let (link, temp) = dummy_link();
+        let mut summary = Summary::default();
+        summary.numbered_chapters = vec![SummaryItem::Link(link)];
+        let chapter = Chapter::new(
+            "Chapter 1",
+            String::from(DUMMY_SRC),
+            PathBuf::from("chapter_1.md"),
+            vec![],
+        );
+        let items = vec![BookItem::Chapter(chapter)];
+        let should_be = Book::new_with_items(items);
+
+        let got = load_book_from_disk(&summary, temp.path()).unwrap();
+
+        assert_eq!(got, should_be);
+    }
+
+    #[test]
+    fn cant_load_chapters_with_an_empty_path() {
+        let (_, temp) = dummy_link();
+        let mut summary = Summary::default();
+        let link = Link::new("Empty", "");
+        summary.numbered_chapters = vec![SummaryItem::Link(link)];
+        let got = load_book_from_disk(&summary, temp.path());
+        assert!(got.is_err());
+    }
+
+    #[test]
+    fn cant_load_chapters_when_the_link_is_a_directory() {
+        let (_, temp) = dummy_link();
+        let dir = temp.path().join("nested");
+        fs::create_dir_all(&dir).unwrap();
+
+        let mut summary = Summary::default();
+        let link = Link::new("nested", dir);
+        summary.numbered_chapters = vec![SummaryItem::Link(link)];
+
+        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 expected = format!(
+            r#"failed to read `{}`"#,
+            temp_dir.path().join("SUMMARY.md").display()
+        );
+        assert_eq!(error_message, expected);
+    }
+}

crates/mdbook-driver/src/mdbook.rs

@@ -0,0 +1,574 @@
+//! The high-level interface for loading and rendering books.
+
+use crate::builtin_preprocessors::{CmdPreprocessor, IndexPreprocessor, LinkPreprocessor};
+use crate::builtin_renderers::{CmdRenderer, MarkdownRenderer};
+use crate::init::BookBuilder;
+use crate::load::{load_book, load_book_from_disk};
+use anyhow::{Context, Error, Result, bail};
+use indexmap::IndexMap;
+use mdbook_core::book::{Book, BookItem, BookItems};
+use mdbook_core::config::{Config, RustEdition};
+use mdbook_core::utils::fs;
+use mdbook_html::HtmlHandlebars;
+use mdbook_preprocessor::{Preprocessor, PreprocessorContext};
+use mdbook_renderer::{RenderContext, Renderer};
+use mdbook_summary::Summary;
+use serde::Deserialize;
+use std::ffi::OsString;
+use std::io::IsTerminal;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use tempfile::Builder as TempFileBuilder;
+use topological_sort::TopologicalSort;
+use tracing::{debug, error, info, trace, warn};
+
+#[cfg(test)]
+mod tests;
+
+/// The object used to manage and build a book.
+pub struct MDBook {
+    /// The book's root directory.
+    pub root: PathBuf,
+
+    /// The configuration used to tweak now a book is built.
+    pub config: Config,
+
+    /// A representation of the book's contents in memory.
+    pub book: Book,
+
+    /// Renderers to execute.
+    renderers: IndexMap<String, Box<dyn Renderer>>,
+
+    /// Pre-processors to be run on the book.
+    preprocessors: IndexMap<String, Box<dyn Preprocessor>>,
+}
+
+impl MDBook {
+    /// Load a book from its root directory on disk.
+    pub fn load<P: Into<PathBuf>>(book_root: P) -> Result<MDBook> {
+        let book_root = book_root.into();
+        let config_location = book_root.join("book.toml");
+
+        let mut config = if config_location.exists() {
+            debug!("Loading config from {}", config_location.display());
+            Config::from_disk(&config_location)?
+        } else {
+            Config::default()
+        };
+
+        config.update_from_env();
+
+        if tracing::enabled!(tracing::Level::TRACE) {
+            for line in format!("Config: {config:#?}").lines() {
+                trace!("{}", line);
+            }
+        }
+
+        MDBook::load_with_config(book_root, config)
+    }
+
+    /// Load a book from its root directory using a custom `Config`.
+    pub fn load_with_config<P: Into<PathBuf>>(book_root: P, config: Config) -> Result<MDBook> {
+        let root = book_root.into();
+
+        let src_dir = root.join(&config.book.src);
+        let book = load_book(src_dir, &config.build)?;
+
+        let renderers = determine_renderers(&config)?;
+        let preprocessors = determine_preprocessors(&config, &root)?;
+
+        Ok(MDBook {
+            root,
+            config,
+            book,
+            renderers,
+            preprocessors,
+        })
+    }
+
+    /// Load a book from its root directory using a custom `Config` and a custom summary.
+    pub fn load_with_config_and_summary<P: Into<PathBuf>>(
+        book_root: P,
+        config: Config,
+        summary: Summary,
+    ) -> Result<MDBook> {
+        let root = book_root.into();
+
+        let src_dir = root.join(&config.book.src);
+        let book = load_book_from_disk(&summary, src_dir)?;
+
+        let renderers = determine_renderers(&config)?;
+        let preprocessors = determine_preprocessors(&config, &root)?;
+
+        Ok(MDBook {
+            root,
+            config,
+            book,
+            renderers,
+            preprocessors,
+        })
+    }
+
+    /// Returns a flat depth-first iterator over the [`BookItem`]s of the book.
+    ///
+    /// ```no_run
+    /// # use mdbook_driver::MDBook;
+    /// # use mdbook_driver::book::BookItem;
+    /// # let book = MDBook::load("mybook").unwrap();
+    /// for item in book.iter() {
+    ///     match *item {
+    ///         BookItem::Chapter(ref chapter) => {},
+    ///         BookItem::Separator => {},
+    ///         BookItem::PartTitle(ref title) => {}
+    ///         _ => {}
+    ///     }
+    /// }
+    ///
+    /// // would print something like this:
+    /// // 1. Chapter 1
+    /// // 1.1 Sub Chapter
+    /// // 1.2 Sub Chapter
+    /// // 2. Chapter 2
+    /// //
+    /// // etc.
+    /// ```
+    pub fn iter(&self) -> BookItems<'_> {
+        self.book.iter()
+    }
+
+    /// `init()` gives you a `BookBuilder` which you can use to setup a new book
+    /// and its accompanying directory structure.
+    ///
+    /// The `BookBuilder` creates some boilerplate files and directories to get
+    /// you started with your book.
+    ///
+    /// ```text
+    /// book-test/
+    /// ├── book
+    /// └── src
+    ///     ├── chapter_1.md
+    ///     └── SUMMARY.md
+    /// ```
+    ///
+    /// It uses the path provided as the root directory for your book, then adds
+    /// in a `src/` directory containing a `SUMMARY.md` and `chapter_1.md` file
+    /// to get you started.
+    pub fn init<P: Into<PathBuf>>(book_root: P) -> BookBuilder {
+        BookBuilder::new(book_root)
+    }
+
+    /// Tells the renderer to build our book and put it in the build directory.
+    pub fn build(&self) -> Result<()> {
+        info!("Book building has started");
+
+        for renderer in self.renderers.values() {
+            self.execute_build_process(&**renderer)?;
+        }
+
+        Ok(())
+    }
+
+    /// Run preprocessors and return the final book.
+    pub fn preprocess_book(&self, renderer: &dyn Renderer) -> Result<(Book, PreprocessorContext)> {
+        let preprocess_ctx = PreprocessorContext::new(
+            self.root.clone(),
+            self.config.clone(),
+            renderer.name().to_string(),
+        );
+        let mut preprocessed_book = self.book.clone();
+        for preprocessor in self.preprocessors.values() {
+            if preprocessor_should_run(&**preprocessor, renderer, &self.config)? {
+                debug!("Running the {} preprocessor.", preprocessor.name());
+                preprocessed_book = preprocessor.run(&preprocess_ctx, preprocessed_book)?;
+            }
+        }
+        Ok((preprocessed_book, preprocess_ctx))
+    }
+
+    /// Run the entire build process for a particular [`Renderer`].
+    pub fn execute_build_process(&self, renderer: &dyn Renderer) -> Result<()> {
+        let (preprocessed_book, preprocess_ctx) = self.preprocess_book(renderer)?;
+
+        let name = renderer.name();
+        let build_dir = self.build_dir_for(name);
+
+        let mut render_context = RenderContext::new(
+            self.root.clone(),
+            preprocessed_book,
+            self.config.clone(),
+            build_dir,
+        );
+        render_context
+            .chapter_titles
+            .extend(preprocess_ctx.chapter_titles.borrow_mut().drain());
+
+        info!("Running the {} backend", renderer.name());
+        renderer
+            .render(&render_context)
+            .with_context(|| "Rendering failed")
+    }
+
+    /// You can change the default renderer to another one by using this method.
+    /// The only requirement is that your renderer implement the [`Renderer`]
+    /// trait.
+    pub fn with_renderer<R: Renderer + 'static>(&mut self, renderer: R) -> &mut Self {
+        self.renderers
+            .insert(renderer.name().to_string(), Box::new(renderer));
+        self
+    }
+
+    /// Register a [`Preprocessor`] to be used when rendering the book.
+    pub fn with_preprocessor<P: Preprocessor + 'static>(&mut self, preprocessor: P) -> &mut Self {
+        self.preprocessors
+            .insert(preprocessor.name().to_string(), Box::new(preprocessor));
+        self
+    }
+
+    /// Run `rustdoc` tests on the book, linking against the provided libraries.
+    pub fn test(&mut self, library_paths: Vec<&str>) -> Result<()> {
+        // test_chapter with chapter:None will run all tests.
+        self.test_chapter(library_paths, None)
+    }
+
+    /// Run `rustdoc` tests on a specific chapter of the book, linking against the provided libraries.
+    /// If `chapter` is `None`, all tests will be run.
+    pub fn test_chapter(&mut self, library_paths: Vec<&str>, chapter: Option<&str>) -> Result<()> {
+        let cwd = std::env::current_dir()?;
+        let library_args: Vec<OsString> = library_paths
+            .into_iter()
+            .flat_map(|path| {
+                let path = Path::new(path);
+                let path = if path.is_relative() {
+                    cwd.join(path).into_os_string()
+                } else {
+                    path.to_path_buf().into_os_string()
+                };
+                [OsString::from("-L"), path]
+            })
+            .collect();
+
+        let temp_dir = TempFileBuilder::new().prefix("mdbook-").tempdir()?;
+
+        let mut chapter_found = false;
+
+        struct TestRenderer;
+        impl Renderer for TestRenderer {
+            // FIXME: Is "test" the proper renderer name to use here?
+            fn name(&self) -> &str {
+                "test"
+            }
+
+            fn render(&self, _: &RenderContext) -> Result<()> {
+                Ok(())
+            }
+        }
+
+        // Index Preprocessor is disabled so that chapter paths
+        // continue to point to the actual markdown files.
+        self.preprocessors = determine_preprocessors(&self.config, &self.root)?;
+        self.preprocessors
+            .shift_remove_entry(IndexPreprocessor::NAME);
+        let (book, _) = self.preprocess_book(&TestRenderer)?;
+
+        let color_output = std::io::stderr().is_terminal();
+        let mut failed = false;
+        for item in book.iter() {
+            if let BookItem::Chapter(ref ch) = *item {
+                let chapter_path = match ch.path {
+                    Some(ref path) if !path.as_os_str().is_empty() => path,
+                    _ => continue,
+                };
+
+                if let Some(chapter) = chapter {
+                    if ch.name != chapter && chapter_path.to_str() != Some(chapter) {
+                        if chapter == "?" {
+                            info!("Skipping chapter '{}'...", ch.name);
+                        }
+                        continue;
+                    }
+                }
+                chapter_found = true;
+                info!("Testing chapter '{}': {:?}", ch.name, chapter_path);
+
+                // write preprocessed file to tempdir
+                let path = temp_dir.path().join(chapter_path);
+                fs::write(&path, &ch.content)?;
+
+                let mut cmd = Command::new("rustdoc");
+                cmd.current_dir(temp_dir.path())
+                    .arg(chapter_path)
+                    .arg("--test")
+                    .args(&library_args);
+
+                if let Some(edition) = self.config.rust.edition {
+                    match edition {
+                        RustEdition::E2015 => {
+                            cmd.args(["--edition", "2015"]);
+                        }
+                        RustEdition::E2018 => {
+                            cmd.args(["--edition", "2018"]);
+                        }
+                        RustEdition::E2021 => {
+                            cmd.args(["--edition", "2021"]);
+                        }
+                        RustEdition::E2024 => {
+                            cmd.args(["--edition", "2024"]);
+                        }
+                        _ => panic!("RustEdition {edition:?} not covered"),
+                    }
+                }
+
+                if color_output {
+                    cmd.args(["--color", "always"]);
+                }
+
+                debug!("running {:?}", cmd);
+                let output = cmd
+                    .output()
+                    .with_context(|| "failed to execute `rustdoc`")?;
+
+                if !output.status.success() {
+                    failed = true;
+                    error!(
+                        "rustdoc returned an error:\n\
+                        \n--- stdout\n{}\n--- stderr\n{}",
+                        String::from_utf8_lossy(&output.stdout),
+                        String::from_utf8_lossy(&output.stderr)
+                    );
+                }
+            }
+        }
+        if failed {
+            bail!("One or more tests failed");
+        }
+        if let Some(chapter) = chapter {
+            if !chapter_found {
+                bail!("Chapter not found: {}", chapter);
+            }
+        }
+        Ok(())
+    }
+
+    /// The logic for determining where a backend should put its build
+    /// artefacts.
+    ///
+    /// If there is only 1 renderer, put it in the directory pointed to by the
+    /// `build.build_dir` key in [`Config`]. If there is more than one then the
+    /// renderer gets its own directory within the main build dir.
+    ///
+    /// i.e. If there were only one renderer (in this case, the HTML renderer):
+    ///
+    /// - build/
+    ///   - index.html
+    ///   - ...
+    ///
+    /// Otherwise if there are multiple:
+    ///
+    /// - build/
+    ///   - epub/
+    ///     - my_awesome_book.epub
+    ///   - html/
+    ///     - index.html
+    ///     - ...
+    ///   - latex/
+    ///     - my_awesome_book.tex
+    ///
+    pub fn build_dir_for(&self, backend_name: &str) -> PathBuf {
+        let build_dir = self.root.join(&self.config.build.build_dir);
+
+        if self.renderers.len() <= 1 {
+            build_dir
+        } else {
+            build_dir.join(backend_name)
+        }
+    }
+
+    /// Get the directory containing this book's source files.
+    pub fn source_dir(&self) -> PathBuf {
+        self.root.join(&self.config.book.src)
+    }
+
+    /// Get the directory containing the theme resources for the book.
+    pub fn theme_dir(&self) -> PathBuf {
+        self.config
+            .html_config()
+            .unwrap_or_default()
+            .theme_dir(&self.root)
+    }
+}
+
+/// An `output` table.
+#[derive(Deserialize)]
+struct OutputConfig {
+    command: Option<String>,
+}
+
+/// Look at the `Config` and try to figure out what renderers to use.
+fn determine_renderers(config: &Config) -> Result<IndexMap<String, Box<dyn Renderer>>> {
+    let mut renderers = IndexMap::new();
+
+    let outputs = config.outputs::<OutputConfig>()?;
+    renderers.extend(outputs.into_iter().map(|(key, table)| {
+        let renderer = if key == "html" {
+            Box::new(HtmlHandlebars::new()) as Box<dyn Renderer>
+        } else if key == "markdown" {
+            Box::new(MarkdownRenderer::new()) as Box<dyn Renderer>
+        } else {
+            let command = table.command.unwrap_or_else(|| format!("mdbook-{key}"));
+            Box::new(CmdRenderer::new(key.clone(), command))
+        };
+        (key, renderer)
+    }));
+
+    // if we couldn't find anything, add the HTML renderer as a default
+    if renderers.is_empty() {
+        renderers.insert("html".to_string(), Box::new(HtmlHandlebars::new()));
+    }
+
+    Ok(renderers)
+}
+
+const DEFAULT_PREPROCESSORS: &[&str] = &["links", "index"];
+
+fn is_default_preprocessor(pre: &dyn Preprocessor) -> bool {
+    let name = pre.name();
+    name == LinkPreprocessor::NAME || name == IndexPreprocessor::NAME
+}
+
+/// A `preprocessor` table.
+#[derive(Deserialize)]
+struct PreprocessorConfig {
+    command: Option<String>,
+    #[serde(default)]
+    before: Vec<String>,
+    #[serde(default)]
+    after: Vec<String>,
+    #[serde(default)]
+    optional: bool,
+}
+
+/// Look at the `MDBook` and try to figure out what preprocessors to run.
+fn determine_preprocessors(
+    config: &Config,
+    root: &Path,
+) -> Result<IndexMap<String, Box<dyn Preprocessor>>> {
+    // Collect the names of all preprocessors intended to be run, and the order
+    // in which they should be run.
+    let mut preprocessor_names = TopologicalSort::<String>::new();
+
+    if config.build.use_default_preprocessors {
+        for name in DEFAULT_PREPROCESSORS {
+            preprocessor_names.insert(name.to_string());
+        }
+    }
+
+    let preprocessor_table = config.preprocessors::<PreprocessorConfig>()?;
+
+    for (name, table) in preprocessor_table.iter() {
+        preprocessor_names.insert(name.to_string());
+
+        let exists = |name| {
+            (config.build.use_default_preprocessors && DEFAULT_PREPROCESSORS.contains(&name))
+                || preprocessor_table.contains_key(name)
+        };
+
+        for after in &table.before {
+            if !exists(&after) {
+                // Only warn so that preprocessors can be toggled on and off (e.g. for
+                // troubleshooting) without having to worry about order too much.
+                warn!(
+                    "preprocessor.{}.after contains \"{}\", which was not found",
+                    name, after
+                );
+            } else {
+                preprocessor_names.add_dependency(name, after);
+            }
+        }
+
+        for before in &table.after {
+            if !exists(&before) {
+                // See equivalent warning above for rationale
+                warn!(
+                    "preprocessor.{}.before contains \"{}\", which was not found",
+                    name, before
+                );
+            } else {
+                preprocessor_names.add_dependency(before, name);
+            }
+        }
+    }
+
+    // Now that all links have been established, queue preprocessors in a suitable order
+    let mut preprocessors = IndexMap::with_capacity(preprocessor_names.len());
+    // `pop_all()` returns an empty vector when no more items are not being depended upon
+    for mut names in std::iter::repeat_with(|| preprocessor_names.pop_all())
+        .take_while(|names| !names.is_empty())
+    {
+        // The `topological_sort` crate does not guarantee a stable order for ties, even across
+        // runs of the same program. Thus, we break ties manually by sorting.
+        // Careful: `str`'s default sorting, which we are implicitly invoking here, uses code point
+        // values ([1]), which may not be an alphabetical sort.
+        // As mentioned in [1], doing so depends on locale, which is not desirable for deciding
+        // preprocessor execution order.
+        // [1]: https://doc.rust-lang.org/stable/std/cmp/trait.Ord.html#impl-Ord-14
+        names.sort();
+        for name in names {
+            let preprocessor: Box<dyn Preprocessor> = match name.as_str() {
+                "links" => Box::new(LinkPreprocessor::new()),
+                "index" => Box::new(IndexPreprocessor::new()),
+                _ => {
+                    // The only way to request a custom preprocessor is through the `preprocessor`
+                    // table, so it must exist, be a table, and contain the key.
+                    let table = &preprocessor_table[&name];
+                    let command = table
+                        .command
+                        .to_owned()
+                        .unwrap_or_else(|| format!("mdbook-{name}"));
+                    Box::new(CmdPreprocessor::new(
+                        name.clone(),
+                        command,
+                        root.to_owned(),
+                        table.optional,
+                    ))
+                }
+            };
+            preprocessors.insert(name, preprocessor);
+        }
+    }
+
+    // "If `pop_all` returns an empty vector and `len` is not 0, there are cyclic dependencies."
+    // Normally, `len() == 0` is equivalent to `is_empty()`, so we'll use that.
+    if preprocessor_names.is_empty() {
+        Ok(preprocessors)
+    } else {
+        Err(Error::msg("Cyclic dependency detected in preprocessors"))
+    }
+}
+
+/// Check whether we should run a particular `Preprocessor` in combination
+/// with the renderer, falling back to `Preprocessor::supports_renderer()`
+/// method if the user doesn't say anything.
+///
+/// The `build.use-default-preprocessors` config option can be used to ensure
+/// default preprocessors always run if they support the renderer.
+fn preprocessor_should_run(
+    preprocessor: &dyn Preprocessor,
+    renderer: &dyn Renderer,
+    cfg: &Config,
+) -> Result<bool> {
+    // default preprocessors should be run by default (if supported)
+    if cfg.build.use_default_preprocessors && is_default_preprocessor(preprocessor) {
+        return preprocessor.supports_renderer(renderer.name());
+    }
+
+    let key = format!("preprocessor.{}.renderers", preprocessor.name());
+    let renderer_name = renderer.name();
+
+    match cfg.get::<Vec<String>>(&key) {
+        Ok(Some(explicit_renderers)) => {
+            Ok(explicit_renderers.iter().any(|name| name == renderer_name))
+        }
+        Ok(None) => preprocessor.supports_renderer(renderer_name),
+        Err(e) => bail!("failed to get `{key}`: {e}"),
+    }
+}

crates/mdbook-driver/src/mdbook/tests.rs

@@ -0,0 +1,284 @@
+use super::*;
+use std::str::FromStr;
+use toml::value::{Table, Value};
+
+#[test]
+fn config_defaults_to_html_renderer_if_empty() {
+    let cfg = Config::default();
+
+    // make sure we haven't got anything in the `output` table
+    assert!(cfg.outputs::<toml::Value>().unwrap().is_empty());
+
+    let got = determine_renderers(&cfg).unwrap();
+
+    assert_eq!(got.len(), 1);
+    assert_eq!(got[0].name(), "html");
+}
+
+#[test]
+fn add_a_random_renderer_to_the_config() {
+    let mut cfg = Config::default();
+    cfg.set("output.random", Table::new()).unwrap();
+
+    let got = determine_renderers(&cfg).unwrap();
+
+    assert_eq!(got.len(), 1);
+    assert_eq!(got[0].name(), "random");
+}
+
+#[test]
+fn add_a_random_renderer_with_custom_command_to_the_config() {
+    let mut cfg = Config::default();
+
+    let mut table = Table::new();
+    table.insert("command".to_string(), Value::String("false".to_string()));
+    cfg.set("output.random", table).unwrap();
+
+    let got = determine_renderers(&cfg).unwrap();
+
+    assert_eq!(got.len(), 1);
+    assert_eq!(got[0].name(), "random");
+}
+
+#[test]
+fn config_defaults_to_link_and_index_preprocessor_if_not_set() {
+    let cfg = Config::default();
+
+    // make sure we haven't got anything in the `preprocessor` table
+    assert!(cfg.preprocessors::<toml::Value>().unwrap().is_empty());
+
+    let got = determine_preprocessors(&cfg, Path::new("")).unwrap();
+
+    let names: Vec<_> = got.values().map(|p| p.name()).collect();
+    assert_eq!(names, ["index", "links"]);
+}
+
+#[test]
+fn use_default_preprocessors_works() {
+    let mut cfg = Config::default();
+    cfg.build.use_default_preprocessors = false;
+
+    let got = determine_preprocessors(&cfg, Path::new("")).unwrap();
+
+    assert_eq!(got.len(), 0);
+}
+
+#[test]
+fn can_determine_third_party_preprocessors() {
+    let cfg_str = r#"
+        [book]
+        title = "Some Book"
+
+        [preprocessor.random]
+
+        [build]
+        build-dir = "outputs"
+        create-missing = false
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    // make sure the `preprocessor.random` table exists
+    assert!(cfg.get::<Value>("preprocessor.random").unwrap().is_some());
+
+    let got = determine_preprocessors(&cfg, Path::new("")).unwrap();
+
+    assert!(got.contains_key("random"));
+}
+
+#[test]
+fn preprocessors_can_provide_their_own_commands() {
+    let cfg_str = r#"
+        [preprocessor.random]
+        command = "python random.py"
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    // make sure the `preprocessor.random` table exists
+    let random = cfg
+        .get::<OutputConfig>("preprocessor.random")
+        .unwrap()
+        .unwrap();
+    assert_eq!(random.command, Some("python random.py".to_string()));
+}
+
+#[test]
+fn preprocessor_before_must_be_array() {
+    let cfg_str = r#"
+        [preprocessor.random]
+        before = 0
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    assert!(determine_preprocessors(&cfg, Path::new("")).is_err());
+}
+
+#[test]
+fn preprocessor_after_must_be_array() {
+    let cfg_str = r#"
+        [preprocessor.random]
+        after = 0
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    assert!(determine_preprocessors(&cfg, Path::new("")).is_err());
+}
+
+#[test]
+fn preprocessor_order_is_honored() {
+    let cfg_str = r#"
+        [preprocessor.random]
+        before = [ "last" ]
+        after = [ "index" ]
+
+        [preprocessor.last]
+        after = [ "links", "index" ]
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    let preprocessors = determine_preprocessors(&cfg, Path::new("")).unwrap();
+    let index = |name| preprocessors.get_index_of(name).unwrap();
+    let assert_before = |before, after| {
+        if index(before) >= index(after) {
+            eprintln!("Preprocessor order:");
+            for preprocessor in preprocessors.keys() {
+                eprintln!("  {}", preprocessor);
+            }
+            panic!("{before} should come before {after}");
+        }
+    };
+
+    assert_before("index", "random");
+    assert_before("index", "last");
+    assert_before("random", "last");
+    assert_before("links", "last");
+}
+
+#[test]
+fn cyclic_dependencies_are_detected() {
+    let cfg_str = r#"
+        [preprocessor.links]
+        before = [ "index" ]
+
+        [preprocessor.index]
+        before = [ "links" ]
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    assert!(determine_preprocessors(&cfg, Path::new("")).is_err());
+}
+
+#[test]
+fn dependencies_dont_register_undefined_preprocessors() {
+    let cfg_str = r#"
+        [preprocessor.links]
+        before = [ "random" ]
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    let preprocessors = determine_preprocessors(&cfg, Path::new("")).unwrap();
+
+    // Does not contain "random"
+    assert_eq!(preprocessors.keys().collect::<Vec<_>>(), ["index", "links"]);
+}
+
+#[test]
+fn dependencies_dont_register_builtin_preprocessors_if_disabled() {
+    let cfg_str = r#"
+        [preprocessor.random]
+        before = [ "links" ]
+
+        [build]
+        use-default-preprocessors = false
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    let preprocessors = determine_preprocessors(&cfg, Path::new("")).unwrap();
+
+    // Does not contain "links"
+    assert_eq!(preprocessors.keys().collect::<Vec<_>>(), ["random"]);
+}
+
+#[test]
+fn config_respects_preprocessor_selection() {
+    let cfg_str = r#"
+        [preprocessor.links]
+        renderers = ["html"]
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    let html_renderer = HtmlHandlebars::default();
+    let pre = LinkPreprocessor::new();
+
+    let should_run = preprocessor_should_run(&pre, &html_renderer, &cfg).unwrap();
+    assert!(should_run);
+}
+
+struct BoolPreprocessor(bool);
+impl Preprocessor for BoolPreprocessor {
+    fn name(&self) -> &str {
+        "bool-preprocessor"
+    }
+
+    fn run(&self, _ctx: &PreprocessorContext, _book: Book) -> Result<Book> {
+        unimplemented!()
+    }
+
+    fn supports_renderer(&self, _renderer: &str) -> Result<bool> {
+        Ok(self.0)
+    }
+}
+
+#[test]
+fn preprocessor_should_run_falls_back_to_supports_renderer_method() {
+    let cfg = Config::default();
+    let html = HtmlHandlebars::new();
+
+    let should_be = true;
+    let got = preprocessor_should_run(&BoolPreprocessor(should_be), &html, &cfg).unwrap();
+    assert_eq!(got, should_be);
+
+    let should_be = false;
+    let got = preprocessor_should_run(&BoolPreprocessor(should_be), &html, &cfg).unwrap();
+    assert_eq!(got, should_be);
+}
+
+// Default is to sort preprocessors alphabetically.
+#[test]
+fn preprocessor_sorted_by_name() {
+    let cfg_str = r#"
+        [preprocessor.xyz]
+        [preprocessor.abc]
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    let got = determine_preprocessors(&cfg, Path::new("")).unwrap();
+
+    let names: Vec<_> = got.values().map(|p| p.name()).collect();
+    assert_eq!(names, ["abc", "index", "links", "xyz"]);
+}
+
+// Default is to sort renderers alphabetically.
+#[test]
+fn renderers_sorted_by_name() {
+    let cfg_str = r#"
+        [output.xyz]
+        [output.abc]
+        "#;
+
+    let cfg = Config::from_str(cfg_str).unwrap();
+
+    let got = determine_renderers(&cfg).unwrap();
+
+    let names: Vec<_> = got.values().map(|p| p.name()).collect();
+    assert_eq!(names, ["abc", "xyz"]);
+}

crates/mdbook-html/Cargo.toml

@@ -0,0 +1,37 @@
+[package]
+name = "mdbook-html"
+version = "0.5.0-beta.1"
+description = "mdBook HTML renderer"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+ego-tree.workspace = true
+elasticlunr-rs = { workspace = true, optional = true }
+font-awesome-as-a-crate.workspace = true
+handlebars.workspace = true
+hex.workspace = true
+html5ever.workspace = true
+indexmap.workspace = true
+mdbook-core.workspace = true
+mdbook-markdown.workspace = true
+mdbook-renderer.workspace = true
+pulldown-cmark.workspace = true
+regex.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+tracing.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+toml.workspace = true
+
+[lints]
+workspace = true
+
+[features]
+search = ["dep:elasticlunr-rs"]

crates/mdbook-html/README.md

@@ -0,0 +1,13 @@
+# mdbook-html
+
+[![Documentation](https://img.shields.io/docsrs/mdbook-html)](https://docs.rs/mdbook-html)
+[![crates.io](https://img.shields.io/crates/v/mdbook-html.svg)](https://crates.io/crates/mdbook-html)
+[![Changelog](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md)
+
+This is the HTML renderer for [mdBook](https://rust-lang.github.io/mdBook/). This is intended for internal use only. It is automatically included by [`mdbook-driver`](https://crates.io/crates/mdbook-driver) to render books to HTML.
+
+> This crate is maintained by the mdBook team, primarily for use by mdBook and not intended for external use (except as a transitive dependency). This crate may make major changes to its APIs or be deprecated without warning.
+
+## License
+
+[Mozilla Public License, version 2.0](https://github.com/rust-lang/mdBook/blob/master/LICENSE)

crates/mdbook-html/front-end/css/ayu-highlight.css

@@ -8,14 +8,11 @@ Original by Dempfi (https://github.com/dempfi/ayu)
   overflow-x: auto;
   background: #191f26;
   color: #e6e1cf;
-  padding: 0.5em;
 }
 
 .hljs-comment,
-.hljs-quote,
-.hljs-meta {
+.hljs-quote {
   color: #5c6773;
-  font-style: italic;
 }
 
 .hljs-variable,
@@ -30,6 +27,7 @@ Original by Dempfi (https://github.com/dempfi/ayu)
 }
 
 .hljs-number,
+.hljs-meta,
 .hljs-builtin-name,
 .hljs-literal,
 .hljs-type,

crates/mdbook-html/front-end/css/chrome.css

@@ -0,0 +1,751 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+html {
+    scrollbar-color: var(--scrollbar) var(--bg);
+}
+#mdbook-searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+    color: var(--links);
+}
+
+/*
+    mdbook-body-container is necessary because mobile browsers don't seem to like
+    overflow-x on the body tag when there is a <meta name="viewport"> tag.
+*/
+#mdbook-body-container {
+    /*
+        This is used when the sidebar pushes the body content off the side of
+        the screen on small screens. Without it, dragging on mobile Safari
+        will want to reposition the viewport in a weird way.
+    */
+    overflow-x: clip;
+}
+
+/* Menu Bar */
+
+#mdbook-menu-bar,
+#mdbook-menu-bar-hover-placeholder {
+    z-index: 101;
+    margin: auto calc(0px - var(--page-padding));
+}
+#mdbook-menu-bar {
+    position: relative;
+    display: flex;
+    flex-wrap: wrap;
+    background-color: var(--bg);
+    border-block-end-color: var(--bg);
+    border-block-end-width: 1px;
+    border-block-end-style: solid;
+}
+#mdbook-menu-bar.sticky,
+#mdbook-menu-bar-hover-placeholder:hover + #mdbook-menu-bar,
+#mdbook-menu-bar:hover,
+html.sidebar-visible #mdbook-menu-bar {
+    position: -webkit-sticky;
+    position: sticky;
+    top: 0 !important;
+}
+#mdbook-menu-bar-hover-placeholder {
+    position: sticky;
+    position: -webkit-sticky;
+    top: 0;
+    height: var(--menu-bar-height);
+}
+#mdbook-menu-bar.bordered {
+    border-block-end-color: var(--table-border-color);
+}
+#mdbook-menu-bar .fa-svg, #mdbook-menu-bar .icon-button {
+    position: relative;
+    padding: 0 8px;
+    z-index: 10;
+    line-height: var(--menu-bar-height);
+    cursor: pointer;
+    transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+    #mdbook-menu-bar .fa-svg, #mdbook-menu-bar .icon-button {
+        padding: 0 5px;
+    }
+}
+
+.icon-button {
+    border: none;
+    background: none;
+    padding: 0;
+    color: inherit;
+}
+.icon-button .fa-svg {
+    margin: 0;
+}
+
+.right-buttons {
+    margin: 0 15px;
+}
+.right-buttons a {
+    text-decoration: none;
+}
+
+.left-buttons {
+    display: flex;
+    margin: 0 5px;
+}
+html:not(.js) .left-buttons button {
+    display: none;
+}
+
+.menu-title {
+    display: inline-block;
+    font-weight: 200;
+    font-size: 2.4rem;
+    line-height: var(--menu-bar-height);
+    text-align: center;
+    margin: 0;
+    flex: 1;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.menu-title {
+    cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a .fa-svg {
+    color: var(--icons);
+}
+
+.menu-bar .fa-svg:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters .fa-svg:hover {
+    color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+    font-size: 2.5em;
+    text-align: center;
+    text-decoration: none;
+
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    margin: 0;
+    max-width: 150px;
+    min-width: 90px;
+
+    display: flex;
+    justify-content: center;
+    align-content: center;
+    flex-direction: column;
+
+    transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+    text-decoration: none;
+    background-color: var(--theme-hover);
+    transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+    margin-block-start: 50px;
+    display: none;
+}
+
+.mobile-nav-chapters {
+    font-size: 2.5em;
+    text-align: center;
+    text-decoration: none;
+    width: 90px;
+    border-radius: 5px;
+    background-color: var(--sidebar-bg);
+}
+
+/* Only Firefox supports flow-relative values */
+.previous { float: left; }
+[dir=rtl] .previous { float: right; }
+
+/* Only Firefox supports flow-relative values */
+.next {
+    float: right;
+    right: var(--page-padding);
+}
+[dir=rtl] .next {
+    float: left;
+    right: unset;
+    left: var(--page-padding);
+}
+
+@media only screen and (max-width: 1080px) {
+    .nav-wide-wrapper { display: none; }
+    .nav-wrapper { display: block; }
+}
+
+/* sidebar-visible */
+@media only screen and (max-width: 1380px) {
+    #mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; }
+    #mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+    display: inline;
+    padding: 0.1em 0.3em;
+    border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+    color: var(--inline-code-color);
+    overflow-x: initial;
+}
+
+a:hover > .hljs {
+    text-decoration: underline;
+}
+
+pre {
+    position: relative;
+}
+pre > .buttons {
+    position: absolute;
+    z-index: 100;
+    right: 0px;
+    top: 2px;
+    margin: 0px;
+    padding: 2px 0px;
+
+    color: var(--sidebar-fg);
+    cursor: pointer;
+    visibility: hidden;
+    opacity: 0;
+    transition: visibility 0.1s linear, opacity 0.1s linear;
+}
+pre:hover > .buttons {
+    visibility: visible;
+    opacity: 1
+}
+pre > .buttons :hover {
+    color: var(--sidebar-active);
+    border-color: var(--icons-hover);
+    background-color: var(--theme-hover);
+}
+pre > .buttons button {
+    cursor: inherit;
+    margin: 0px 5px;
+    padding: 2px 3px 0px 4px;
+    font-size: 23px;
+
+    border-style: solid;
+    border-width: 1px;
+    border-radius: 4px;
+    border-color: var(--icons);
+    background-color: var(--theme-popup-bg);
+    transition: 100ms;
+    transition-property: color,border-color,background-color;
+    color: var(--icons);
+}
+
+pre > .buttons button.clip-button {
+    padding: 2px 4px 0px 6px;
+}
+pre > .buttons button.clip-button::before {
+    /* clipboard image from octicons (https://github.com/primer/octicons/tree/v2.0.0) MIT license
+     */
+    content: url('data:image/svg+xml,<svg width="21" height="20" viewBox="0 0 24 25" \
+xmlns="http://www.w3.org/2000/svg" aria-label="Copy to clipboard">\
+<path d="M18 20h2v3c0 1-1 2-2 2H2c-.998 0-2-1-2-2V5c0-.911.755-1.667 1.667-1.667h5A3.323 3.323 0 \
+0110 0a3.323 3.323 0 013.333 3.333h5C19.245 3.333 20 4.09 20 5v8.333h-2V9H2v14h16v-3zM3 \
+7h14c0-.911-.793-1.667-1.75-1.667H13.5c-.957 0-1.75-.755-1.75-1.666C11.75 2.755 10.957 2 10 \
+2s-1.75.755-1.75 1.667c0 .911-.793 1.666-1.75 1.666H4.75C3.793 5.333 3 6.09 3 7z"/>\
+<path d="M4 19h6v2H4zM12 11H4v2h8zM4 17h4v-2H4zM15 15v-3l-4.5 4.5L15 21v-3l8.027-.032L23 15z"/>\
+</svg>');
+    filter: var(--copy-button-filter);
+}
+pre > .buttons button.clip-button:hover::before {
+    filter: var(--copy-button-filter-hover);
+}
+
+@media (pointer: coarse) {
+    pre > .buttons button {
+        /* On mobile, make it easier to tap buttons. */
+        padding: 0.3rem 1rem;
+    }
+
+    .sidebar-resize-indicator {
+        /* Hide resize indicator on devices with limited accuracy */
+        display: none;
+    }
+}
+pre > code {
+    display: block;
+    padding: 1rem;
+}
+
+/* FIXME: ACE editors overlap their buttons because ACE does absolute
+   positioning within the code block which breaks padding. The only solution I
+   can think of is to move the padding to the outer pre tag (or insert a div
+   wrapper), but that would require fixing a whole bunch of CSS rules.
+*/
+.hljs.ace_editor {
+  padding: 0rem 0rem;
+}
+
+pre > .result {
+    margin-block-start: 10px;
+}
+
+/* Search */
+
+#mdbook-searchresults a {
+    text-decoration: none;
+}
+
+mark {
+    border-radius: 2px;
+    padding-block-start: 0;
+    padding-block-end: 1px;
+    padding-inline-start: 3px;
+    padding-inline-end: 3px;
+    margin-block-start: 0;
+    margin-block-end: -1px;
+    margin-inline-start: -3px;
+    margin-inline-end: -3px;
+    background-color: var(--search-mark-bg);
+    transition: background-color 300ms linear;
+    cursor: pointer;
+}
+
+mark.fade-out {
+    background-color: rgba(0,0,0,0) !important;
+    cursor: auto;
+}
+
+.searchbar-outer {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+}
+
+#mdbook-searchbar-outer.searching #mdbook-searchbar {
+    padding-right: 30px;
+}
+#mdbook-searchbar-outer .spinner-wrapper {
+    display: none;
+}
+#mdbook-searchbar-outer.searching .spinner-wrapper {
+    display: block;
+}
+
+.search-wrapper {
+    position: relative;
+}
+
+.spinner-wrapper {
+    --spinner-margin: 2px;
+    position: absolute;
+    margin-block-start: calc(var(--searchbar-margin-block-start) + var(--spinner-margin));
+    right: var(--spinner-margin);
+    top: 0;
+    bottom: var(--spinner-margin);
+    padding: 6px;
+    background-color: var(--bg);
+}
+
+#fa-spin {
+    animation: rotating 2s linear infinite;
+    display: inline-block;
+}
+
+@keyframes rotating {
+    from {
+        transform: rotate(0deg);
+    }
+    to {
+        transform: rotate(360deg);
+    }
+}
+
+#mdbook-searchbar {
+    width: 100%;
+    margin-block-start: var(--searchbar-margin-block-start);
+    margin-block-end: 0;
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    padding: 10px 16px;
+    transition: box-shadow 300ms ease-in-out;
+    border: 1px solid var(--searchbar-border-color);
+    border-radius: 3px;
+    background-color: var(--searchbar-bg);
+    color: var(--searchbar-fg);
+}
+#mdbook-searchbar:focus,
+#mdbook-searchbar.active {
+    box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+    font-weight: bold;
+    font-size: 1em;
+    padding-block-start: 18px;
+    padding-block-end: 0;
+    padding-inline-start: 5px;
+    padding-inline-end: 0;
+    color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+    border-block-end: 1px dashed var(--searchresults-border-color);
+}
+
+ul#mdbook-searchresults {
+    list-style: none;
+    padding-inline-start: 20px;
+}
+ul#mdbook-searchresults li {
+    margin: 10px 0px;
+    padding: 2px;
+    border-radius: 2px;
+}
+ul#mdbook-searchresults li.focus {
+    background-color: var(--searchresults-li-bg);
+}
+ul#mdbook-searchresults span.teaser {
+    display: block;
+    clear: both;
+    margin-block-start: 5px;
+    margin-block-end: 0;
+    margin-inline-start: 20px;
+    margin-inline-end: 0;
+    font-size: 0.8em;
+}
+ul#mdbook-searchresults span.teaser em {
+    font-weight: bold;
+    font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+    position: fixed;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    width: var(--sidebar-width);
+    font-size: 0.875em;
+    box-sizing: border-box;
+    -webkit-overflow-scrolling: touch;
+    overscroll-behavior-y: contain;
+    background-color: var(--sidebar-bg);
+    color: var(--sidebar-fg);
+}
+.sidebar-iframe-inner {
+    --padding: 10px;
+
+    background-color: var(--sidebar-bg);
+    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;
+    height: 100%;
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    right: 0;
+}
+[dir=rtl] .sidebar { left: unset; right: 0; }
+.sidebar-resizing {
+    -moz-user-select: none;
+    -webkit-user-select: none;
+    -ms-user-select: none;
+    user-select: none;
+}
+html:not(.sidebar-resizing) .sidebar {
+    transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+    line-height: 2em;
+}
+.sidebar .sidebar-scrollbox {
+    overflow-y: auto;
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+    position: absolute;
+    cursor: col-resize;
+    width: 0;
+    right: calc(var(--sidebar-resize-indicator-width) * -1);
+    top: 0;
+    bottom: 0;
+    display: flex;
+    align-items: center;
+}
+
+.sidebar-resize-handle .sidebar-resize-indicator {
+    width: 100%;
+    height: 16px;
+    color: var(--icons);
+    margin-inline-start: var(--sidebar-resize-indicator-space);
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+}
+.sidebar-resize-handle .sidebar-resize-indicator::before {
+    content: "";
+    width: 2px;
+    height: 12px;
+    border-left: dotted 2px currentColor;
+}
+.sidebar-resize-handle .sidebar-resize-indicator::after {
+    content: "";
+    width: 2px;
+    height: 16px;
+    border-left: dotted 2px currentColor;
+}
+
+[dir=rtl] .sidebar .sidebar-resize-handle {
+    left: calc(var(--sidebar-resize-indicator-width) * -1);
+    right: unset;
+}
+.js .sidebar .sidebar-resize-handle {
+    cursor: col-resize;
+    width: calc(var(--sidebar-resize-indicator-width) - var(--sidebar-resize-indicator-space));
+}
+/* sidebar-hidden */
+#mdbook-sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+    transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
+}
+[dir=rtl] #mdbook-sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+    transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
+}
+.sidebar::-webkit-scrollbar {
+    background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+    background: var(--scrollbar);
+}
+
+/* sidebar-visible */
+#mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper {
+    transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
+}
+[dir=rtl] #mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper {
+    transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
+}
+@media only screen and (min-width: 620px) {
+    #mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper {
+        transform: none;
+        margin-inline-start: calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width));
+    }
+    [dir=rtl] #mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper {
+        transform: none;
+    }
+}
+
+.chapter {
+    list-style: none outside none;
+    padding-inline-start: 0;
+    line-height: 2.2em;
+}
+
+.chapter li {
+    color: var(--sidebar-non-existant);
+}
+
+/* This is a span wrapping the chapter link and the fold chevron. */
+.chapter-link-wrapper {
+    /* Used to position the chevron to the right, allowing the text to wrap before it. */
+    display: flex;
+}
+
+.chapter li a {
+    /* Remove underlines. */
+    text-decoration: none;
+    color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+    color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+    color: var(--sidebar-active);
+}
+
+/* This is the toggle chevron. */
+.chapter-fold-toggle {
+    cursor: pointer;
+    /* Positions the chevron to the side. */
+    margin-inline-start: auto;
+    padding: 0 10px;
+    user-select: none;
+    opacity: 0.68;
+}
+
+.chapter-fold-toggle div {
+    transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) > ol {
+    display: none;
+}
+
+.chapter li.chapter-item {
+    line-height: 1.5em;
+    margin-block-start: 0.6em;
+}
+
+/* When expanded, rotate the chevron to point down. */
+.chapter li.expanded > span > .chapter-fold-toggle div {
+    transform: rotate(90deg);
+}
+
+.chapter a.current-header {
+    color: var(--sidebar-active);
+}
+
+.on-this-page {
+    margin-left: 22px;
+    border-inline-start: 4px solid var(--sidebar-header-border-color);
+    padding-left: 8px;
+}
+
+.on-this-page > ol {
+    padding-left: 0;
+}
+
+/* Horizontal line in chapter list. */
+.spacer {
+    width: 100%;
+    height: 3px;
+    margin: 5px 0px;
+}
+.chapter .spacer {
+    background-color: var(--sidebar-spacer);
+}
+
+/* On touch devices, add more vertical spacing to make it easier to tap links. */
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+    .chapter li a { padding: 5px 0; }
+    .spacer { margin: 10px 0; }
+}
+
+.section {
+    list-style: none outside none;
+    padding-inline-start: 20px;
+    line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+    position: absolute;
+    left: 10px;
+    top: var(--menu-bar-height);
+    z-index: 1000;
+    border-radius: 4px;
+    font-size: 0.7em;
+    color: var(--fg);
+    background: var(--theme-popup-bg);
+    border: 1px solid var(--theme-popup-border);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    display: none;
+    /* Don't let the children's background extend past the rounded corners. */
+    overflow: hidden;
+}
+[dir=rtl] .theme-popup { left: unset;  right: 10px; }
+.theme-popup .default {
+    color: var(--icons);
+}
+.theme-popup .theme {
+    width: 100%;
+    border: 0;
+    margin: 0;
+    padding: 2px 20px;
+    line-height: 25px;
+    white-space: nowrap;
+    text-align: start;
+    cursor: pointer;
+    color: inherit;
+    background: inherit;
+    font-size: inherit;
+}
+.theme-popup .theme:hover {
+    background-color: var(--theme-hover);
+}
+
+.theme-selected::before {
+    display: inline-block;
+    content: "✓";
+    margin-inline-start: -14px;
+    width: 14px;
+}
+
+/* The container for the help popup that covers the whole window. */
+#mdbook-help-container {
+    /* Position and size for the whole window. */
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    /* This uses flex layout (which is set in book.js), and centers the popup
+       in the window.*/
+    display: none;
+    align-items: center;
+    justify-content: center;
+    z-index: 1000;
+    /* Dim out the book while the popup is visible. */
+    background: var(--overlay-bg);
+}
+
+/* The popup help box. */
+#mdbook-help-popup {
+    box-shadow: 0 4px 24px rgba(0,0,0,0.15);
+    min-width: 300px;
+    max-width: 500px;
+    width: 100%;
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    background-color: var(--bg);
+    color: var(--fg);
+    border-width: 1px;
+    border-color: var(--theme-popup-border);
+    border-style: solid;
+    border-radius: 8px;
+    padding: 10px;
+}
+
+.mdbook-help-title {
+    text-align: center;
+    /* mdbook's margin for h2 is way too large. */
+    margin: 10px;
+}

crates/mdbook-html/front-end/css/general.css

@@ -0,0 +1,408 @@
+/* Base styles and content styles */
+
+:root {
+    /* Browser default font-size is 16px, this way 1 rem = 10px */
+    font-size: 62.5%;
+    color-scheme: var(--color-scheme);
+}
+
+html {
+    font-family: "Open Sans", sans-serif;
+    color: var(--fg);
+    background-color: var(--bg);
+    text-size-adjust: none;
+    -webkit-text-size-adjust: none;
+}
+
+body {
+    margin: 0;
+    font-size: 1.6rem;
+    overflow-x: hidden;
+}
+
+code {
+    font-family: var(--mono-font) !important;
+    font-size: var(--code-font-size);
+    direction: ltr !important;
+}
+
+/* make long words/inline code not x overflow */
+main {
+    overflow-wrap: break-word;
+}
+
+/* make wide tables scroll if they overflow */
+.table-wrapper {
+    overflow-x: auto;
+}
+
+/* Don't change font size in headers. */
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+    font-size: unset;
+}
+
+.left { float: left; }
+.right { float: right; }
+.boring { opacity: 0.6; }
+.hide-boring .boring { display: none; }
+.hidden { display: none !important; }
+
+h2, h3 { margin-block-start: 2.5em; }
+h4, h5 { margin-block-start: 2em; }
+
+.header + .header h3,
+.header + .header h4,
+.header + .header h5 {
+    margin-block-start: 1em;
+}
+
+h1:target::before,
+h2:target::before,
+h3:target::before,
+h4:target::before,
+h5:target::before,
+h6:target::before,
+dt:target::before {
+    display: inline-block;
+    content: "»";
+    margin-inline-start: -30px;
+    width: 30px;
+}
+
+/* This is broken on Safari as of version 14, but is fixed
+   in Safari Technology Preview 117 which I think will be Safari 14.2.
+   https://bugs.webkit.org/show_bug.cgi?id=218076
+*/
+:target {
+    /* Safari does not support logical properties */
+    scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
+}
+
+.page {
+    outline: 0;
+    padding: 0 var(--page-padding);
+    margin-block-start: calc(0px - var(--menu-bar-height)); /* Compensate for the #mdbook-menu-bar-hover-placeholder */
+}
+.page-wrapper {
+    box-sizing: border-box;
+    background-color: var(--bg);
+}
+html:not(.js) .page-wrapper,
+.js:not(.sidebar-resizing) .page-wrapper {
+    transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+[dir=rtl]:not(.js) .page-wrapper,
+[dir=rtl].js:not(.sidebar-resizing) .page-wrapper {
+    transition: margin-right 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+
+.content {
+    overflow-y: auto;
+    padding: 0 5px 50px 5px;
+}
+.content main {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+}
+.content p { line-height: 1.45em; }
+.content ol { line-height: 1.45em; }
+.content ul { line-height: 1.45em; }
+.content a { text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content img, .content video { max-width: 100%; }
+.content .header:link,
+.content .header:visited {
+    color: var(--fg);
+}
+.content .header:link,
+.content .header:visited:hover {
+    text-decoration: none;
+}
+
+table {
+    margin: 0 auto;
+    border-collapse: collapse;
+}
+table td {
+    padding: 3px 20px;
+    border: 1px var(--table-border-color) solid;
+}
+table thead {
+    background: var(--table-header-bg);
+}
+table thead td {
+    font-weight: 700;
+    border: none;
+}
+table thead th {
+    padding: 3px 20px;
+}
+table thead tr {
+    border: 1px var(--table-header-bg) solid;
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+    background: var(--table-alternate-bg);
+}
+
+
+blockquote {
+    margin: 20px 0;
+    padding: 0 20px;
+    color: var(--fg);
+    background-color: var(--quote-bg);
+    border-block-start: .1em solid var(--quote-border);
+    border-block-end: .1em solid var(--quote-border);
+}
+
+/* TODO: Remove .warning in a future version of mdbook, it is replaced by
+blockquote tags. */
+.warning {
+    margin: 20px;
+    padding: 0 20px;
+    border-inline-start: 2px solid var(--warning-border);
+}
+
+.warning:before {
+    position: absolute;
+    width: 3rem;
+    height: 3rem;
+    margin-inline-start: calc(-1.5rem - 21px);
+    content: "ⓘ";
+    text-align: center;
+    background-color: var(--bg);
+    color: var(--warning-border);
+    font-weight: bold;
+    font-size: 2rem;
+}
+
+blockquote .warning:before {
+    background-color: var(--quote-bg);
+}
+
+kbd {
+    background-color: var(--table-border-color);
+    border-radius: 4px;
+    border: solid 1px var(--theme-popup-border);
+    box-shadow: inset 0 -1px 0 var(--theme-hover);
+    display: inline-block;
+    font-size: var(--code-font-size);
+    font-family: var(--mono-font);
+    line-height: 10px;
+    padding: 4px 5px;
+    vertical-align: middle;
+}
+
+sup {
+    /* Set the line-height for superscript and footnote references so that there
+       isn't an awkward space appearing above lines that contain the footnote.
+
+       See https://github.com/rust-lang/mdBook/pull/2443#discussion_r1813773583
+       for an explanation.
+    */
+    line-height: 0;
+}
+
+.footnote-definition {
+    font-size: 0.9em;
+}
+/* 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 {
+    position: absolute;
+    visibility: hidden;
+    color: #fff;
+    background-color: #333;
+    transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
+    left: -8px; /* Half of the width of the icon */
+    top: -35px;
+    font-size: 0.8em;
+    text-align: center;
+    border-radius: 6px;
+    padding: 5px 8px;
+    margin: 5px;
+    z-index: 1000;
+}
+.tooltipped .tooltiptext {
+    visibility: visible;
+}
+
+.chapter li.part-title {
+    color: var(--sidebar-fg);
+    margin: 5px 0px;
+    font-weight: bold;
+}
+
+.result-no-output {
+    font-style: italic;
+}
+
+.fa-svg svg {
+    width: 1em;
+    height: 1em;
+    fill: currentColor;
+    margin-bottom: -0.1em;
+}
+
+dt {
+    font-weight: bold;
+    margin-top: 0.5em;
+    margin-bottom: 0.1em;
+}
+
+/* This uses a CSS counter to add numbers to definitions, but only if there is
+ more than one definition. */
+dl, dt {
+    counter-reset: dd-counter;
+}
+
+/* When there is more than one definition, increment the counter. The first
+selector selects the first definition, and the second one selects definitions
+2 and beyond.*/
+dd:has(+ dd), dd + dd {
+    counter-increment: dd-counter;
+    /* Use flex display to help with positioning the numbers when there is a p
+    tag inside the definition. */
+    display: flex;
+    align-items: flex-start;
+}
+
+/* Shows the counter for definitions. The first selector selects the first
+definition, and the second one selections definitions 2 and beyond.*/
+dd:has(+ dd)::before, dd + dd::before  {
+    content: counter(dd-counter) ". ";
+    font-weight: 600;
+    display: inline-block;
+    margin-right: 0.5em;
+}
+
+dd > p {
+    /* For loose definitions that have a p tag inside, don't add a bunch of
+    space before the definition. */
+    margin-top: 0;
+}
+
+/* Remove some excess space from the bottom. */
+.blockquote-tag p:last-child {
+    margin-bottom: 2px;
+}
+
+.blockquote-tag {
+    /* Add some padding to make the vertical bar a little taller than the text.*/
+    padding: 2px 0px 2px 20px;
+    /* Add a solid color bar on the left side. */
+    border-inline-start-style: solid;
+    border-inline-start-width: 4px;
+    /* Disable the background color from normal blockquotes . */
+    background-color: inherit;
+    /* Disable border blocks from blockquotes. */
+    border-block-start: none;
+    border-block-end: none;
+}
+
+.blockquote-tag-title svg {
+    fill: currentColor;
+    /* Add space between the icon and the title. */
+    margin-right: 8px;
+}
+
+.blockquote-tag-note {
+    border-inline-start-color: var(--blockquote-note-color);
+}
+
+.blockquote-tag-tip {
+    border-inline-start-color: var(--blockquote-tip-color);
+}
+
+.blockquote-tag-important {
+    border-inline-start-color: var(--blockquote-important-color);
+}
+
+.blockquote-tag-warning {
+    border-inline-start-color: var(--blockquote-warning-color);
+}
+
+.blockquote-tag-caution {
+    border-inline-start-color: var(--blockquote-caution-color);
+}
+
+.blockquote-tag-note .blockquote-tag-title {
+    color: var(--blockquote-note-color);
+}
+
+.blockquote-tag-tip .blockquote-tag-title {
+    color: var(--blockquote-tip-color);
+}
+
+.blockquote-tag-important .blockquote-tag-title {
+    color: var(--blockquote-important-color);
+}
+
+.blockquote-tag-warning .blockquote-tag-title {
+    color: var(--blockquote-warning-color);
+}
+
+.blockquote-tag-caution .blockquote-tag-title {
+    color: var(--blockquote-caution-color);
+}
+
+.blockquote-tag-title {
+    /* Slightly increase the weight for more emphasis. */
+    font-weight: 600;
+    /* Vertically center the icon with the text. */
+    display: flex;
+    align-items: center;
+    /* Remove default large margins for a more compact display. */
+    margin: 2px 0 8px 0;
+}
+
+.blockquote-tag-title .fa-svg {
+    fill: currentColor;
+    /* Add some space between the icon and the text. */
+    margin-right: 8px;
+}

crates/mdbook-html/front-end/css/highlight.css

@@ -1,17 +1,22 @@
-/* Base16 Atelier Dune Light - Theme */
-/* by Bram de Haan (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune) */
-/* Original Base16 color scheme by Chris Kempson (https://github.com/chriskempson/base16) */
+/*
+ * An increased contrast highlighting scheme loosely based on the
+ * "Base16 Atelier Dune Light" theme by Bram de Haan
+ * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
+ * Original Base16 color scheme by Chris Kempson
+ * (https://github.com/chriskempson/base16)
+ */
 
-/* Atelier-Dune Comment */
+/* Comment */
 .hljs-comment,
 .hljs-quote {
-  color: #AAA;
+  color: #575757;
 }
 
-/* Atelier-Dune Red */
+/* Red */
 .hljs-variable,
 .hljs-template-variable,
 .hljs-attribute,
+.hljs-attr,
 .hljs-tag,
 .hljs-name,
 .hljs-regexp,
@@ -19,10 +24,10 @@
 .hljs-name,
 .hljs-selector-id,
 .hljs-selector-class {
-  color: #d73737;
+  color: #d70025;
 }
 
-/* Atelier-Dune Orange */
+/* Orange */
 .hljs-number,
 .hljs-meta,
 .hljs-built_in,
@@ -30,34 +35,33 @@
 .hljs-literal,
 .hljs-type,
 .hljs-params {
-  color: #b65611;
+  color: #b21e00;
 }
 
-/* Atelier-Dune Green */
+/* Green */
 .hljs-string,
 .hljs-symbol,
 .hljs-bullet {
-  color: #60ac39;
+  color: #008200;
 }
 
-/* Atelier-Dune Blue */
+/* Blue */
 .hljs-title,
 .hljs-section {
-  color: #6684e1;
+  color: #0030f2;
 }
 
-/* Atelier-Dune Purple */
+/* Purple */
 .hljs-keyword,
 .hljs-selector-tag {
-  color: #b854d4;
+  color: #9d00ec;
 }
 
 .hljs {
   display: block;
   overflow-x: auto;
-  background: #f1f1f1;
-  color: #6e6b5e;
-  padding: 0.5em;
+  background: #f6f7f6;
+  color: #000;
 }
 
 .hljs-emphasis {

crates/mdbook-html/front-end/css/print.css

@@ -1,18 +1,18 @@
 
-#sidebar,
-#menu-bar,
+#mdbook-sidebar,
+#mdbook-menu-bar,
 .nav-chapters,
 .mobile-nav-chapters {
     display: none;
 }
 
-#page-wrapper.page-wrapper {
-    transform: none;
-    margin-left: 0px;
+#mdbook-page-wrapper.page-wrapper {
+    transform: none !important;
+    margin-inline-start: 0px;
     overflow-y: initial;
 }
 
-#content {
+#mdbook-content {
     max-width: none;
     margin: 0;
     padding: 0;
@@ -23,11 +23,7 @@
 }
 
 code {
-    background-color: #666666;
-    border-radius: 5px;
-
-    /* Force background to be printed in Chrome */
-    -webkit-print-color-adjust: exact;
+    direction: ltr !important;
 }
 
 pre > .buttons {

crates/mdbook-html/front-end/css/tomorrow-night.css

@@ -1,7 +1,7 @@
 /* Tomorrow Night Theme */
-/* http://jmblog.github.com/color-themes-for-google-code-highlightjs */
+/* https://github.com/jmblog/color-themes-for-highlightjs */
 /* Original theme - https://github.com/chriskempson/tomorrow-theme */
-/* http://jmblog.github.com/color-themes-for-google-code-highlightjs */
+/* https://github.com/jmblog/color-themes-for-highlightjs */
 
 /* Tomorrow Comment */
 .hljs-comment {
@@ -11,6 +11,7 @@
 /* Tomorrow Red */
 .hljs-variable,
 .hljs-attribute,
+.hljs-attr,
 .hljs-tag,
 .hljs-regexp,
 .ruby .hljs-constant,
@@ -54,6 +55,7 @@
 
 /* Tomorrow Aqua */
 .hljs-title,
+.hljs-section,
 .css .hljs-hexcolor {
   color: #8abeb7;
 }
@@ -81,8 +83,6 @@
   overflow-x: auto;
   background: #1d1f21;
   color: #c5c8c6;
-  padding: 0.5em;
-  -webkit-text-size-adjust: none;
 }
 
 .coffeescript .javascript,

crates/mdbook-html/front-end/css/variables.css

@@ -0,0 +1,383 @@
+
+/* Globals */
+
+:root {
+    --sidebar-target-width: 300px;
+    --sidebar-width: min(var(--sidebar-target-width), 80vw);
+    --sidebar-resize-indicator-width: 8px;
+    --sidebar-resize-indicator-space: 2px;
+    --page-padding: 15px;
+    --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 */
+    --searchbar-margin-block-start: 5px;
+}
+
+/* Themes */
+
+.ayu {
+    --bg: hsl(210, 25%, 8%);
+    --fg: #c5c5c5;
+
+    --sidebar-bg: #14191f;
+    --sidebar-fg: #c8c9db;
+    --sidebar-non-existant: #5c6773;
+    --sidebar-active: #ffb454;
+    --sidebar-spacer: #2d334f;
+
+    --scrollbar: var(--sidebar-fg);
+
+    --icons: #737480;
+    --icons-hover: #b7b9cc;
+
+    --links: #0096cf;
+
+    --inline-code-color: #ffb454;
+
+    --theme-popup-bg: #14191f;
+    --theme-popup-border: #5c6773;
+    --theme-hover: #191f26;
+
+    --quote-bg: hsl(226, 15%, 17%);
+    --quote-border: hsl(226, 15%, 22%);
+
+    --warning-border: #ff8e00;
+
+    --table-border-color: hsl(210, 25%, 13%);
+    --table-header-bg: hsl(210, 25%, 28%);
+    --table-alternate-bg: hsl(210, 25%, 11%);
+
+    --searchbar-border-color: #848484;
+    --searchbar-bg: #424242;
+    --searchbar-fg: #fff;
+    --searchbar-shadow-color: #d4c89f;
+    --searchresults-header-fg: #666;
+    --searchresults-border-color: #888;
+    --searchresults-li-bg: #252932;
+    --search-mark-bg: #e3b171;
+
+    --color-scheme: dark;
+
+    /* Same as `--icons` */
+    --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;
+
+    --overlay-bg: rgba(33, 40, 48, 0.4);
+
+    --blockquote-note-color: #74b9ff;
+    --blockquote-tip-color: #09ca09;
+    --blockquote-important-color: #d3abff;
+    --blockquote-warning-color: #f0b72f;
+    --blockquote-caution-color: #f21424;
+
+    --sidebar-header-border-color: #c18639;
+}
+
+.coal {
+    --bg: hsl(200, 7%, 8%);
+    --fg: #98a3ad;
+
+    --sidebar-bg: #292c2f;
+    --sidebar-fg: #a1adb8;
+    --sidebar-non-existant: #505254;
+    --sidebar-active: #3473ad;
+    --sidebar-spacer: #393939;
+
+    --scrollbar: var(--sidebar-fg);
+
+    --icons: #43484d;
+    --icons-hover: #b3c0cc;
+
+    --links: #2b79a2;
+
+    --inline-code-color: #c5c8c6;
+
+    --theme-popup-bg: #141617;
+    --theme-popup-border: #43484d;
+    --theme-hover: #1f2124;
+
+    --quote-bg: hsl(234, 21%, 18%);
+    --quote-border: hsl(234, 21%, 23%);
+
+    --warning-border: #ff8e00;
+
+    --table-border-color: hsl(200, 7%, 13%);
+    --table-header-bg: hsl(200, 7%, 28%);
+    --table-alternate-bg: hsl(200, 7%, 11%);
+
+    --searchbar-border-color: #aaa;
+    --searchbar-bg: #b7b7b7;
+    --searchbar-fg: #000;
+    --searchbar-shadow-color: #aaa;
+    --searchresults-header-fg: #666;
+    --searchresults-border-color: #98a3ad;
+    --searchresults-li-bg: #2b2b2f;
+    --search-mark-bg: #355c7d;
+
+    --color-scheme: dark;
+
+    /* Same as `--icons` */
+    --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;
+
+    --overlay-bg: rgba(33, 40, 48, 0.4);
+
+    --blockquote-note-color: #4493f8;
+    --blockquote-tip-color: #08ae08;
+    --blockquote-important-color: #ab7df8;
+    --blockquote-warning-color: #d29922;
+    --blockquote-caution-color: #d91b29;
+
+    --sidebar-header-border-color: #3473ad;
+}
+
+.light, html:not(.js) {
+    --bg: hsl(0, 0%, 100%);
+    --fg: hsl(0, 0%, 0%);
+
+    --sidebar-bg: #fafafa;
+    --sidebar-fg: hsl(0, 0%, 0%);
+    --sidebar-non-existant: #aaaaaa;
+    --sidebar-active: #1f1fff;
+    --sidebar-spacer: #f4f4f4;
+
+    --scrollbar: #8F8F8F;
+
+    --icons: #747474;
+    --icons-hover: #000000;
+
+    --links: #20609f;
+
+    --inline-code-color: #301900;
+
+    --theme-popup-bg: #fafafa;
+    --theme-popup-border: #cccccc;
+    --theme-hover: #e6e6e6;
+
+    --quote-bg: hsl(197, 37%, 96%);
+    --quote-border: hsl(197, 37%, 91%);
+
+    --warning-border: #ff8e00;
+
+    --table-border-color: hsl(0, 0%, 95%);
+    --table-header-bg: hsl(0, 0%, 80%);
+    --table-alternate-bg: hsl(0, 0%, 97%);
+
+    --searchbar-border-color: #aaa;
+    --searchbar-bg: #fafafa;
+    --searchbar-fg: #000;
+    --searchbar-shadow-color: #aaa;
+    --searchresults-header-fg: #666;
+    --searchresults-border-color: #888;
+    --searchresults-li-bg: #e4f2fe;
+    --search-mark-bg: #a2cff5;
+
+    --color-scheme: light;
+
+    /* Same as `--icons` */
+    --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;
+
+    --overlay-bg: rgba(200, 200, 205, 0.4);
+
+    --blockquote-note-color: #0969da;
+    --blockquote-tip-color: #008000;
+    --blockquote-important-color: #8250df;
+    --blockquote-warning-color: #9a6700;
+    --blockquote-caution-color: #b52731;
+
+    --sidebar-header-border-color: #6e6edb;
+}
+
+.navy {
+    --bg: hsl(226, 23%, 11%);
+    --fg: #bcbdd0;
+
+    --sidebar-bg: #282d3f;
+    --sidebar-fg: #c8c9db;
+    --sidebar-non-existant: #505274;
+    --sidebar-active: #2b79a2;
+    --sidebar-spacer: #2d334f;
+
+    --scrollbar: var(--sidebar-fg);
+
+    --icons: #737480;
+    --icons-hover: #b7b9cc;
+
+    --links: #2b79a2;
+
+    --inline-code-color: #c5c8c6;
+
+    --theme-popup-bg: #161923;
+    --theme-popup-border: #737480;
+    --theme-hover: #282e40;
+
+    --quote-bg: hsl(226, 15%, 17%);
+    --quote-border: hsl(226, 15%, 22%);
+
+    --warning-border: #ff8e00;
+
+    --table-border-color: hsl(226, 23%, 16%);
+    --table-header-bg: hsl(226, 23%, 31%);
+    --table-alternate-bg: hsl(226, 23%, 14%);
+
+    --searchbar-border-color: #aaa;
+    --searchbar-bg: #aeaec6;
+    --searchbar-fg: #000;
+    --searchbar-shadow-color: #aaa;
+    --searchresults-header-fg: #5f5f71;
+    --searchresults-border-color: #5c5c68;
+    --searchresults-li-bg: #242430;
+    --search-mark-bg: #a2cff5;
+
+    --color-scheme: dark;
+
+    /* Same as `--icons` */
+    --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;
+
+    --overlay-bg: rgba(33, 40, 48, 0.4);
+
+    --blockquote-note-color: #4493f8;
+    --blockquote-tip-color: #09ca09;
+    --blockquote-important-color: #ab7df8;
+    --blockquote-warning-color: #d29922;
+    --blockquote-caution-color: #f21424;
+
+    --sidebar-header-border-color: #2f6ab5;
+}
+
+.rust {
+    --bg: hsl(60, 9%, 87%);
+    --fg: #262625;
+
+    --sidebar-bg: #3b2e2a;
+    --sidebar-fg: #c8c9db;
+    --sidebar-non-existant: #505254;
+    --sidebar-active: #e69f67;
+    --sidebar-spacer: #45373a;
+
+    --scrollbar: var(--sidebar-fg);
+
+    --icons: #737480;
+    --icons-hover: #262625;
+
+    --links: #2b79a2;
+
+    --inline-code-color: #6e6b5e;
+
+    --theme-popup-bg: #e1e1db;
+    --theme-popup-border: #b38f6b;
+    --theme-hover: #99908a;
+
+    --quote-bg: hsl(60, 5%, 75%);
+    --quote-border: hsl(60, 5%, 70%);
+
+    --warning-border: #ff8e00;
+
+    --table-border-color: hsl(60, 9%, 82%);
+    --table-header-bg: #b3a497;
+    --table-alternate-bg: hsl(60, 9%, 84%);
+
+    --searchbar-border-color: #aaa;
+    --searchbar-bg: #fafafa;
+    --searchbar-fg: #000;
+    --searchbar-shadow-color: #aaa;
+    --searchresults-header-fg: #666;
+    --searchresults-border-color: #888;
+    --searchresults-li-bg: #dec2a2;
+    --search-mark-bg: #e69f67;
+
+    /* Same as `--icons` */
+    --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;
+
+    --overlay-bg: rgba(150, 150, 150, 0.25);
+
+    --blockquote-note-color: #023b95;
+    --blockquote-tip-color: #007700;
+    --blockquote-important-color: #8250df;
+    --blockquote-warning-color: #603700;
+    --blockquote-caution-color: #aa1721;
+
+    --sidebar-header-border-color: #8c391f;
+}
+
+@media (prefers-color-scheme: dark) {
+    html:not(.js) {
+        --bg: hsl(200, 7%, 8%);
+        --fg: #98a3ad;
+
+        --sidebar-bg: #292c2f;
+        --sidebar-fg: #a1adb8;
+        --sidebar-non-existant: #505254;
+        --sidebar-active: #3473ad;
+        --sidebar-spacer: #393939;
+
+        --scrollbar: var(--sidebar-fg);
+
+        --icons: #43484d;
+        --icons-hover: #b3c0cc;
+
+        --links: #2b79a2;
+
+        --inline-code-color: #c5c8c6;
+
+        --theme-popup-bg: #141617;
+        --theme-popup-border: #43484d;
+        --theme-hover: #1f2124;
+
+        --quote-bg: hsl(234, 21%, 18%);
+        --quote-border: hsl(234, 21%, 23%);
+
+        --warning-border: #ff8e00;
+
+        --table-border-color: hsl(200, 7%, 13%);
+        --table-header-bg: hsl(200, 7%, 28%);
+        --table-alternate-bg: hsl(200, 7%, 11%);
+
+        --searchbar-border-color: #aaa;
+        --searchbar-bg: #b7b7b7;
+        --searchbar-fg: #000;
+        --searchbar-shadow-color: #aaa;
+        --searchresults-header-fg: #666;
+        --searchresults-border-color: #98a3ad;
+        --searchresults-li-bg: #2b2b2f;
+        --search-mark-bg: #355c7d;
+
+        --color-scheme: dark;
+
+        /* Same as `--icons` */
+        --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;
+
+        --overlay-bg: rgba(33, 40, 48, 0.4);
+
+        --blockquote-note-color: #4493f8;
+        --blockquote-tip-color: #08ae08;
+        --blockquote-important-color: #ab7df8;
+        --blockquote-warning-color: #d29922;
+        --blockquote-caution-color: #d91b29;
+
+        --sidebar-header-border-color: #3473ad;
+    }
+}

crates/mdbook-html/front-end/fonts/OPEN-SANS-LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

crates/mdbook-html/front-end/fonts/SOURCE-CODE-PRO-LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

crates/mdbook-html/front-end/fonts/fonts.css

@@ -0,0 +1,100 @@
+/* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */
+/* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */
+
+/* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: normal;
+  font-weight: 300;
+  src: local('Open Sans Light'), local('OpenSans-Light'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: italic;
+  font-weight: 300;
+  src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: normal;
+  font-weight: 400;
+  src: local('Open Sans Regular'), local('OpenSans-Regular'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: italic;
+  font-weight: 400;
+  src: local('Open Sans Italic'), local('OpenSans-Italic'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: normal;
+  font-weight: 600;
+  src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: italic;
+  font-weight: 600;
+  src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: normal;
+  font-weight: 700;
+  src: local('Open Sans Bold'), local('OpenSans-Bold'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: italic;
+  font-weight: 700;
+  src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: normal;
+  font-weight: 800;
+  src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'),
+       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 */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: italic;
+  font-weight: 800;
+  src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'),
+       url('{{ resource "fonts/open-sans-v17-all-charsets-800italic.woff2" }}') format('woff2');
+}
+
+/* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+  font-family: 'Source Code Pro';
+  font-style: normal;
+  font-weight: 500;
+  src: url('{{ resource "fonts/source-code-pro-v11-all-charsets-500.woff2" }}') format('woff2');
+}

crates/mdbook-html/front-end/images/favicon.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 199.7 184.2">
+  <style>
+    @media (prefers-color-scheme: dark) {
+      svg { fill: white; }
+    }
+  </style>
+<path d="M189.5,36.8c0.2,2.8,0,5.1-0.6,6.8L153,162c-0.6,2.1-2,3.7-4.2,5c-2.2,1.2-4.4,1.9-6.7,1.9H31.4c-9.6,0-15.3-2.8-17.3-8.4
+  c-0.8-2.2-0.8-3.9,0.1-5.2c0.9-1.2,2.4-1.8,4.6-1.8H123c7.4,0,12.6-1.4,15.4-4.1s5.7-8.9,8.6-18.4l32.9-108.6
+  c1.8-5.9,1-11.1-2.2-15.6S169.9,0,164,0H72.7c-1,0-3.1,0.4-6.1,1.1l0.1-0.4C64.5,0.2,62.6,0,61,0.1s-3,0.5-4.3,1.4
+  c-1.3,0.9-2.4,1.8-3.2,2.8S52,6.5,51.2,8.1c-0.8,1.6-1.4,3-1.9,4.3s-1.1,2.7-1.8,4.2c-0.7,1.5-1.3,2.7-2,3.7c-0.5,0.6-1.2,1.5-2,2.5
+  s-1.6,2-2.2,2.8s-0.9,1.5-1.1,2.2c-0.2,0.7-0.1,1.8,0.2,3.2c0.3,1.4,0.4,2.4,0.4,3.1c-0.3,3-1.4,6.9-3.3,11.6
+  c-1.9,4.7-3.6,8.1-5.1,10.1c-0.3,0.4-1.2,1.3-2.6,2.7c-1.4,1.4-2.3,2.6-2.6,3.7c-0.3,0.4-0.3,1.5-0.1,3.4c0.3,1.8,0.4,3.1,0.3,3.8
+  c-0.3,2.7-1.3,6.3-3,10.8c-1.7,4.5-3.4,8.2-5,11c-0.2,0.5-0.9,1.4-2,2.8c-1.1,1.4-1.8,2.5-2,3.4c-0.2,0.6-0.1,1.8,0.1,3.4
+  c0.2,1.6,0.2,2.8-0.1,3.6c-0.6,3-1.8,6.7-3.6,11c-1.8,4.3-3.6,7.9-5.4,11c-0.5,0.8-1.1,1.7-2,2.8c-0.8,1.1-1.5,2-2,2.8
+  s-0.8,1.6-1,2.5c-0.1,0.5,0,1.3,0.4,2.3c0.3,1.1,0.4,1.9,0.4,2.6c-0.1,1.1-0.2,2.6-0.5,4.4c-0.2,1.8-0.4,2.9-0.4,3.2
+  c-1.8,4.8-1.7,9.9,0.2,15.2c2.2,6.2,6.2,11.5,11.9,15.8c5.7,4.3,11.7,6.4,17.8,6.4h110.7c5.2,0,10.1-1.7,14.7-5.2s7.7-7.8,9.2-12.9
+  l33-108.6c1.8-5.8,1-10.9-2.2-15.5C194.9,39.7,192.6,38,189.5,36.8z M59.6,122.8L73.8,80c0,0,7,0,10.8,0s28.8-1.7,25.4,17.5
+  c-3.4,19.2-18.8,25.2-36.8,25.4S59.6,122.8,59.6,122.8z M78.6,116.8c4.7-0.1,18.9-2.9,22.1-17.1S89.2,86.3,89.2,86.3l-8.9,0
+  l-10.2,30.5C70.2,116.9,74,116.9,78.6,116.8z M75.3,68.7L89,26.2h9.8l0.8,34l23.6-34h9.9l-13.6,42.5h-7.1l12.5-35.4l-24.5,35.4h-6.8
+  l-0.8-35L82,68.7H75.3z"/>
+</svg>
+<!-- Original image Copyright Dave Gandy — CC BY 4.0 License -->

crates/mdbook-html/front-end/js/book.js

@@ -0,0 +1,843 @@
+'use strict';
+
+/* global default_theme, default_dark_theme, default_light_theme, hljs, ClipboardJS */
+
+// Fix back button cache problem
+window.onunload = function() { };
+
+// Global variable, shared between modules
+function playground_text(playground, hidden = true) {
+    const code_block = playground.querySelector('code');
+
+    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;
+    } else {
+        return code_block.innerText;
+    }
+}
+
+(function codeSnippets() {
+    function fetch_with_timeout(url, options, timeout = 6000) {
+        return Promise.race([
+            fetch(url, options),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout)),
+        ]);
+    }
+
+    const playgrounds = Array.from(document.querySelectorAll('.playground'));
+    if (playgrounds.length > 0) {
+        fetch_with_timeout('https://play.rust-lang.org/meta/crates', {
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            method: 'POST',
+            mode: 'cors',
+        })
+            .then(response => response.json())
+            .then(response => {
+            // get list of crates available in the rust playground
+                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) {
+        // update the play buttons after receiving the response
+        update_play_button(playground_block, playground_crates);
+
+        // and install on change listener to dynamically update ACE editors
+        if (window.ace) {
+            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',
+                    bindKey: {
+                        win: 'Ctrl-Enter',
+                        mac: 'Ctrl-Enter',
+                    },
+                    exec: _editor => run_rust_code(playground_block),
+                });
+            }
+        }
+    }
+
+    // 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) {
+        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');
+            return;
+        }
+
+        // get list of `extern crate`'s from snippet
+        const txt = playground_text(pre_block);
+        const re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
+        const snippet_crates = [];
+        let item;
+        while (item = re.exec(txt)) {
+            snippet_crates.push(item[1]);
+        }
+
+        // check if all used crates are available on play.rust-lang.org
+        const all_available = snippet_crates.every(function(elem) {
+            return playground_crates.indexOf(elem) > -1;
+        });
+
+        if (all_available) {
+            play_button.classList.remove('hidden');
+            play_button.hidden = false;
+        } else {
+            play_button.classList.add('hidden');
+        }
+    }
+
+    function run_rust_code(code_block) {
+        let result_block = code_block.querySelector('.result');
+        if (!result_block) {
+            result_block = document.createElement('code');
+            result_block.className = 'result hljs language-bash';
+
+            code_block.append(result_block);
+        }
+
+        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,
+        };
+
+        if (text.indexOf('#![feature') !== -1) {
+            params.version = 'nightly';
+        }
+
+        result_block.innerText = 'Running...';
+
+        fetch_with_timeout('https://play.rust-lang.org/evaluate.json', {
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            method: 'POST',
+            mode: 'cors',
+            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);
+    }
+
+    // Syntax highlighting Configuration
+    hljs.configure({
+        tabReplace: '    ', // 4 spaces
+        languages: [], // Languages used for auto-detection
+    });
+
+    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');
+        });
+
+    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');
+            });
+
+        code_nodes
+            .filter(function(node) {
+                return !node.classList.contains('editable');
+            })
+            .forEach(function(block) {
+                hljs.highlightBlock(block);
+            });
+    } else {
+        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');
+    });
+
+    Array.from(document.querySelectorAll('code.hljs')).forEach(function(block) {
+
+        const lines = Array.from(block.querySelectorAll('.boring'));
+        // If no lines were hidden, return
+        if (!lines.length) {
+            return;
+        }
+        block.classList.add('hide-boring');
+
+        const buttons = document.createElement('div');
+        buttons.className = 'buttons';
+        buttons.innerHTML = '<button title="Show hidden lines" \
+aria-label="Show hidden lines"></button>';
+        buttons.firstChild.innerHTML = document.getElementById('fa-eye').innerHTML;
+
+        // add expand button
+        const pre_block = block.parentNode;
+        pre_block.insertBefore(buttons, pre_block.firstChild);
+
+        buttons.firstChild.addEventListener('click', function(e) {
+            if (this.title === 'Show hidden lines') {
+                this.innerHTML = document.getElementById('fa-eye-slash').innerHTML;
+                this.title = 'Hide lines';
+                this.setAttribute('aria-label', e.target.title);
+
+                block.classList.remove('hide-boring');
+            } else if (this.title === 'Hide lines') {
+                this.innerHTML = document.getElementById('fa-eye').innerHTML;
+                this.title = 'Show hidden lines';
+                this.setAttribute('aria-label', e.target.title);
+
+                block.classList.add('hide-boring');
+            }
+        });
+    });
+
+    if (window.playground_copyable) {
+        Array.from(document.querySelectorAll('pre code')).forEach(function(block) {
+            const pre_block = block.parentNode;
+            if (!pre_block.classList.contains('playground')) {
+                let buttons = pre_block.querySelector('.buttons');
+                if (!buttons) {
+                    buttons = document.createElement('div');
+                    buttons.className = 'buttons';
+                    pre_block.insertBefore(buttons, pre_block.firstChild);
+                }
+
+                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>';
+
+                buttons.insertBefore(clipButton, buttons.firstChild);
+            }
+        });
+    }
+
+    // Process playground code blocks
+    Array.from(document.querySelectorAll('.playground')).forEach(function(pre_block) {
+        // Add play button
+        let buttons = pre_block.querySelector('.buttons');
+        if (!buttons) {
+            buttons = document.createElement('div');
+            buttons.className = 'buttons';
+            pre_block.insertBefore(buttons, pre_block.firstChild);
+        }
+
+        const runCodeButton = document.createElement('button');
+        runCodeButton.className = 'play-button';
+        runCodeButton.hidden = true;
+        runCodeButton.title = 'Run this code';
+        runCodeButton.setAttribute('aria-label', runCodeButton.title);
+        runCodeButton.innerHTML = document.getElementById('fa-play').innerHTML;
+
+        buttons.insertBefore(runCodeButton, buttons.firstChild);
+        runCodeButton.addEventListener('click', () => {
+            run_rust_code(pre_block);
+        });
+
+        if (window.playground_copyable) {
+            const copyCodeClipboardButton = document.createElement('button');
+            copyCodeClipboardButton.className = 'clip-button';
+            copyCodeClipboardButton.innerHTML = '<i class="tooltiptext"></i>';
+            copyCodeClipboardButton.title = 'Copy to clipboard';
+            copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
+
+            buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
+        }
+
+        const code_block = pre_block.querySelector('code');
+        if (window.ace && code_block.classList.contains('editable')) {
+            const undoChangesButton = document.createElement('button');
+            undoChangesButton.className = 'reset-button';
+            undoChangesButton.title = 'Undo changes';
+            undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
+            undoChangesButton.innerHTML +=
+                document.getElementById('fa-clock-rotate-left').innerHTML;
+
+            buttons.insertBefore(undoChangesButton, buttons.firstChild);
+
+            undoChangesButton.addEventListener('click', function() {
+                const editor = window.ace.edit(code_block);
+                editor.setValue(editor.originalCode);
+                editor.clearSelection();
+            });
+        }
+    });
+})();
+
+(function themes() {
+    const html = document.querySelector('html');
+    const themeToggleButton = document.getElementById('mdbook-theme-toggle');
+    const themePopup = document.getElementById('mdbook-theme-list');
+    const themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
+    const themeIds = [];
+    themePopup.querySelectorAll('button.theme').forEach(function(el) {
+        themeIds.push(el.id);
+    });
+    const stylesheets = {
+        ayuHighlight: document.querySelector('#mdbook-ayu-highlight-css'),
+        tomorrowNight: document.querySelector('#mdbook-tomorrow-night-css'),
+        highlight: document.querySelector('#mdbook-highlight-css'),
+    };
+
+    function showThemes() {
+        themePopup.style.display = 'block';
+        themeToggleButton.setAttribute('aria-expanded', true);
+        themePopup.querySelector('button#mdbook-theme-' + get_theme()).focus();
+    }
+
+    function updateThemeSelected() {
+        themePopup.querySelectorAll('.theme-selected').forEach(function(el) {
+            el.classList.remove('theme-selected');
+        });
+        const selected = get_saved_theme() ?? 'default_theme';
+        let element = themePopup.querySelector('button#mdbook-theme-' + selected);
+        if (element === null) {
+            // Fall back in case there is no "Default" item.
+            element = themePopup.querySelector('button#mdbook-theme-' + get_theme());
+        }
+        element.classList.add('theme-selected');
+    }
+
+    function hideThemes() {
+        themePopup.style.display = 'none';
+        themeToggleButton.setAttribute('aria-expanded', false);
+        themeToggleButton.focus();
+    }
+
+    function get_saved_theme() {
+        let theme = null;
+        try {
+            theme = localStorage.getItem('mdbook-theme');
+        } catch {
+            // ignore error.
+        }
+        return theme;
+    }
+
+    function delete_saved_theme() {
+        localStorage.removeItem('mdbook-theme');
+    }
+
+    function get_theme() {
+        const theme = get_saved_theme();
+        if (theme === null || theme === undefined || !themeIds.includes('mdbook-theme-' + 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') {
+            stylesheets.ayuHighlight.disabled = true;
+            stylesheets.tomorrowNight.disabled = false;
+            stylesheets.highlight.disabled = true;
+
+            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';
+        } else {
+            stylesheets.ayuHighlight.disabled = true;
+            stylesheets.tomorrowNight.disabled = true;
+            stylesheets.highlight.disabled = false;
+            ace_theme = 'ace/theme/dawn';
+        }
+
+        setTimeout(function() {
+            themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor;
+        }, 1);
+
+        if (window.ace && window.editors) {
+            window.editors.forEach(function(editor) {
+                editor.setTheme(ace_theme);
+            });
+        }
+
+        if (store) {
+            try {
+                localStorage.setItem('mdbook-theme', theme);
+            } catch {
+                // ignore error.
+            }
+        }
+
+        html.classList.remove(previousTheme);
+        html.classList.add(theme);
+        previousTheme = theme;
+        updateThemeSelected();
+    }
+
+    const query = window.matchMedia('(prefers-color-scheme: dark)');
+    query.onchange = function() {
+        set_theme(get_theme(), false);
+    };
+
+    // Set theme.
+    set_theme(get_theme(), false);
+
+    themeToggleButton.addEventListener('click', function() {
+        if (themePopup.style.display === 'block') {
+            hideThemes();
+        } else {
+            showThemes();
+        }
+    });
+
+    themePopup.addEventListener('click', function(e) {
+        let theme;
+        if (e.target.className === 'theme') {
+            theme = e.target.id;
+        } else if (e.target.parentElement.className === 'theme') {
+            theme = e.target.parentElement.id;
+        } else {
+            return;
+        }
+        theme = theme.replace(/^mdbook-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)
+        ) {
+            hideThemes();
+        }
+    });
+
+    // 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)
+        ) {
+            hideThemes();
+        }
+    });
+
+    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();
+            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() {
+    const sidebar = document.getElementById('mdbook-sidebar');
+    const sidebarLinks = document.querySelectorAll('#mdbook-sidebar a');
+    const sidebarToggleButton = document.getElementById('mdbook-sidebar-toggle');
+    const sidebarResizeHandle = document.getElementById('mdbook-sidebar-resize-handle');
+    const sidebarCheckbox = document.getElementById('mdbook-sidebar-toggle-anchor');
+    let firstContact = null;
+
+
+    /* Because we cannot change the `display` using only CSS after/before the transition, we
+       need JS to do it. We change the display to prevent the browsers search to find text inside
+       the collapsed sidebar. */
+    if (!document.documentElement.classList.contains('sidebar-visible')) {
+        sidebar.style.display = 'none';
+    }
+    sidebar.addEventListener('transitionend', () => {
+        /* We only change the display to "none" if we're collapsing the sidebar. */
+        if (!sidebarCheckbox.checked) {
+            sidebar.style.display = 'none';
+        }
+    });
+    sidebarToggleButton.addEventListener('click', () => {
+        /* To allow the sidebar expansion animation, we first need to put back the display. */
+        if (!sidebarCheckbox.checked) {
+            sidebar.style.display = '';
+            // Workaround for Safari skipping the animation when changing
+            // `display` and a transform in the same event loop. This forces a
+            // reflow after updating the display.
+            sidebar.offsetHeight;
+        }
+    });
+
+    function showSidebar() {
+        document.documentElement.classList.add('sidebar-visible');
+        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 {
+            // Ignore error.
+        }
+    }
+
+    function hideSidebar() {
+        document.documentElement.classList.remove('sidebar-visible');
+        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 {
+            // Ignore error.
+        }
+    }
+
+    // Toggle sidebar
+    sidebarCheckbox.addEventListener('change', function sidebarToggle() {
+        if (sidebarCheckbox.checked) {
+            const current_width = parseInt(
+                document.documentElement.style.getPropertyValue('--sidebar-target-width'), 10);
+            if (current_width < 150) {
+                document.documentElement.style.setProperty('--sidebar-target-width', '150px');
+            }
+            showSidebar();
+        } else {
+            hideSidebar();
+        }
+    });
+
+    sidebarResizeHandle.addEventListener('mousedown', initResize, false);
+
+    function initResize() {
+        window.addEventListener('mousemove', resize, false);
+        window.addEventListener('mouseup', stopResize, false);
+        document.documentElement.classList.add('sidebar-resizing');
+    }
+    function resize(e) {
+        let pos = e.clientX - sidebar.offsetLeft;
+        if (pos < 20) {
+            hideSidebar();
+        } else {
+            if (!document.documentElement.classList.contains('sidebar-visible')) {
+                showSidebar();
+            }
+            pos = Math.min(pos, window.innerWidth - 100);
+            document.documentElement.style.setProperty('--sidebar-target-width', pos + 'px');
+        }
+    }
+    //on mouseup remove windows functions mousemove & mouseup
+    function stopResize() {
+        document.documentElement.classList.remove('sidebar-resizing');
+        window.removeEventListener('mousemove', resize, false);
+        window.removeEventListener('mouseup', stopResize, false);
+    }
+
+    document.addEventListener('touchstart', function(e) {
+        firstContact = {
+            x: e.touches[0].clientX,
+            time: Date.now(),
+        };
+    }, { passive: true });
+
+    document.addEventListener('touchmove', function(e) {
+        if (!firstContact) {
+            return;
+        }
+
+        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)) {
+                showSidebar();
+            } else if (xDiff < 0 && curX < 300) {
+                hideSidebar();
+            }
+
+            firstContact = null;
+        }
+    }, { passive: true });
+})();
+
+(function chapterNavigation() {
+    document.addEventListener('keydown', function(e) {
+        if (e.altKey || e.ctrlKey || e.metaKey) {
+            return;
+        }
+        if (window.search && window.search.hasFocus()) {
+            return;
+        }
+        const html = document.querySelector('html');
+
+        function next() {
+            const nextButton = document.querySelector('.nav-chapters.next');
+            if (nextButton) {
+                window.location.href = nextButton.href;
+            }
+        }
+        function prev() {
+            const previousButton = document.querySelector('.nav-chapters.previous');
+            if (previousButton) {
+                window.location.href = previousButton.href;
+            }
+        }
+        function showHelp() {
+            const container = document.getElementById('mdbook-help-container');
+            const overlay = document.getElementById('mdbook-help-popup');
+            container.style.display = 'flex';
+
+            // Clicking outside the popup will dismiss it.
+            const mouseHandler = event => {
+                if (overlay.contains(event.target)) {
+                    return;
+                }
+                if (event.button !== 0) {
+                    return;
+                }
+                event.preventDefault();
+                event.stopPropagation();
+                document.removeEventListener('mousedown', mouseHandler);
+                hideHelp();
+            };
+
+            // Pressing esc will dismiss the popup.
+            const escapeKeyHandler = event => {
+                if (event.key === 'Escape') {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    document.removeEventListener('keydown', escapeKeyHandler, true);
+                    hideHelp();
+                }
+            };
+            document.addEventListener('keydown', escapeKeyHandler, true);
+            document.getElementById('mdbook-help-container')
+                .addEventListener('mousedown', mouseHandler);
+        }
+        function hideHelp() {
+            document.getElementById('mdbook-help-container').style.display = 'none';
+        }
+
+        // Usually needs the Shift key to be pressed
+        switch (e.key) {
+        case '?':
+            e.preventDefault();
+            showHelp();
+            break;
+        }
+
+        // Rest of the keys are only active when the Shift key is not pressed
+        if (e.shiftKey) {
+            return;
+        }
+
+        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;
+        }
+    });
+})();
+
+(function clipboard() {
+    const clipButtons = document.querySelectorAll('.clip-button');
+
+    function hideTooltip(elem) {
+        elem.firstChild.innerText = '';
+        elem.className = 'clip-button';
+    }
+
+    function showTooltip(elem, msg) {
+        elem.firstChild.innerText = msg;
+        elem.className = 'clip-button tooltipped';
+    }
+
+    const clipboardSnippets = new ClipboardJS('.clip-button', {
+        text: function(trigger) {
+            hideTooltip(trigger);
+            const playground = trigger.closest('pre');
+            return playground_text(playground, false);
+        },
+    });
+
+    Array.from(clipButtons).forEach(function(clipButton) {
+        clipButton.addEventListener('mouseout', function(e) {
+            hideTooltip(e.currentTarget);
+        });
+    });
+
+    clipboardSnippets.on('success', function(e) {
+        e.clearSelection();
+        showTooltip(e.trigger, 'Copied!');
+    });
+
+    clipboardSnippets.on('error', function(e) {
+        showTooltip(e.trigger, 'Clipboard error!');
+    });
+})();
+
+(function scrollToTop() {
+    const menuTitle = document.querySelector('.menu-title');
+
+    menuTitle.addEventListener('click', function() {
+        document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
+    });
+})();
+
+(function controllMenu() {
+    const menu = document.getElementById('mdbook-menu-bar');
+
+    (function controllPosition() {
+        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 refresh it).
+        menu.style.top = scrollTop + 'px';
+        // Same as parseInt(menu.style.top.slice(0, -2), but faster
+        let topCache = menu.style.top.slice(0, -2);
+        menu.classList.remove('sticky');
+        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
+            let nextSticky = null;
+            let nextTop = null;
+            const scrollDown = scrollTop > prevScrollTop;
+            const menuPosAbsoluteY = topCache - scrollTop;
+            if (scrollDown) {
+                nextSticky = false;
+                if (menuPosAbsoluteY > 0) {
+                    nextTop = prevScrollTop;
+                }
+            } else {
+                if (menuPosAbsoluteY > 0) {
+                    nextSticky = true;
+                } else if (menuPosAbsoluteY < minMenuY) {
+                    nextTop = prevScrollTop + minMenuY;
+                }
+            }
+            if (nextSticky === true && stickyCache === false) {
+                menu.classList.add('sticky');
+                stickyCache = true;
+            } else if (nextSticky === false && stickyCache === true) {
+                menu.classList.remove('sticky');
+                stickyCache = false;
+            }
+            if (nextTop !== null) {
+                menu.style.top = nextTop + 'px';
+                topCache = nextTop;
+            }
+            prevScrollTop = scrollTop;
+        }, { passive: true });
+    })();
+    (function controllBorder() {
+        function updateBorder() {
+            if (menu.offsetTop === 0) {
+                menu.classList.remove('bordered');
+            } else {
+                menu.classList.add('bordered');
+            }
+        }
+        updateBorder();
+        document.addEventListener('scroll', updateBorder, { passive: true });
+    })();
+})();

crates/mdbook-html/front-end/playground_editor/editor.js

@@ -6,7 +6,7 @@ window.editors = [];
     }
 
     Array.from(document.querySelectorAll('.editable')).forEach(function(editable) {
-        let display_line_numbers = window.playpen_line_numbers || false;
+        let display_line_numbers = window.playground_line_numbers || false;
 
         let editor = ace.edit(editable);
             editor.setOptions({