Updated the documentation for new preprocessor format (#787)

* Updated the documentation for new preprocessor format

* adjusted the descriptions for preprocessors

.cargo/config.toml

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

.git-blame-ignore-revs

@@ -1,26 +0,0 @@
-# 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

@@ -2,9 +2,7 @@
 
 * text=auto eol=lf
 *.rs rust
-*.woff binary
-*.ttf binary
-*.otf binary
-*.png binary
-*.eot binary
-*.woff2 binary
+*.woff -text
+*.ttf -text
+*.otf -text
+*.png -text

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,45 +0,0 @@
-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

@@ -1,28 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,71 +0,0 @@
-{
-    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

@@ -1,68 +0,0 @@
-name: Deploy
-on:
-  release:
-    types: [created]
-
-defaults:
-  run:
-    shell: bash
-
-permissions:
-  contents: write
-
-jobs:
-  release:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        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@v5
-    - name: Install Rust
-      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
-    steps:
-    - uses: actions/checkout@v5
-    - name: Install Rust (rustup)
-      run: rustup update stable --no-self-update && rustup default stable
-    - 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
-    environment: publish
-    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,147 +0,0 @@
-name: CI
-on:
-  pull_request:
-  merge_group:
-
-jobs:
-  test:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        include:
-          - name: stable linux
-            os: ubuntu-latest
-            rust: stable
-            target: x86_64-unknown-linux-gnu
-          - name: beta linux
-            os: ubuntu-latest
-            rust: beta
-            target: x86_64-unknown-linux-gnu
-          - name: nightly linux
-            os: ubuntu-latest
-            rust: nightly
-            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
-            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
-            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@v5
-    - name: Install Rust
-      run: bash ci/install-rust.sh ${{ matrix.rust }} ${{ matrix.target }}
-    - name: Build and run tests
-      run: cargo test --workspace --locked --target ${{ matrix.target }}
-    - name: Test no default
-      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@v5
-    - name: Install Rust
-      run: rustup update stable && rustup default stable && rustup component add rustfmt
-    - run: cargo fmt --check
-
-  gui:
-    name: GUI tests
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - name: Install Rust
-        run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu
-      - name: Install npm
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24
-      - 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.45.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

@@ -1,21 +0,0 @@
-name: Update dependencies
-on:
-  schedule:
-    - cron: '0 0 1 * *'
-  workflow_dispatch:
-
-jobs:
-  update:
-    name: Update dependencies
-    runs-on: ubuntu-latest
-    if: github.repository == 'rust-lang/mdBook'
-    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,21 +4,8 @@ target
 .DS_Store
 
 book-test
-guide/book
+book-example/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

.travis.yml

@@ -0,0 +1,48 @@
+language: rust
+
+rust:
+  - stable
+  - beta
+  - nightly
+
+os:
+  - linux
+  - osx
+
+cache: 
+  timeout: 360
+  cargo: true
+
+before_cache:
+  - chmod -R a+r $HOME/.cargo
+
+env:
+  global:
+    - CRATE_NAME=mdbook
+
+script:
+  - cargo test --all
+  - cargo test --all --no-default-features
+
+before_deploy:
+  - sh ci/before_deploy.sh
+
+deploy:
+  provider: releases
+  api_key:
+    - secure: cURRWBr034iqBz/ifD7uOunBfNR30YxIXfgLX0osWz+iafkVbhDGYYz9sBmRraqO2P7L2koEXMADVb/md1kI2+ykiq/ml+l9zuEAZPVmvSGUN7ZD+7s+lu3l5OBPG5z175T+b2q2q2m8XVR7TW20ra4QbE0bq06KAoOyjSgQVBTSCYsL9uTsGwiVRMEqqJT/BmKhKJNkpGsTKyBSKkOXvfeAAbE260vXUDEN9TYdJ3fvteRrpwLX56ee64gIZUq0RjDc4SKIEqilM6iUtNMvurqaewYNGkiXKRruV6BPCHxEHo6NNT46kOJLBJTf7gZw//dWhSoWpg9P0gdAnPWm407kSa3F7aJ1eRShAFQ4BLyfz9efTqm+jP3fOp7Mm7igSh9w6caSRuOnSsUf5+raRQ8E5Y9HsWGzzpZQk24Fx9EGZ04EeDSdpZAFz+jcbMpHf8t2p4CEx0CCNwYvKx6EydMKbMF5QteQ8SQkXNLhv7Rz2OgtXWYZPRVCMfQfOplsi2InsLCrQxTgwh+6u654SqVSgaHG+IncEAxBrdWy4rHcg7qereUcKfcY3k96vaDxdn/T2c00Ig0aNFR91YnixGMd6J6tQgDcRK9jh6fUm1CCBE9hT+pNUmtgYKuWBoLZexUZFFnfuBed0WciBot1bGDDamndqKq0jJiAzg+GMHk=
+  file_glob: true
+  file: "$CRATE_NAME-$TRAVIS_TAG-$TARGET.*"
+  on:
+    condition: "$TRAVIS_RUST_VERSION = stable"
+    tags: true
+  skip_cleanup: true
+
+branches:
+  only:
+    - master
+    - /^v\d+\.\d+\.\d+.*$/
+
+notifications:
+  email:
+    on_success: never

CODE_OF_CONDUCT.md

@@ -1,3 +0,0 @@
-# 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,43 +5,35 @@ 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/mdBook/issues), no question is too simple.
+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:
 
-## Issue assignment
+### Issues to work on
 
-**: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).
+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).
 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/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).
+[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).
 
-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`.
+When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you.
 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 regarding the management of the mdBook project itself
+- **M**-prefixed labels are meta-issues used for questions, discussions, or tracking issues
 - **S**-prefixed labels show the status of the issue
-- **C**-prefixed labels show the category of issue
+- **T**-prefixed labels show the type 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:
 
@@ -49,192 +41,20 @@ 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/mdBook.git
+   git clone https://github.com/rust-lang-nursery/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
-
-We love code quality and Rust has some excellent tools to assist you with contributions.
-
-### 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/rustfmt) has a lot more information on the project.
-The quick guide is
-
-1. Install it (`rustfmt` is usually installed by default via [rustup](https://rustup.rs/)):
-    ```
-    rustup component add rustfmt
-    ```
-1. You can now run `rustfmt` on a single file simply by...
-    ```
-    rustfmt src/path/to/your/file.rs
-    ```
-   ... or you can format the entire project with
-   ```
-   cargo fmt
-   ```
-   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/rustfmt)
-
-### Finding issues with 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
-    ```
-    rustup component add clippy
-    ```
-2. Running clippy
-    ```
-    cargo clippy
-    ```
-
-## Change requirements
-
-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
+### 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 && git branch --set-upstream-to=origin/bump-version`
-    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,157 +1,66 @@
-[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.7"
-clap = { version = "4.5.53", features = ["cargo", "wrap_help"] }
-clap_complete = "4.5.61"
-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.36.0"
-indexmap = "2.12.1"
-ignore = "0.4.25"
-mdbook-core = { path = "crates/mdbook-core", version = "0.5.2" }
-mdbook-driver = { path = "crates/mdbook-driver", version = "0.5.2" }
-mdbook-html = { path = "crates/mdbook-html", version = "0.5.2" }
-mdbook-markdown = { path = "crates/mdbook-markdown", version = "0.5.2" }
-mdbook-preprocessor = { path = "crates/mdbook-preprocessor", version = "0.5.2" }
-mdbook-renderer = { path = "crates/mdbook-renderer", version = "0.5.2" }
-mdbook-summary = { path = "crates/mdbook-summary", version = "0.5.2" }
-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.23"
-tempfile = "3.23.0"
-tokio = "1.48.0"
-toml = "0.9.8"
-topological-sort = "0.2.2"
-tower-http = "0.6.7"
-tracing = "0.1.43"
-tracing-subscriber = { version = "0.3.22", features = ["env-filter"] }
-walkdir = "2.5.0"
-
 [package]
 name = "mdbook"
-version = "0.5.2"
+version = "0.2.2-alpha.0"
 authors = [
-    "Mathieu David <mathieudavid@mathieudavid.org>",
+    "Mathieu David <mathieudavid@mathieudavid.org>", 
     "Michael-F-Bryan <michaelfbryan@gmail.com>",
     "Matt Ickstadt <mattico8@gmail.com>"
 ]
-documentation = "https://rust-lang.github.io/mdBook/index.html"
-edition.workspace = true
-exclude = ["/guide/*"]
+description = "Create books from markdown files"
+documentation = "http://rust-lang-nursery.github.io/mdBook/index.html"
+repository = "https://github.com/rust-lang-nursery/mdBook"
 keywords = ["book", "gitbook", "rustbook", "markdown"]
-license.workspace = true
+license = "MPL-2.0"
 readme = "README.md"
-repository.workspace = true
-description = "Creates a book from markdown files"
-rust-version.workspace = true
+exclude = ["book-example/*"]
 
 [dependencies]
-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
+clap = "2.24"
+chrono = "0.4"
+handlebars = "1.0"
+serde = "1.0"
+serde_derive = "1.0"
+error-chain = "0.12"
+serde_json = "1.0"
+pulldown-cmark = "0.1.2"
+lazy_static = "1.0"
+log = "0.4"
+env_logger = "0.5"
+toml = "0.4"
+memchr = "2.0"
+open = "1.1"
+regex = "1.0.0"
+tempfile = "3.0"
+itertools = "0.7"
+shlex = "0.1"
+toml-query = "0.7"
 
 # Watch feature
-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 }
+notify = { version = "4.0", optional = true }
 
 # Serve feature
-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 }
+iron = { version = "0.6", optional = true }
+staticfile = { version = "0.5", optional = true }
+ws = { version = "0.7", optional = true}
+
+# Search feature
+elasticlunr-rs = { version = "2.3", optional = true, default-features = false }
+ammonia = { version = "1.1", optional = true }
 
 [dev-dependencies]
-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
+select = "0.4"
+pretty_assertions = "0.5"
+walkdir = "2.0"
+pulldown-cmark-to-cmark = "1.1.0"
 
 [features]
-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"]
+default = ["output", "watch", "serve", "search"]
+debug = []
+output = []
+watch = ["notify"]
+serve = ["iron", "staticfile", "ws"]
+search = ["elasticlunr-rs", "ammonia"]
 
 [[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,20 +1,191 @@
 # mdBook
 
-[![CI Status](https://github.com/rust-lang/mdBook/actions/workflows/main.yml/badge.svg)](https://github.com/rust-lang/mdBook/actions/workflows/main.yml)
-[![crates.io](https://img.shields.io/crates/v/mdbook.svg)](https://crates.io/crates/mdbook)
-[![LICENSE](https://img.shields.io/github/license/rust-lang/mdBook.svg)](LICENSE)
+<table>
+    <tr>
+        <td><strong>Linux / OS X</strong></td>
+        <td>
+            <a href="https://travis-ci.org/rust-lang-nursery/mdBook"><img src="https://travis-ci.org/rust-lang-nursery/mdBook.svg?branch=master"></a>
+        </td>
+    </tr>
+    <tr>
+        <td><strong>Windows</strong></td>
+        <td>
+            <a href="https://ci.appveyor.com/project/rust-lang-libs/mdbook"><img src="https://ci.appveyor.com/api/projects/status/ysyke2rvo85sni55?svg=true"></a>
+        </td>
+    </tr>
+    <tr>
+        <td colspan="2">
+            <a href="https://crates.io/crates/mdbook"><img src="https://img.shields.io/crates/v/mdbook.svg"></a>
+            <a href="LICENSE"><img src="https://img.shields.io/github/license/rust-lang-nursery/mdBook.svg"></a>
+        </td>
+    </tr>
+</table>
 
 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.
 
-If you are interested in contributing to the development of mdBook, check out the [Contribution Guide].
+## 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.20 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 latests **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.
+
+
+### 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`.
+
 
 ## 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.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
+
+[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/mdbook/

appveyor.yml

@@ -0,0 +1,64 @@
+environment:
+  global:
+    PROJECT_NAME: mdBook
+  matrix:
+    # Stable channel
+    - TARGET: i686-pc-windows-msvc
+      RUST_CHANNEL: stable
+    - TARGET: x86_64-pc-windows-msvc
+      RUST_CHANNEL: stable
+    # Beta channel
+    - TARGET: i686-pc-windows-msvc
+      RUST_CHANNEL: beta
+    - TARGET: x86_64-pc-windows-msvc
+      RUST_CHANNEL: beta
+    # Nightly channel
+    - TARGET: i686-pc-windows-msvc
+      RUST_CHANNEL: nightly
+    - TARGET: x86_64-pc-windows-msvc
+      RUST_CHANNEL: nightly
+
+# Install Rust and Cargo
+install:
+  - ps: >-
+      If ($Env:TARGET -eq 'x86_64-pc-windows-gnu') {
+        $Env:PATH += ';C:\msys64\mingw64\bin'
+      } ElseIf ($Env:TARGET -eq 'i686-pc-windows-gnu') {
+        $Env:PATH += ';C:\msys64\mingw32\bin'
+      }
+  - curl -sSf -o rustup-init.exe https://win.rustup.rs/
+  - rustup-init.exe -y --default-host %TARGET% --default-toolchain %RUST_CHANNEL%
+  - set PATH=%PATH%;C:\Users\appveyor\.cargo\bin
+  - rustc -Vv
+  - cargo -V
+
+build: false
+
+# Equivalent to Travis' `script` phase
+test_script:
+  - cargo test --all
+  - cargo test --all --no-default-features
+
+before_deploy:
+  # Generate artifacts for release
+  - cargo rustc --bin mdbook --release -- -C lto
+  - mkdir staging
+  - copy target\release\mdbook.exe staging
+  - cd staging
+  - 7z a ../%PROJECT_NAME%-%APPVEYOR_REPO_TAG_NAME%-%TARGET%.zip *
+  - appveyor PushArtifact ../%PROJECT_NAME%-%APPVEYOR_REPO_TAG_NAME%-%TARGET%.zip
+
+deploy:
+  description: 'Windows release'
+  artifact: /.*\.zip/
+  auth_token:
+    secure: QQhjKVyz7mpjlyGhlXytbFQQfKFQWTahHkD+B0NzIUoEVqO7ZLWjnoWasvLqW4nE
+  provider: GitHub
+  on:
+    RUST_CHANNEL: stable
+    appveyor_repo_tag: true
+
+branches:
+  only:
+    - master
+    - /^v\d+\.\d+\.\d+.*$/

book-example/book.toml

@@ -0,0 +1,19 @@
+[book]
+title = "mdBook Documentation"
+description = "Create book from markdown files. Like Gitbook but implemented in Rust"
+authors = ["Mathieu David", "Michael-F-Bryan"]
+
+[output.html]
+mathjax-support = true
+
+[output.html.playpen]
+editable = 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

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,27 @@
+# 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)
+    - [Alternate Backends](for_developers/backends.md)
+
+-----------
+
+[Contributors](misc/contributors.md)

book-example/src/cli/README.md

@@ -0,0 +1,55 @@
+# 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/downloads.html) 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/build.md

@@ -7,8 +7,7 @@ mdbook build
 ```
 
 It will try to parse your `SUMMARY.md` file to understand the structure of your
-book and fetch the corresponding files. Note that this will also create files
-mentioned in `SUMMARY.md` which are not yet present.
+book and fetch the corresponding files.
 
 The rendered output will maintain the same directory structure as the source for
 convenience. Large books will therefore remain structured when rendered.
@@ -22,19 +21,18 @@ root instead of the current working directory.
 mdbook build path/to/book
 ```
 
-#### `--open`
+#### --open
 
 When you use the `--open` (`-o`) flag, mdbook will open the rendered book in
 your default web browser after building it.
 
-#### `--dest-dir`
+#### --dest-dir
 
 The `--dest-dir` (`-d`) option allows you to change the output directory for the
-book. Relative paths are interpreted relative to the current directory. If
-not specified it will default to the value of the `build.build-dir` key in
-`book.toml`, or to `./book`.
+book. If not specified it will default to the value of the `build.build-dir` key
+in `book.toml`, or to `./book` relative to the book's root directory.
 
 -------------------
 
-***Note:*** *The build command copies all files (excluding files with `.md` extension) from the source directory
-into the build directory.*
+***Note:*** *Make sure to run the build command in the root directory and not in
+the source directory*

book-example/src/cli/clean.md

@@ -16,15 +16,15 @@ root instead of the current working directory.
 mdbook clean path/to/book
 ```
 
-#### `--dest-dir`
+#### --dest-dir
 
 The `--dest-dir` (`-d`) option allows you to override the book's output
-directory, which will be deleted by this command. Relative paths are interpreted
-relative to the current directory. If not specified it will default to the
-value of the `build.build-dir` key in `book.toml`, or to `./book`.
+directory, which will be deleted by this command. If not specified it will
+default to the value of the `build.build-dir` key in `book.toml`, or to `./book`
+relative to the book's root directory.
 
 ```bash
 mdbook clean --dest-dir=path/to/book
 ```
 
-`path/to/book` could be absolute or relative.
+`path/to/book` could be absolute or relative.

book-example/src/cli/init.md

@@ -19,15 +19,15 @@ book-test/
     └── SUMMARY.md
 ```
 
-- The `src` directory is where you write your book in markdown. It contains all
+- The `src` directory is were you write your book in markdown. It contains all
   the source files, configuration files, etc.
 
 - The `book` directory is where your book is rendered. All the output is ready
   to be uploaded to a server to be seen by your audience.
 
-- The `SUMMARY.md` is the skeleton of your
-  book, and is discussed in more detail [in another
-  chapter](../format/summary.md).
+- The `SUMMARY.md` file is the most important file, it's the skeleton of your
+  book and is discussed in more detail [in another
+  chapter](../format/summary.md)
 
 #### Tip: Generate chapters from SUMMARY.md
 
@@ -45,38 +45,10 @@ instead of the current working directory.
 mdbook init path/to/book
 ```
 
-#### `--theme`
+#### --theme
 
 When you use the `--theme` flag, the default theme will be copied into a
 directory called `theme` in your source directory so that you can modify it.
 
 The theme is selectively overwritten, this means that if you don't want to
 overwrite a specific file, just delete it and the default file will be used.
-
-#### `--title`
-
-Specify a title for the book. If not supplied, an interactive prompt will ask for 
-a title. 
-
-```bash
-mdbook init --title="my amazing book"
-```
-
-#### `--ignore`
-
-Create a `.gitignore` file configured to ignore the `book` directory created when [building] a book. 
-If not supplied, an interactive prompt will ask whether it should be created.
-
-```bash
-mdbook init --ignore=none
-```
-
-```bash
-mdbook init --ignore=git
-```
-
-[building]: build.md
-
-#### `--force`
-
-Skip the prompts to create a `.gitignore` and for the title for the book.

book-example/src/cli/serve.md

@@ -0,0 +1,49 @@
+# 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.
+
+#### 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 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. If not specified it will default to the value of the `build.build-dir` key
+in `book.toml`, or to `./book` relative to the book's root directory.
+
+-----
+
+***Note:*** *The `serve` command is for testing, and is not intended to be a
+complete HTTP server for a website.*

book-example/src/cli/test.md

@@ -6,7 +6,8 @@ of code examples that could get outdated. Therefore it is very important for
 them to be able to automatically test these code examples.
 
 mdBook supports a `test` command that will run all available tests in a book. At
-the moment, only Rust tests are supported.
+the moment, only rustdoc tests are supported, but this may be expanded upon in
+the future.
 
 #### Disable tests on a code block
 
@@ -37,24 +38,15 @@ instead of the current working directory.
 mdbook test path/to/book
 ```
 
-#### `--library-path`
+#### --library-path
 
 The `--library-path` (`-L`) option allows you to add directories to the library
 search path used by `rustdoc` when it builds and tests the examples. Multiple
 directories can be specified with multiple options (`-L foo -L bar`) or with a
-comma-delimited list (`-L foo,bar`). The path should point to the Cargo
-[build cache](https://doc.rust-lang.org/cargo/guide/build-cache.html) `deps` directory that
-contains the build output of your project. For example, if your Rust project's book is in a directory
-named `my-book`, the following command would include the crate's dependencies when running `test`:
+comma-delimited list (`-L foo,bar`).
 
-```shell
-mdbook test my-book -L target/debug/deps/
-```
+#### --dest-dir
 
-See the `rustdoc` command-line [documentation](https://doc.rust-lang.org/rustdoc/command-line-arguments.html#-l--library-path-where-to-look-for-dependencies)
-for more information.
-
-#### `--chapter`
-
-The `--chapter` (`-c`) option allows you to test a specific chapter of the
-book using the chapter name or the relative path to the chapter.
+The `--dest-dir` (`-d`) option allows you to change the output directory for the
+book. If not specified it will default to the value of the `build.build-dir` key
+in `book.toml`, or to `./book` relative to the book's root directory.

book-example/src/cli/watch.md

@@ -0,0 +1,26 @@
+# 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. If not specified it will default to the value of the `build.build-dir` key
+in `book.toml`, or to `./book` relative to the book's root directory.

book-example/src/continuous-integration.md

@@ -0,0 +1,56 @@
+# 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.1" mdbook)
+  - cargo install-update -a
+
+script:
+  - cd path/to/mybook && mdbook build && mdbook test
+```
+
+## 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!

book-example/src/for_developers/README.md

@@ -1,7 +1,7 @@
-# For developers
+# For Developers
 
 While `mdbook` is mainly used as a command line tool, you can also import the
-underlying libraries directly and use those to manage a book. It also has a fairly
+underlying library directly and use that to manage a book. It also has a fairly
 flexible plugin mechanism, allowing you to create your own custom tooling and
 consumers (often referred to as *backends*) if you need to do some analysis of
 the book or render it in a different format.
@@ -12,33 +12,35 @@ The *For Developers* chapters are here to show you the more advanced usage of
 The two main ways a developer can hook into the book's build process is via,
 
 - [Preprocessors](preprocessors.md)
-- [Alternative Backends](backends.md)
+- [Alternate Backends](backends.md)
 
-## The build process
+
+## The Build Process
 
 The process of rendering a book project goes through several steps.
 
-1. Load the book
+1. Load the book 
     - Parse the `book.toml`, falling back to the default `Config` if it doesn't
        exist
     - Load the book chapters into memory
     - Discover which preprocessors/backends should be used
-2. For each backend:
-   1. Run all the preprocessors.
-   2. Call the backend to render the processed result.
+2. Run the preprocessors
+3. Call each backend in turn
 
-## Using `mdbook` as a library
 
-The `mdbook` binary is just a wrapper around the underlying mdBook crates,
-exposing their functionality as a command-line program. If you want to
-programmatically drive mdBook, you can use the [`mdbook-driver`] crate.
-This can be used to add your own functionality or tweak the build process.
+## Using `mdbook` as a Library
 
-The easiest way to find out how to use the `mdbook-driver` crate is by looking at the
+The `mdbook` binary is just a wrapper around the `mdbook` crate, exposing its
+functionality as a command-line program. As such it is quite easy to create your
+own programs which use `mdbook` internally, adding your own functionality (e.g.
+a custom preprocessor) or tweaking the build process.
+
+The easiest way to find out how to use the `mdbook` crate is by looking at the
 [API Docs]. The top level documentation explains how one would use the
 [`MDBook`] type to load and build a book, while the [config] module gives a good
 explanation on the configuration system.
 
-[`MDBook`]: https://docs.rs/mdbook-driver/latest/mdbook_driver/struct.MDBook.html
-[API Docs]: https://docs.rs/mdbook-driver/latest/mdbook_driver/
-[config]: https://docs.rs/mdbook-driver/latest/mdbook_driver/config/index.html
+
+[`MDBook`]: http://rust-lang-nursery.github.io/mdBook/mdbook/book/struct.MDBook.html
+[API Docs]: http://rust-lang-nursery.github.io/mdBook/mdbook/
+[config]: file:///home/michael/Documents/forks/mdBook/target/doc/mdbook/config/index.html

book-example/src/for_developers/backends.md

@@ -1,28 +1,33 @@
-# Alternative backends
+# Alternate Backends
 
 A "backend" is simply a program which `mdbook` will invoke during the book
 rendering process. This program is passed a JSON representation of the book and
 configuration information via `stdin`. Once the backend receives this
 information it is free to do whatever it wants.
 
-See [Configuring Renderers](../format/configuration/renderers.md) for more information about using backends.
+There are already several alternate backends on GitHub which can be used as a
+rough example of how this is accomplished in practice.
 
-The community has developed several backends.
-See the [Third Party Plugins] wiki page for a list of available backends.
+- [mdbook-linkcheck] - a simple program for verifying the book doesn't contain
+  any broken links
+- [mdbook-epub] - an EPUB renderer
+- [mdbook-test] - a program to run the book's contents through [rust-skeptic] to
+  verify everything compiles and runs correctly (similar to `rustdoc --test`)
 
-## Setting up
-
-This page will step you through creating your own alternative backend in the form
+This page will step you through creating your own alternate backend in the form
 of a simple word counting program. Although it will be written in Rust, there's
 no reason why it couldn't be accomplished using something like Python or Ruby.
 
-First you'll want to create a new binary program and add `mdbook-renderer` as a
+
+## Setting Up
+
+First you'll want to create a new binary program and add `mdbook` as a
 dependency.
 
-```shell
+```
 $ cargo new --bin mdbook-wordcount
-$ cd mdbook-wordcount
-$ cargo add mdbook-renderer
+$ cd mdbook-wordcount 
+$ cargo add mdbook
 ```
 
 When our `mdbook-wordcount` plugin is invoked, `mdbook` will send it a JSON
@@ -33,8 +38,10 @@ This is all the boilerplate necessary for our backend to load the book.
 
 ```rust
 // src/main.rs
+extern crate mdbook;
+
 use std::io;
-use mdbook_renderer::RenderContext;
+use mdbook::renderer::RenderContext;
 
 fn main() {
     let mut stdin = io::stdin();
@@ -43,14 +50,15 @@ fn main() {
 ```
 
 > **Note:** The `RenderContext` contains a `version` field. This lets backends
-> figure out whether they are compatible with the version of `mdbook` it's being
-> called by. This `version` comes directly from the corresponding field in
-> `mdbook`'s `Cargo.toml`.
->
-> It is recommended that backends use the [`semver`] crate to inspect this field
-> and emit a warning if there may be a compatibility issue.
+  figure out whether they are compatible with the version of `mdbook` it's being
+  called by. This `version` comes directly from the corresponding field in
+  `mdbook`'s `Cargo.toml`. 
+  
+  It is recommended that backends use the [`semver`] crate to inspect this field
+  and emit a warning if there may be a compatibility issue.
 
-## Inspecting the book
+
+## Inspecting the Book
 
 Now our backend has a copy of the book, lets count how many words are in each
 chapter!
@@ -79,17 +87,17 @@ fn count_words(ch: &Chapter) -> usize {
 ```
 
 
-## Enabling the backend
+## Enabling the Backend
 
 Now we've got the basics running, we want to actually use it. First, install the
 program.
 
-```shell
-$ cargo install --path .
+```
+$ cargo install
 ```
 
 Then `cd` to the particular book you'd like to count the words of and update its
-`book.toml` file.
+`book.toml` file. 
 
 ```diff
   [book]
@@ -104,7 +112,7 @@ Then `cd` to the particular book you'd like to count the words of and update its
 
 When it loads a book into memory, `mdbook` will inspect your `book.toml` file to
 try and figure out which backends to use by looking for all `output.*` tables.
-If none are provided it'll fall back to using the default HTML renderer.
+If none are provided it'll fall back to using the default HTML renderer. 
 
 Notably, this means if you want to add your own custom backend you'll also need
 to make sure to add the HTML backend, even if its table just stays empty.
@@ -112,7 +120,7 @@ to make sure to add the HTML backend, even if its table just stays empty.
 Now you just need to build your book like normal, and everything should *Just
 Work*.
 
-```shell
+```
 $ mdbook build
 ...
 2018-01-16 07:31:15 [INFO] (mdbook::renderer): Invoking the "mdbook-wordcount" renderer
@@ -132,7 +140,7 @@ Syntax highlighting: 314
 MathJax Support: 153
 Rust code specific features: 148
 For Developers: 788
-Alternative Backends: 710
+Alternate Backends: 710
 Contributors: 85
 ```
 
@@ -161,7 +169,7 @@ arguments or be an interpreted script), you can use the `command` field.
 Now imagine you don't want to count the number of words on a particular chapter
 (it might be generated text/code, etc). The canonical way to do this is via the
 usual `book.toml` configuration file by adding items to your `[output.foo]`
-table.
+table. 
 
 The `Config` can be treated roughly as a nested hashmap which lets you call
 methods like `get()` to access the config's contents, with a
@@ -180,7 +188,9 @@ $ cargo add serde serde_derive
 And then you can create the config struct,
 
 ```rust
-use serde_derive::{Serialize, Deserialize};
+extern crate serde;
+#[macro_use]
+extern crate serde_derive;
 
 ...
 
@@ -201,13 +211,13 @@ and then add a check to make sure we skip ignored chapters.
 +     let cfg: WordcountConfig = ctx.config
 +         .get_deserialized("output.wordcount")
 +         .unwrap_or_default();
-
+  
       for item in ctx.book.iter() {
           if let BookItem::Chapter(ref ch) = *item {
 +             if cfg.ignores.contains(&ch.name) {
 +                 continue;
 +             }
-+
++ 
               let num_words = count_words(ch);
               println!("{}: {}", ch.name, num_words);
           }
@@ -216,7 +226,7 @@ and then add a check to make sure we skip ignored chapters.
 ```
 
 
-## Output and signalling failure
+## Output and Signalling Failure
 
 While it's nice to print word counts to the terminal when a book is built, it
 might also be a good idea to output them to a file somewhere. `mdbook` tells a
@@ -229,17 +239,17 @@ in [`RenderContext`].
 - use std::io;
   use mdbook::renderer::RenderContext;
   use mdbook::book::{BookItem, Chapter};
-
+  
   fn main() {
     ...
-
+  
 +     let _ = fs::create_dir_all(&ctx.destination);
 +     let mut f = File::create(ctx.destination.join("wordcounts.txt")).unwrap();
-+
++ 
       for item in ctx.book.iter() {
           if let BookItem::Chapter(ref ch) = *item {
               ...
-
+  
               let num_words = count_words(ch);
               println!("{}: {}", ch.name, num_words);
 +             writeln!(f, "{}: {}", ch.name, num_words).unwrap();
@@ -251,10 +261,6 @@ in [`RenderContext`].
 > **Note:** There is no guarantee that the destination directory exists or is
 > empty (`mdbook` may leave the previous contents to let backends do caching),
 > so it's always a good idea to create it with `fs::create_dir_all()`.
->
-> If the destination directory already exists, don't assume it will be empty.
-> To allow backends to cache the results from previous runs, `mdbook` may leave
-> old content in the directory.
 
 There's always the possibility that an error will occur while processing a book
 (just look at all the `unwrap()`'s we've written already), so `mdbook` will
@@ -270,11 +276,11 @@ like this:
 
   fn main() {
       ...
-
+  
       for item in ctx.book.iter() {
           if let BookItem::Chapter(ref ch) = *item {
               ...
-
+  
               let num_words = count_words(ch);
               println!("{}: {}", ch.name, num_words);
               writeln!(f, "{}: {}", ch.name, num_words).unwrap();
@@ -282,7 +288,7 @@ like this:
 +             if cfg.deny_odds && num_words % 2 == 1 {
 +               eprintln!("{} has an odd number of words!", ch.name);
 +               process::exit(1);
-+             }
+              }
           }
       }
   }
@@ -297,8 +303,8 @@ like this:
 
 Now, if we reinstall the backend and build a book,
 
-```shell
-$ cargo install --path . --force
+```
+$ cargo install --force
 $ mdbook build /path/to/book
 ...
 2018-01-16 21:21:39 [INFO] (mdbook::renderer): Invoking the "wordcount" renderer
@@ -317,12 +323,13 @@ the "rule of silence" and only generate output when necessary (e.g. an error in
 generation or a warning).
 
 All environment variables are passed through to the backend, allowing you to use
-the usual `MDBOOK_LOG` to control logging verbosity.
+the usual `RUST_LOG` to control logging verbosity.
 
-## Wrapping up
+
+## Wrapping Up
 
 Although contrived, hopefully this example was enough to show how you'd create
-an alternative backend for `mdbook`. If you feel it's missing something, don't
+an alternate backend for `mdbook`. If you feel it's missing something, don't
 hesitate to create an issue in the [issue tracker] so we can improve the user
 guide.
 
@@ -331,11 +338,14 @@ as a good example of how it's done in real life, so feel free to skim through
 the source code or ask questions.
 
 
-[Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins
-[`RenderContext`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/struct.RenderContext.html
-[`RenderContext::from_json()`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/struct.RenderContext.html#method.from_json
+[mdbook-linkcheck]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
+[mdbook-epub]: https://github.com/Michael-F-Bryan/mdbook-epub
+[mdbook-test]: https://github.com/Michael-F-Bryan/mdbook-test
+[rust-skeptic]: https://github.com/budziq/rust-skeptic
+[`RenderContext`]: http://rust-lang-nursery.github.io/mdBook/mdbook/renderer/struct.RenderContext.html
+[`RenderContext::from_json()`]: http://rust-lang-nursery.github.io/mdBook/mdbook/renderer/struct.RenderContext.html#method.from_json
 [`semver`]: https://crates.io/crates/semver
-[`Book`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/book/struct.Book.html
-[`Book::iter()`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/book/struct.Book.html#method.iter
-[`Config`]: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/config/struct.Config.html
-[issue tracker]: https://github.com/rust-lang/mdBook/issues
+[`Book`]: http://rust-lang-nursery.github.io/mdBook/mdbook/book/struct.Book.html
+[`Book::iter()`]: http://rust-lang-nursery.github.io/mdBook/mdbook/book/struct.Book.html#method.iter
+[`Config`]: http://rust-lang-nursery.github.io/mdBook/mdbook/config/struct.Config.html
+[issue tracker]: https://github.com/rust-lang-nursery/mdBook/issues

book-example/src/for_developers/preprocessors.md

@@ -0,0 +1,109 @@
+# 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
+
+
+## Implementing a Preprocessor
+
+A preprocessor is represented by the `Preprocessor` trait.
+
+```rust
+pub trait Preprocessor {
+    fn name(&self) -> &str;
+    fn run(&self, ctx: &PreprocessorContext, book: Book) -> Result<Book>;
+    fn supports_renderer(&self, _renderer: &str) -> bool {
+        true
+    }
+}
+```
+
+Where the `PreprocessorContext` is defined as
+
+```rust
+pub struct PreprocessorContext {
+    pub root: PathBuf,
+    pub config: Config,
+    /// The `Renderer` this preprocessor is being used with.
+    pub renderer: String,
+}
+```
+
+The `renderer` value allows you react accordingly, for example, PDF or HTML.
+
+## A complete Example
+
+The magic happens within the `run(...)` method of the
+[`Preprocessor`][preprocessor-docs] trait implementation.
+
+As direct access to the chapters is not possible, you will probably end up
+iterating them using `for_each_mut(...)`:
+
+```rust
+book.for_each_mut(|item: &mut BookItem| {
+    if let BookItem::Chapter(ref mut chapter) = *item {
+      eprintln!("{}: processing chapter '{}'", self.name(), chapter.name);
+      res = Some(
+          match Deemphasize::remove_emphasis(&mut num_removed_items, chapter) {
+              Ok(md) => {
+                  chapter.content = md;
+                  Ok(())
+              }
+              Err(err) => Err(err),
+          },
+      );
+  }
+});
+```
+
+The `chapter.content` is just a markdown formatted string, and you will have to
+process it in some way. Even though it's entirely possible to implement some
+sort of manual find & replace operation, if that feels too unsafe you can use
+[`pulldown-cmark`][pc] to parse the string into events and work on them instead.
+
+Finally you can use [`pulldown-cmark-to-cmark`][pctc] to transform these events
+back to a string.
+
+The following code block shows how to remove all emphasis from markdown, and do
+so safely.
+
+```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/de-emphasize.rs

book-example/src/format/config.md

@@ -0,0 +1,259 @@
+# 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
+
+[preprocess.index]
+
+[preprocess.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 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.
+
+**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`
+```
+
+### 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 }}` and `{{ #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
+
+[preprocess.links]
+
+[preprocess.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
+
+```
+[preprocess.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.
+
+```
+[preprocessor.mathjax]
+renderers = ["html"]  # mathjax only makes sense with the HTML renderer
+```
+
+## 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.
+- **curly-quotes:** Convert straight quotes to curly quotes, except for those
+  that occur in code blocks and code spans. 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`.
+- **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).
+
+Available configuration options for the `[output.html.playpen]` table:
+
+- **editable:** Allow editing the source code. Defaults to `false`.
+- **copy-js:** Copy JavaScript files for the editor to the output directory.
+  Defaults to `true`.
+
+[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 `true`.
+- **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 options in the **book.toml**:
+```toml
+[book]
+title = "Example book"
+authors = ["John Doe", "Jane Doe"]
+description = "The example book covers examples."
+
+[build]
+build-dir = "book"
+create-missing = true
+preprocess = ["links", "index"]
+
+[output.html]
+theme = "my-theme"
+curly-quotes = true
+google-analytics = "123456"
+additional-css = ["custom.css", "custom2.css"]
+additional-js = ["custom.js"]
+
+[output.html.playpen]
+editor = "./path/to/editor"
+editable = false
+
+[output.html.search]
+enable = true
+searcher = "./path/to/searcher"
+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
+```
+
+
+## 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
+>
+> ```text
+> $ 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/mathjax.md

@@ -1,4 +1,4 @@
-# MathJax support
+# MathJax Support
 
 mdBook has optional support for math equations through
 [MathJax](https://www.mathjax.org/).

book-example/src/format/mdbook.md

@@ -0,0 +1,74 @@
+# mdBook-specific markdown
+
+## 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);
+# }
+```
+
+## 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.
+
+Usually, this command is used for including code snippets and examples. In this
+case, oftens one would include a specific part of the file e.g. which only
+contains the relevant lines for the 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.
+
+## 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

@@ -0,0 +1,38 @@
+# 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

@@ -0,0 +1,34 @@
+# 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

@@ -0,0 +1,46 @@
+# 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/index-hbs.md

@@ -0,0 +1,97 @@
+# index.hbs
+
+`index.hbs` is the handlebars template that is used to render the book. The
+markdown files are processed to html and then injected in that template.
+
+If you want to change the layout or style of your book, chances are that you
+will have to modify this template a little bit. Here is what you need to know.
+
+## Data
+
+A lot of data is exposed to the handlebars template with the "context". In the
+handlebars template you can access this information by using
+
+```handlebars
+{{name_of_property}}
+```
+
+Here is a list of the properties that are exposed:
+
+- ***language*** Language of the book in the form `en`. To use in <code
+  class="language-html">\<html lang="{{ language }}"></code> for example. At the
+  moment it is hardcoded.
+- ***title*** Title of the book, as specified in `book.toml`
+- ***chapter_title*** Title of the current chapter, as listed in `SUMMARY.md`
+
+- ***path*** Relative path to the original markdown file from the source
+  directory
+- ***content*** This is the rendered markdown.
+- ***path_to_root*** This is a path containing exclusively `../`'s that points
+  to the root of the book from the current file. Since the original directory
+  structure is maintained, it is useful to prepend relative links with this
+  `path_to_root`.
+
+- ***chapters*** Is an array of dictionaries of the form
+  ```json
+  {"section": "1.2.1", "name": "name of this chapter", "path": "dir/markdown.md"}
+  ```
+  containing all the chapters of the book. It is used for example to construct
+  the table of contents (sidebar).
+
+## Handlebars Helpers
+
+In addition to the properties you can access, there are some handlebars helpers
+at your disposal.
+
+### 1. toc
+
+    The toc helper is used like this
+
+    ```handlebars
+    {{#toc}}{{/toc}}
+    ```
+
+    and outputs something that looks like this, depending on the structure of your book
+
+    ```html
+    <ul class="chapter">
+        <li><a href="link/to/file.html">Some chapter</a></li>
+        <li>
+            <ul class="section">
+                <li><a href="link/to/other_file.html">Some other Chapter</a></li>
+            </ul>
+        </li>
+    </ul>
+    ```
+
+    If you would like to make a toc with another structure, you have access to the chapters property containing all the data.
+    The only limitation at the moment is that you would have to do it with JavaScript instead of with a handlebars helper.
+
+    ```html
+    <script>
+    var chapters = {{chapters}};
+    // Processing here
+    </script>
+    ```
+
+### 2. previous / next
+
+    The previous and next helpers expose a `link` and `name` property to the previous and next chapters.
+
+    They are used like this
+
+    ```handlebars
+    {{#previous}}
+        <a href="{{link}}" class="nav-chapters previous">
+            <i class="fa fa-angle-left"></i>
+        </a>
+    {{/previous}}
+    ```
+
+    The inner html will only be rendered if the previous / next chapter exists.
+    Of course the inner html can be changed to your liking.
+
+------
+
+*If you would like other properties or helpers exposed, please [create a new
+issue](https://github.com/rust-lang-nursery/mdBook/issues)*

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

@@ -0,0 +1,70 @@
+# 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/contributors.md

@@ -15,10 +15,6 @@ shout-out to them!
 - [projektir](https://github.com/projektir)
 - [Phaiax](https://github.com/Phaiax)
 - Matt Ickstadt ([mattico](https://github.com/mattico))
-- Weihang Lo ([weihanglo](https://github.com/weihanglo))
-- Avision Ho ([avisionh](https://github.com/avisionh))
-- Vivek Akupatni ([apatniv](https://github.com/apatniv))
-- Eric Huss ([ehuss](https://github.com/ehuss))
-- Josh Rotenberg ([joshrotenberg](https://github.com/joshrotenberg))
+- Weihang Lo ([@weihanglo](https://github.com/weihanglo))
 
-If you feel you're missing from this list, feel free to add yourself in a PR.
+If you feel you're missing from this list, feel free to add yourself in a PR.

book-example/src/misc/introduction.md

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

ci/before_deploy.sh

@@ -0,0 +1,32 @@
+# This script takes care of building your crate and packaging it for release
+
+set -ex
+
+main() {
+    local src=$(pwd) \
+          stage=
+
+    case $TRAVIS_OS_NAME in
+        linux)
+            stage=$(mktemp -d)
+            ;;
+        osx)
+            stage=$(mktemp -d -t tmp)
+            ;;
+    esac
+
+    # This will slow down the build, but is necessary to not run out of disk space
+    cargo clean
+
+    cargo rustc --bin mdbook --target $TARGET --release -- -C lto
+
+    cp target/$TARGET/release/mdbook $stage/
+
+    cd $stage
+    tar czf $src/$CRATE_NAME-$TRAVIS_TAG-$TARGET.tar.gz *
+    cd $src
+
+    rm -rf $stage
+}
+
+main

ci/install-rust.sh

@@ -1,43 +0,0 @@
-#!/usr/bin/env bash
-# Install/update rust.
-# The first argument should be the toolchain to install.
-
-set -ex
-if [ -z "$1" ]
-then
-    echo "First parameter must be toolchain to install."
-    exit 1
-fi
-TOOLCHAIN="$1"
-
-rustup set profile minimal
-rustup component remove --toolchain=$TOOLCHAIN rust-docs || echo "already removed"
-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
-cargo -V

ci/make-release-asset.sh

@@ -1,49 +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")
-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/publish-guide.sh

@@ -1,38 +0,0 @@
-#!/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

@@ -1,44 +0,0 @@
-#!/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

@@ -1,12 +0,0 @@
-[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

@@ -1,26 +0,0 @@
-# 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

@@ -1,113 +0,0 @@
-//! 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

@@ -1,22 +0,0 @@
-[package]
-name = "mdbook-core"
-version = "0.5.2"
-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

@@ -1,13 +0,0 @@
-# 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

@@ -1,288 +0,0 @@
-//! 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

@@ -1,123 +0,0 @@
-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

@@ -1,16 +0,0 @@
-//! 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

@@ -1,273 +0,0 @@
-//! 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

@@ -1,78 +0,0 @@
-//! 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

@@ -1,37 +0,0 @@
-//! 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

@@ -1,94 +0,0 @@
-//! 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

@@ -1,32 +0,0 @@
-[package]
-name = "mdbook-driver"
-version = "0.5.2"
-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

@@ -1,13 +0,0 @@
-# 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

@@ -1,183 +0,0 @@
-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/links.rs

@@ -1,936 +0,0 @@
-use self::take_lines::{
-    take_anchored_lines, take_lines, take_rustdoc_include_anchored_lines,
-    take_rustdoc_include_lines,
-};
-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};
-
-mod take_lines;
-
-const ESCAPE_CHAR: char = '\\';
-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.
-/// - `{{# 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 `#`.
-///   This hides the lines from initial display but shows them when the reader expands the code
-///   block and provides them to Rustdoc for testing.
-/// - `{{# playground}}` - Insert runnable Rust files
-/// - `{{# title}}` - Override \<title\> of a webpage.
-#[derive(Default)]
-#[non_exhaustive]
-pub struct LinkPreprocessor;
-
-impl LinkPreprocessor {
-    /// Name of this preprocessor.
-    pub const NAME: &'static str = "links";
-
-    /// Create a new `LinkPreprocessor`.
-    pub fn new() -> Self {
-        LinkPreprocessor
-    }
-}
-
-impl Preprocessor for LinkPreprocessor {
-    fn name(&self) -> &str {
-        Self::NAME
-    }
-
-    fn run(&self, ctx: &PreprocessorContext, mut book: Book) -> Result<Book> {
-        let src_dir = ctx.root.join(&ctx.config.book.src);
-
-        book.for_each_mut(|section: &mut BookItem| {
-            if let BookItem::Chapter(ref mut ch) = *section {
-                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 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);
-                    }
-                }
-            }
-        });
-
-        Ok(book)
-    }
-}
-
-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>,
-{
-    // When replacing one thing in a string by something with a different length,
-    // the indices after that will not correspond,
-    // we therefore have to store the difference to correct this
-    let path = path.as_ref();
-    let source = source.as_ref();
-    let mut previous_end_index = 0;
-    let mut replaced = String::new();
-
-    for link in find_links(s) {
-        replaced.push_str(&s[previous_end_index..link.start_index]);
-
-        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,
-                            chapter_title,
-                        ));
-                    } else {
-                        replaced.push_str(&new_content);
-                    }
-                } else {
-                    error!(
-                        "Stack depth exceeded in {}. Check for cyclic includes",
-                        source.display()
-                    );
-                }
-                previous_end_index = link.end_index;
-            }
-            Err(e) => {
-                error!("Error updating \"{}\", {}", link.link_text, e);
-                for cause in e.chain().skip(1) {
-                    warn!("Caused By: {}", cause);
-                }
-
-                // This should make sure we include the raw `{{# ... }}` snippet
-                // in the page content if there are any errors.
-                previous_end_index = link.start_index;
-            }
-        }
-    }
-
-    replaced.push_str(&s[previous_end_index..]);
-    replaced
-}
-
-#[derive(PartialEq, Debug, Clone)]
-enum LinkType<'a> {
-    Escaped,
-    Include(PathBuf, RangeOrAnchor),
-    Playground(PathBuf, Vec<&'a str>),
-    RustdocInclude(PathBuf, RangeOrAnchor),
-    Title(&'a str),
-}
-
-#[derive(PartialEq, Debug, Clone)]
-enum RangeOrAnchor {
-    Range(LineRange),
-    Anchor(String),
-}
-
-// A range of lines specified with some include directive.
-#[derive(PartialEq, Debug, Clone)]
-enum LineRange {
-    Range(Range<usize>),
-    RangeFrom(RangeFrom<usize>),
-    RangeTo(RangeTo<usize>),
-    RangeFull(RangeFull),
-}
-
-impl RangeBounds<usize> for LineRange {
-    fn start_bound(&self) -> Bound<&usize> {
-        match self {
-            LineRange::Range(r) => r.start_bound(),
-            LineRange::RangeFrom(r) => r.start_bound(),
-            LineRange::RangeTo(r) => r.start_bound(),
-            LineRange::RangeFull(r) => r.start_bound(),
-        }
-    }
-
-    fn end_bound(&self) -> Bound<&usize> {
-        match self {
-            LineRange::Range(r) => r.end_bound(),
-            LineRange::RangeFrom(r) => r.end_bound(),
-            LineRange::RangeTo(r) => r.end_bound(),
-            LineRange::RangeFull(r) => r.end_bound(),
-        }
-    }
-}
-
-impl From<Range<usize>> for LineRange {
-    fn from(r: Range<usize>) -> LineRange {
-        LineRange::Range(r)
-    }
-}
-
-impl From<RangeFrom<usize>> for LineRange {
-    fn from(r: RangeFrom<usize>) -> LineRange {
-        LineRange::RangeFrom(r)
-    }
-}
-
-impl From<RangeTo<usize>> for LineRange {
-    fn from(r: RangeTo<usize>) -> LineRange {
-        LineRange::RangeTo(r)
-    }
-}
-
-impl From<RangeFull> for LineRange {
-    fn from(r: RangeFull) -> LineRange {
-        LineRange::RangeFull(r)
-    }
-}
-
-impl<'a> LinkType<'a> {
-    fn relative_path<P: AsRef<Path>>(self, base: P) -> Option<PathBuf> {
-        let base = base.as_ref();
-        match self {
-            LinkType::Escaped => None,
-            LinkType::Include(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,
-        }
-    }
-}
-fn return_relative_path<P: AsRef<Path>>(base: P, relative: P) -> PathBuf {
-    base.as_ref()
-        .join(relative)
-        .parent()
-        .expect("Included file should not be /")
-        .to_path_buf()
-}
-
-fn parse_range_or_anchor(parts: Option<&str>) -> RangeOrAnchor {
-    let mut parts = parts.unwrap_or("").splitn(3, ':').fuse();
-
-    let next_element = parts.next();
-    let start = if let Some(value) = next_element.and_then(|s| s.parse::<usize>().ok()) {
-        // subtract 1 since line numbers usually begin with 1
-        Some(value.saturating_sub(1))
-    } else if let Some("") = next_element {
-        None
-    } else if let Some(anchor) = next_element {
-        return RangeOrAnchor::Anchor(String::from(anchor));
-    } else {
-        None
-    };
-
-    let end = parts.next();
-    // If `end` is empty string or any other value that can't be parsed as a usize, treat this
-    // include as a range with only a start bound. However, if end isn't specified, include only
-    // the single line specified by `start`.
-    let end = end.map(|s| s.parse::<usize>());
-
-    match (start, end) {
-        (Some(start), Some(Ok(end))) => RangeOrAnchor::Range(LineRange::from(start..end)),
-        (Some(start), Some(Err(_))) => RangeOrAnchor::Range(LineRange::from(start..)),
-        (Some(start), None) => RangeOrAnchor::Range(LineRange::from(start..start + 1)),
-        (None, Some(Ok(end))) => RangeOrAnchor::Range(LineRange::from(..end)),
-        (None, None) | (None, Some(Err(_))) => RangeOrAnchor::Range(LineRange::from(RangeFull)),
-    }
-}
-
-fn parse_include_path(path: &str) -> LinkType<'static> {
-    let mut parts = path.splitn(2, ':');
-
-    let path = parts.next().unwrap().into();
-    let range_or_anchor = parse_range_or_anchor(parts.next());
-
-    LinkType::Include(path, range_or_anchor)
-}
-
-fn parse_rustdoc_include_path(path: &str) -> LinkType<'static> {
-    let mut parts = path.splitn(2, ':');
-
-    let path = parts.next().unwrap().into();
-    let range_or_anchor = parse_range_or_anchor(parts.next());
-
-    LinkType::RustdocInclude(path, range_or_anchor)
-}
-
-#[derive(PartialEq, Debug, Clone)]
-struct Link<'a> {
-    start_index: usize,
-    end_index: usize,
-    link_type: LinkType<'a>,
-    link_text: &'a str,
-}
-
-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();
-                let props: Vec<&str> = path_props.collect();
-
-                match (typ.as_str(), file_arg) {
-                    ("include", Some(pth)) => Some(parse_include_path(pth)),
-                    ("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,
-                }
-            }
-            (Some(mat), None, None) if mat.as_str().starts_with(ESCAPE_CHAR) => {
-                Some(LinkType::Escaped)
-            }
-            _ => None,
-        };
-
-        link_type.and_then(|lnk_type| {
-            cap.get(0).map(|mat| Link {
-                start_index: mat.start(),
-                end_index: mat.end(),
-                link_type: lnk_type,
-                link_text: mat.as_str(),
-            })
-        })
-    }
-
-    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::Include(ref pat, ref range_or_anchor) => {
-                let target = base.join(pat);
-
-                fs::read_to_string(&target)
-                    .map(|s| match range_or_anchor {
-                        RangeOrAnchor::Range(range) => take_lines(&s, range.clone()),
-                        RangeOrAnchor::Anchor(anchor) => take_anchored_lines(&s, anchor),
-                    })
-                    .with_context(|| {
-                        format!(
-                            "Could not read file for link {} ({})",
-                            self.link_text,
-                            target.display(),
-                        )
-                    })
-            }
-            LinkType::RustdocInclude(ref pat, ref range_or_anchor) => {
-                let target = base.join(pat);
-
-                fs::read_to_string(&target)
-                    .map(|s| match range_or_anchor {
-                        RangeOrAnchor::Range(range) => {
-                            take_rustdoc_include_lines(&s, range.clone())
-                        }
-                        RangeOrAnchor::Anchor(anchor) => {
-                            take_rustdoc_include_anchored_lines(&s, anchor)
-                        }
-                    })
-                    .with_context(|| {
-                        format!(
-                            "Could not read file for link {} ({})",
-                            self.link_text,
-                            target.display(),
-                        )
-                    })
-            }
-            LinkType::Playground(ref pat, ref attrs) => {
-                let target = base.join(pat);
-
-                let mut contents = fs::read_to_string(&target).with_context(|| {
-                    format!(
-                        "Could not read file for link {} ({})",
-                        self.link_text,
-                        target.display()
-                    )
-                })?;
-                let ftype = if !attrs.is_empty() { "rust," } else { "rust" };
-                if !contents.ends_with('\n') {
-                    contents.push('\n');
-                }
-                Ok(format!(
-                    "```{}{}\n{}```\n",
-                    ftype,
-                    attrs.join(","),
-                    contents
-                ))
-            }
-            LinkType::Title(title) => {
-                *chapter_title = title.to_owned();
-                Ok(String::new())
-            }
-        }
-    }
-}
-
-struct LinkIter<'a>(CaptureMatches<'a, 'a>);
-
-impl<'a> Iterator for LinkIter<'a> {
-    type Item = Link<'a>;
-    fn next(&mut self) -> Option<Link<'a>> {
-        for cap in &mut self.0 {
-            if let Some(inc) = Link::from_capture(cap) {
-                return Some(inc);
-            }
-        }
-        None
-    }
-}
-
-fn find_links(contents: &str) -> LinkIter<'_> {
-    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)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_replace_all_escaped() {
-        let start = r"
-        Some text over here.
-        ```hbs
-        \{{#include file.rs}} << an escaped link!
-        ```";
-        let end = r"
-        Some text over here.
-        ```hbs
-        {{#include file.rs}} << an escaped link!
-        ```";
-        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]
-    fn test_find_links_no_link() {
-        let s = "Some random text without link...";
-        assert!(find_links(s).collect::<Vec<_>>() == vec![]);
-    }
-
-    #[test]
-    fn test_find_links_partial_link() {
-        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![]);
-        let s = "Some random text with \\{{#include...";
-        assert!(find_links(s).collect::<Vec<_>>() == vec![]);
-    }
-
-    #[test]
-    fn test_find_links_empty_link() {
-        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 {{#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 {{#playground file.rs}} and {{#playground test.rs }}...";
-
-        let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {res:?}\n");
-
-        assert_eq!(
-            res,
-            vec![
-                Link {
-                    start_index: 22,
-                    end_index: 45,
-                    link_type: LinkType::Playground(PathBuf::from("file.rs"), vec![]),
-                    link_text: "{{#playground file.rs}}",
-                },
-                Link {
-                    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 22,
-                end_index: 48,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Range(LineRange::from(9..20))
-                ),
-                link_text: "{{#include file.rs:10:20}}",
-            }]
-        );
-    }
-
-    #[test]
-    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 22,
-                end_index: 45,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Range(LineRange::from(9..10))
-                ),
-                link_text: "{{#include file.rs:10}}",
-            }]
-        );
-    }
-
-    #[test]
-    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 22,
-                end_index: 46,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Range(LineRange::from(9..))
-                ),
-                link_text: "{{#include file.rs:10:}}",
-            }]
-        );
-    }
-
-    #[test]
-    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 22,
-                end_index: 46,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Range(LineRange::from(..20))
-                ),
-                link_text: "{{#include file.rs::20}}",
-            }]
-        );
-    }
-
-    #[test]
-    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 22,
-                end_index: 44,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Range(LineRange::from(..))
-                ),
-                link_text: "{{#include file.rs::}}",
-            }]
-        );
-    }
-
-    #[test]
-    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 22,
-                end_index: 42,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Range(LineRange::from(..))
-                ),
-                link_text: "{{#include file.rs}}",
-            }]
-        );
-    }
-
-    #[test]
-    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 22,
-                end_index: 49,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Anchor(String::from("anchor"))
-                ),
-                link_text: "{{#include file.rs:anchor}}",
-            }]
-        );
-    }
-
-    #[test]
-    fn test_find_links_escaped_link() {
-        let s = "Some random text with escaped playground \\{{#playground file.rs editable}} ...";
-
-        let res = find_links(s).collect::<Vec<_>>();
-        println!("\nOUTPUT: {res:?}\n");
-
-        assert_eq!(
-            res,
-            vec![Link {
-                start_index: 41,
-                end_index: 74,
-                link_type: LinkType::Escaped,
-                link_text: "\\{{#playground file.rs editable}}",
-            }]
-        );
-    }
-
-    #[test]
-    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: {res:?}\n");
-        assert_eq!(
-            res,
-            vec![
-                Link {
-                    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: 95,
-                    end_index: 145,
-                    link_type: LinkType::Playground(
-                        PathBuf::from("my.rs"),
-                        vec!["editable", "no_run", "should_panic"],
-                    ),
-                    link_text: "{{#playground my.rs editable no_run should_panic}}",
-                },
-            ]
-        );
-    }
-
-    #[test]
-    fn test_find_all_link_types() {
-        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: {res:?}\n");
-        assert_eq!(res.len(), 3);
-        assert_eq!(
-            res[0],
-            Link {
-                start_index: 41,
-                end_index: 61,
-                link_type: LinkType::Include(
-                    PathBuf::from("file.rs"),
-                    RangeOrAnchor::Range(LineRange::from(..))
-                ),
-                link_text: "{{#include file.rs}}",
-            }
-        );
-        assert_eq!(
-            res[1],
-            Link {
-                start_index: 66,
-                end_index: 115,
-                link_type: LinkType::Escaped,
-                link_text: "\\{{#contents are insignifficant in escaped link}}",
-            }
-        );
-        assert_eq!(
-            res[2],
-            Link {
-                start_index: 133,
-                end_index: 183,
-                link_type: LinkType::Playground(
-                    PathBuf::from("my.rs"),
-                    vec!["editable", "no_run", "should_panic"]
-                ),
-                link_text: "{{#playground my.rs editable no_run should_panic}}",
-            }
-        );
-    }
-
-    #[test]
-    fn parse_without_colon_includes_all() {
-        let link_type = parse_include_path("arbitrary");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(RangeFull))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_nothing_after_colon_includes_all() {
-        let link_type = parse_include_path("arbitrary:");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(RangeFull))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_two_colons_includes_all() {
-        let link_type = parse_include_path("arbitrary::");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(RangeFull))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_garbage_after_two_colons_includes_all() {
-        let link_type = parse_include_path("arbitrary::NaN");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(RangeFull))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_one_number_after_colon_only_that_line() {
-        let link_type = parse_include_path("arbitrary:5");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(4..5))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_one_based_start_becomes_zero_based() {
-        let link_type = parse_include_path("arbitrary:1");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(0..1))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_zero_based_start_stays_zero_based_but_is_probably_an_error() {
-        let link_type = parse_include_path("arbitrary:0");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(0..1))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_start_only_range() {
-        let link_type = parse_include_path("arbitrary:5:");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(4..))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_start_with_garbage_interpreted_as_start_only_range() {
-        let link_type = parse_include_path("arbitrary:5:NaN");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(4..))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_end_only_range() {
-        let link_type = parse_include_path("arbitrary::5");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(..5))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_start_and_end_range() {
-        let link_type = parse_include_path("arbitrary:5:10");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(4..10))
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_negative_interpreted_as_anchor() {
-        let link_type = parse_include_path("arbitrary:-5");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Anchor("-5".to_string())
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_floating_point_interpreted_as_anchor() {
-        let link_type = parse_include_path("arbitrary:-5.7");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Anchor("-5.7".to_string())
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_anchor_followed_by_colon() {
-        let link_type = parse_include_path("arbitrary:some-anchor:this-gets-ignored");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Anchor("some-anchor".to_string())
-            )
-        );
-    }
-
-    #[test]
-    fn parse_with_more_than_three_colons_ignores_everything_after_third_colon() {
-        let link_type = parse_include_path("arbitrary:5:10:17:anything:");
-        assert_eq!(
-            link_type,
-            LinkType::Include(
-                PathBuf::from("arbitrary"),
-                RangeOrAnchor::Range(LineRange::from(4..10))
-            )
-        );
-    }
-}

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

@@ -1,253 +0,0 @@
-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(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 lines = s.lines().skip(start);
-    match range.end_bound() {
-        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"),
-    }
-}
-
-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(super) fn take_anchored_lines(s: &str, anchor: &str) -> String {
-    let mut retained = Vec::<&str>::new();
-    let mut anchor_found = false;
-
-    for l in s.lines() {
-        if anchor_found {
-            match ANCHOR_END.captures(l) {
-                Some(cap) => {
-                    if &cap["anchor_name"] == anchor {
-                        break;
-                    }
-                }
-                None => {
-                    if !ANCHOR_START.is_match(l) {
-                        retained.push(l);
-                    }
-                }
-            }
-        } else if let Some(cap) = ANCHOR_START.captures(l) {
-            if &cap["anchor_name"] == anchor {
-                anchor_found = true;
-            }
-        }
-    }
-
-    retained.join("\n")
-}
-
-/// Keep lines contained within the range specified as-is.
-/// 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(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() {
-        if !range.contains(&index) {
-            output.push_str("# ");
-        }
-        output.push_str(line);
-        output.push('\n');
-    }
-    output.pop();
-    output
-}
-
-/// Keep lines between the anchor comments specified as-is.
-/// 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(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;
-
-    for l in s.lines() {
-        if within_anchored_section {
-            match ANCHOR_END.captures(l) {
-                Some(cap) => {
-                    if &cap["anchor_name"] == anchor {
-                        within_anchored_section = false;
-                    }
-                }
-                None => {
-                    if !ANCHOR_START.is_match(l) {
-                        output.push_str(l);
-                        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('\n');
-        }
-    }
-
-    output.pop();
-    output
-}
-
-#[cfg(test)]
-mod tests {
-    use super::{
-        take_anchored_lines, take_lines, take_rustdoc_include_anchored_lines,
-        take_rustdoc_include_lines,
-    };
-
-    #[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");
-        assert_eq!(take_lines(s, 3..), "sit\namet");
-        assert_eq!(take_lines(s, ..3), "Lorem\nipsum\ndolor");
-        assert_eq!(take_lines(s, ..), s);
-        // corner cases
-        assert_eq!(take_lines(s, 4..3), "");
-        assert_eq!(take_lines(s, ..100), s);
-    }
-
-    #[test]
-    fn take_anchored_lines_test() {
-        let s = "Lorem\nipsum\ndolor\nsit\namet";
-        assert_eq!(take_anchored_lines(s, "test"), "");
-
-        let s = "Lorem\nipsum\ndolor\nANCHOR_END: test\nsit\namet";
-        assert_eq!(take_anchored_lines(s, "test"), "");
-
-        let s = "Lorem\nipsum\nANCHOR: test\ndolor\nsit\namet";
-        assert_eq!(take_anchored_lines(s, "test"), "dolor\nsit\namet");
-        assert_eq!(take_anchored_lines(s, "something"), "");
-
-        let s = "Lorem\nipsum\nANCHOR: test\ndolor\nsit\namet\nANCHOR_END: test\nlorem\nipsum";
-        assert_eq!(take_anchored_lines(s, "test"), "dolor\nsit\namet");
-        assert_eq!(take_anchored_lines(s, "something"), "");
-
-        let s = "Lorem\nANCHOR: test\nipsum\nANCHOR: test\ndolor\nsit\namet\nANCHOR_END: test\nlorem\nipsum";
-        assert_eq!(take_anchored_lines(s, "test"), "ipsum\ndolor\nsit\namet");
-        assert_eq!(take_anchored_lines(s, "something"), "");
-
-        let s = "Lorem\nANCHOR:    test2\nipsum\nANCHOR: test\ndolor\nsit\namet\nANCHOR_END: test\nlorem\nANCHOR_END:test2\nipsum";
-        assert_eq!(
-            take_anchored_lines(s, "test2"),
-            "ipsum\ndolor\nsit\namet\nlorem"
-        );
-        assert_eq!(take_anchored_lines(s, "test"), "dolor\nsit\namet");
-        assert_eq!(take_anchored_lines(s, "something"), "");
-    }
-
-    #[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!(
-            take_rustdoc_include_lines(s, 1..3),
-            "# Lorem\nipsum\ndolor\n# sit\n# amet"
-        );
-        assert_eq!(
-            take_rustdoc_include_lines(s, 3..),
-            "# Lorem\n# ipsum\n# dolor\nsit\namet"
-        );
-        assert_eq!(
-            take_rustdoc_include_lines(s, ..3),
-            "Lorem\nipsum\ndolor\n# sit\n# amet"
-        );
-        assert_eq!(take_rustdoc_include_lines(s, ..), s);
-        // corner cases
-        assert_eq!(
-            take_rustdoc_include_lines(s, 4..3),
-            "# Lorem\n# ipsum\n# dolor\n# sit\n# amet"
-        );
-        assert_eq!(take_rustdoc_include_lines(s, ..100), s);
-    }
-
-    #[test]
-    fn take_rustdoc_include_anchored_lines_test() {
-        let s = "Lorem\nipsum\ndolor\nsit\namet";
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test"),
-            "# Lorem\n# ipsum\n# dolor\n# sit\n# amet"
-        );
-
-        let s = "Lorem\nipsum\ndolor\nANCHOR_END: test\nsit\namet";
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test"),
-            "# Lorem\n# ipsum\n# dolor\n# sit\n# amet"
-        );
-
-        let s = "Lorem\nipsum\nANCHOR: test\ndolor\nsit\namet";
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test"),
-            "# Lorem\n# ipsum\ndolor\nsit\namet"
-        );
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "something"),
-            "# Lorem\n# ipsum\n# dolor\n# sit\n# amet"
-        );
-
-        let s = "Lorem\nipsum\nANCHOR: test\ndolor\nsit\namet\nANCHOR_END: test\nlorem\nipsum";
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test"),
-            "# Lorem\n# ipsum\ndolor\nsit\namet\n# lorem\n# ipsum"
-        );
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "something"),
-            "# Lorem\n# ipsum\n# dolor\n# sit\n# amet\n# lorem\n# ipsum"
-        );
-
-        let s = "Lorem\nANCHOR: test\nipsum\nANCHOR: test\ndolor\nsit\namet\nANCHOR_END: test\nlorem\nipsum";
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test"),
-            "# Lorem\nipsum\ndolor\nsit\namet\n# lorem\n# ipsum"
-        );
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "something"),
-            "# Lorem\n# ipsum\n# dolor\n# sit\n# amet\n# lorem\n# ipsum"
-        );
-
-        let s = "Lorem\nANCHOR:    test2\nipsum\nANCHOR: test\ndolor\nsit\namet\nANCHOR_END: test\nlorem\nANCHOR_END:test2\nipsum";
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test2"),
-            "# Lorem\nipsum\ndolor\nsit\namet\nlorem\n# ipsum"
-        );
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test"),
-            "# Lorem\n# ipsum\ndolor\nsit\namet\n# lorem\n# ipsum"
-        );
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "something"),
-            "# Lorem\n# ipsum\n# dolor\n# sit\n# amet\n# lorem\n# ipsum"
-        );
-
-        let s = "Lorem\nANCHOR: test\nipsum\nANCHOR_END: test\ndolor\nANCHOR: test\nsit\nANCHOR_END: test\namet";
-        assert_eq!(
-            take_rustdoc_include_anchored_lines(s, "test"),
-            "# Lorem\nipsum\n# dolor\nsit\n# amet"
-        );
-    }
-}

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

@@ -1,9 +0,0 @@
-//! 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,46 +0,0 @@
-use anyhow::{Context, Result};
-use mdbook_core::utils::fs;
-use mdbook_renderer::{RenderContext, Renderer};
-use tracing::trace;
-
-/// 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 {
-    /// Create a new `MarkdownRenderer` instance.
-    pub fn new() -> Self {
-        MarkdownRenderer
-    }
-}
-
-impl Renderer for MarkdownRenderer {
-    fn name(&self) -> &str {
-        "markdown"
-    }
-
-    fn render(&self, ctx: &RenderContext) -> Result<()> {
-        let destination = &ctx.destination;
-        let book = &ctx.book;
-
-        if destination.exists() {
-            fs::remove_dir_content(destination)
-                .with_context(|| "Unable to remove stale Markdown output")?;
-        }
-
-        trace!("markdown render");
-        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)
-            .with_context(|| "Unexpected error when constructing destination path")?;
-
-        Ok(())
-    }
-}

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

@@ -1,88 +0,0 @@
-//! 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/lib.rs

@@ -1,131 +0,0 @@
-//! 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

@@ -1,309 +0,0 @@
-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

@@ -1,569 +0,0 @@
-//! 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, 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(())
-            }
-        }
-
-        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;
-                    eprintln!(
-                        "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

@@ -1,284 +0,0 @@
-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

@@ -1,37 +0,0 @@
-[package]
-name = "mdbook-html"
-version = "0.5.2"
-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

@@ -1,13 +0,0 @@
-# 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/chrome.css

@@ -1,756 +0,0 @@
-/* CSS for UI elements (a.k.a. chrome) */
-
-html {
-    scrollbar-color: var(--scrollbar) transparent;
-}
-#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));
-}
-
-html:not(.js) .sidebar-resize-handle {
-    display: none;
-}
-
-/* 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

@@ -1,408 +0,0 @@
-/* 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,83 +0,0 @@
-/*
- * 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)
- */
-
-/* Comment */
-.hljs-comment,
-.hljs-quote {
-  color: #575757;
-}
-
-/* Red */
-.hljs-variable,
-.hljs-template-variable,
-.hljs-attribute,
-.hljs-attr,
-.hljs-tag,
-.hljs-name,
-.hljs-regexp,
-.hljs-link,
-.hljs-name,
-.hljs-selector-id,
-.hljs-selector-class {
-  color: #d70025;
-}
-
-/* Orange */
-.hljs-number,
-.hljs-meta,
-.hljs-built_in,
-.hljs-builtin-name,
-.hljs-literal,
-.hljs-type,
-.hljs-params {
-  color: #b21e00;
-}
-
-/* Green */
-.hljs-string,
-.hljs-symbol,
-.hljs-bullet {
-  color: #008200;
-}
-
-/* Blue */
-.hljs-title,
-.hljs-section {
-  color: #0030f2;
-}
-
-/* Purple */
-.hljs-keyword,
-.hljs-selector-tag {
-  color: #9d00ec;
-}
-
-.hljs {
-  display: block;
-  overflow-x: auto;
-  background: #f6f7f6;
-  color: #000;
-}
-
-.hljs-emphasis {
-  font-style: italic;
-}
-
-.hljs-strong {
-  font-weight: bold;
-}
-
-.hljs-addition {
-  color: #22863a;
-  background-color: #f0fff4;
-}
-
-.hljs-deletion {
-  color: #b31d28;
-  background-color: #ffeef0;
-}

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

@@ -1,383 +0,0 @@
-
-/* 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

@@ -1,202 +0,0 @@
-
-                                 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

@@ -1,93 +0,0 @@
-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

@@ -1,100 +0,0 @@
-/* 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

@@ -1,22 +0,0 @@
-<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

@@ -1,843 +0,0 @@
-'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 });
-    })();
-})();