mdBook

https://rust-lang.github.io/mdBook
Admin
mdBook is a command-line tool designed to create easily navigable, customizable books and...
Tokens:20,713
Snippets:225
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### mdBook SUMMARY.md Full Example

Source: https://rust-lang.github.io/mdBook/print

Presents a comprehensive example of a SUMMARY.md file, demonstrating a typical book structure with sections like 'Introduction', 'User Guide', and 'Reference Guide', including nested chapters and cross-references.

```markdown
# Summary

[Introduction](README.md)

# User Guide

- [Installation](guide/installation.md)
- [Reading Books](guide/reading.md)
- [Creating a Book](guide/creating.md)

# Reference Guide

- [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)
    - [completions](cli/completions.md)
- [Format](format/README.md)
    - [SUMMARY.md](format/summary.md)
        - [Draft chapter]()
    - [Configuration](format/configuration/README.md)
        - [General](format/configuration/general.md)
        - [Preprocessors](format/configuration/preprocessors.md)
        - [Renderers](format/configuration/renderers.md)
        - [Environment Variables](format/configuration/environment-variables.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)
    - [Markdown](format/markdown.md)
- [Continuous Integration](continuous-integration.md)
- [For Developers](for_developers/README.md)
    - [Preprocessors](for_developers/preprocessors.md)
    - [Alternative Backends](for_developers/backends.md)

-----------

[Contributors](misc/contributors.md)
```

--------------------------------

### Install Custom mdBook Backend

Source: https://rust-lang.github.io/mdBook/for_developers/backends

This command installs the compiled custom mdBook backend locally. After running this, mdBook will be able to find and execute the backend when building a book.

```bash
cargo install --path .
```

--------------------------------

### Install Latest mdBook from Git using Cargo

Source: https://rust-lang.github.io/mdBook/guide/installation

Builds and installs the latest version of mdBook directly from its GitHub repository using Cargo. This method ensures you have the most up-to-date version, which might be slightly ahead of the crates.io release. Ensure the Cargo bin directory is in your PATH.

```rust
cargo install --git https://github.com/rust-lang/mdBook.git mdbook
```

--------------------------------

### Install mdBook using Cargo

Source: https://rust-lang.github.io/mdBook/guide/installation

Installs the mdBook CLI tool from crates.io using Cargo, Rust's package manager. This command downloads, builds, and installs mdBook into the Cargo global binary directory. It can be re-run to update mdBook.

```rust
cargo install mdbook
```

--------------------------------

### Rust Hello World Example

Source: https://rust-lang.github.io/mdBook/guide/reading

A basic 'Hello, World!' program in Rust, demonstrating a runnable code block. This snippet is intended to be displayed within an mdBook-generated HTML page.

```rust
#![allow(unused)]
fn main() {
println!("Hello, World!");
}

```

--------------------------------

### Install mdbook Custom Backend

Source: https://rust-lang.github.io/mdBook/print

This command installs a locally developed mdbook backend. After running this, the backend executable will be available in your system's PATH, allowing `mdbook` to discover and use it.

```bash
$ cargo install --path .
```

--------------------------------

### mdBook Shell Completions Installation

Source: https://rust-lang.github.io/mdBook/print

Provides instructions for generating and installing shell auto-completions for mdBook. Examples are given for bash and zsh (oh-my-zsh), directing users to consult their shell's documentation for specific placement.

```bash
# bash
mdbook completions bash > ~/.local/share/bash-completion/completions/mdbook
# oh-my-zsh
mdbook completions zsh > ~/.oh-my-zsh/completions/_mdbook
autoload -U compinit && compinit
```

--------------------------------

### Basic mdBook configuration (book.toml)

Source: https://rust-lang.github.io/mdBook/guide/creating

The `book.toml` file in the root of the book directory contains settings for building the book. This example shows a minimal configuration with a title for the book.

```toml
[book]
title = "My First Book"

```

--------------------------------

### Install mdBook from source using Cargo

Source: https://rust-lang.github.io/mdBook/continuous-integration

This command installs mdBook from source using Cargo, Rust's package manager. It includes recommended options like `--no-default-features` to disable unnecessary components for CI, `--features search` to enable search functionality, `--vers "^0.4"` to specify a version range, and `--locked` to ensure reproducible builds. This method requires Rust to be installed.

```rust
cargo install mdbook --no-default-features --features search --vers "^0.4" --locked
```

--------------------------------

### Rust Code Example

Source: https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting

Demonstrates a basic Rust function declaration, commonly used within mdBook for code examples. No external dependencies are required for this snippet.

```rust
fn main() {
    // Some code
}
```

--------------------------------

### Install mdBook using pre-compiled binaries with curl

Source: https://rust-lang.github.io/mdBook/continuous-integration

This snippet demonstrates how to download and extract pre-compiled mdBook binaries using `curl`. It's a quick method that doesn't require Rust installation and is suitable for environments where direct download is feasible. The output is placed in a 'bin' directory, and 'mdbook build' is then executed.

```shell
mkdir bin
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.52/mdbook-v0.4.52-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
bin/mdbook build
```

--------------------------------

### Configure mdBook Preprocessor

Source: https://rust-lang.github.io/mdBook/format/configuration/preprocessors

This configuration snippet shows how to add a custom preprocessor named 'example' to your mdBook project by defining a preprocessor table in book.toml. mdBook will attempt to run an executable named 'mdbook-example'.

```toml
[preprocessor.example]
```

--------------------------------

### Install mdBook CLI using Cargo

Source: https://rust-lang.github.io/mdBook/print

Installs the mdBook command-line tool from crates.io using Cargo. This command downloads, builds, and installs mdBook, and can be re-run to update to the latest version. It also provides the command for uninstallation.

```rust
cargo install mdbook

# To update:
# cargo install mdbook

# To uninstall:
# cargo uninstall mdbook
```

--------------------------------

### Test Rust code examples in mdBook

Source: https://rust-lang.github.io/mdBook/continuous-integration

This command runs tests for Rust code examples embedded within an mdBook project. It's crucial for validating the correctness of code snippets. This command requires Rust to be installed and should be executed from the book's directory.

```shell
mdbook test
```

--------------------------------

### Initialize mdBook Project and Skip Prompts

Source: https://rust-lang.github.io/mdBook/cli/init

This command initializes a new mdBook project and skips interactive prompts for the book's title and the creation of a .gitignore file. This is useful for automated setups.

```bash
mdbook init --ignore=none --title="my title"
```

--------------------------------

### Serve a local book preview

Source: https://rust-lang.github.io/mdBook/cli/serve

This command starts a local HTTP server to preview your mdBook. It watches for file changes and automatically rebuilds and refreshes the browser. Ensure you are in the book's directory or provide the path to it.

```bash
mdbook serve
```

--------------------------------

### Test Rust Code Examples in mdBook

Source: https://rust-lang.github.io/mdBook/cli/test

The mdBook 'test' command is used to run all runnable Rust code examples within a book. It supports specifying a custom book root directory and adding library paths for rustdoc testing.

```bash
mdbook test path/to/book
```

```bash
mdbook test my-book -L target/debug/deps/
```

--------------------------------

### Configure mdBook Backend with Options

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

This TOML configuration demonstrates how to specify custom options for a backend plugin, using 'wordcount' as an example. The `ignores` key is provided as an example of a backend-specific configuration option that mdBook will pass to the plugin.

```toml
[output.wordcount]
ignores = ["Example Chapter"]
```

--------------------------------

### mdBook SUMMARY.md Structure Examples

Source: https://rust-lang.github.io/mdBook/print

Illustrates various ways to structure a SUMMARY.md file in mdBook, including numbered chapters, nested sub-chapters, suffix chapters, draft chapters, and separators. These examples help define the table of contents and navigation for a book.

```markdown
# My Part Title

- [First Chapter](relative/path/to/markdown.md)

```

  4. _**Numbered Chapter**_ - Numbered chapters outline the main content of the book and can be nested, resulting in a nice hierarchy (chapters, sub-chapters, etc.).
```

__
# Title of Part

- [First Chapter](relative/path/to/markdown.md)
- [Second Chapter](relative/path/to/markdown2.md)
   - [Sub Chapter](relative/path/to/markdown3.md)

# Title of Another Part

- [Another Chapter](relative/path/to/markdown4.md)

```

Numbered chapters can be denoted with either `-` or `*` (do not mix delimiters).
  5. _**Suffix Chapter**_ - Like prefix chapters, suffix chapters are unnumbered, but they come after numbered chapters.
```

__
- [Last Chapter](relative/path/to/markdown.md)

[Title of Suffix Chapter](relative/path/to/markdown2.md)

```

  6. _**Draft chapters**_ - Draft chapters are chapters without a file and thus content. The purpose of a draft chapter is to signal future chapters still to be written. Or when still laying out the structure of the book to avoid creating the files while you are still changing the structure of the book a lot. Draft chapters will be rendered in the HTML renderer as disabled links in the table of contents, as you can see for the next chapter in the table of contents on the left. Draft chapters are written like normal chapters but without writing the path to the file.
```

__
- [Draft Chapter]()

```

  7. _**Separators**_ - Separators can be added before, in between, and after any other element. They result in an HTML rendered line in the built table of contents. A separator is a line containing exclusively dashes and at least three of them: `---`.
```

__
# My Part Title

[A Prefix Chapter](relative/path/to/markdown.md)

---

- [First Chapter](relative/path/to/markdown2.md)

```
```

--------------------------------

### Example mdBook chapter content

Source: https://rust-lang.github.io/mdBook/guide/creating

The content of each chapter is stored in separate Markdown files within the `src` directory. Each file typically starts with a level 1 heading representing the chapter title. The file layout affects the URL structure of the generated HTML.

```markdown
# My First Chapter

Fill out your content here.


```

--------------------------------

### Serve a book preview and open in browser

Source: https://rust-lang.github.io/mdBook/cli/serve

This command serves the mdBook preview and automatically opens the book in your default web browser once the server starts. Use the '-o' or '--open' flag for this functionality.

```bash
mdbook serve --open
```

--------------------------------

### mdBook SUMMARY.md Structure Example

Source: https://rust-lang.github.io/mdBook/format/summary

This markdown code demonstrates the expected structure for a SUMMARY.md file in mdBook. It includes examples of prefix chapters, part titles, numbered chapters (including nested sub-chapters), suffix chapters, draft chapters, and separators.

```markdown
# Summary

[Introduction](README.md)

# User Guide

- [Installation](guide/installation.md)
- [Reading Books](guide/reading.md)
- [Creating a Book](guide/creating.md)
```

--------------------------------

### Example mdBook summary file (SUMMARY.md)

Source: https://rust-lang.github.io/mdBook/guide/creating

The `src/SUMMARY.md` file lists all chapters in the book. It supports Markdown formatting for chapter titles and nesting for sub-chapters. Chapters must be added here to be included in the book.

```markdown
# Summary

[Introduction](README.md)

- [My First Chapter](my-first-chapter.md)
- [Nested example](nested/README.md)
    - [Sub-chapter](nested/sub-chapter.md)


```

--------------------------------

### Rust Example: No-op mdBook Preprocessor Implementation

Source: https://rust-lang.github.io/mdBook/for_developers/preprocessors

This Rust code provides a functional example of a no-operation (no-op) mdBook preprocessor. It defines the command-line interface for supporting renderers and processing book content, adhering to the mdBook preprocessor trait. It includes logic for checking mdBook version compatibility and handling potential configuration options like 'blow-up'.

```rust
use crate::nop_lib::Nop;
use clap::{Arg, ArgMatches, Command};
use mdbook::book::Book;
use mdbook::errors::Error;
use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext};
use semver::{Version, VersionReq};
use std::io;
use std::process;

pub fn make_app() -> Command {
    Command::new("nop-preprocessor")
        .about("A mdbook preprocessor which does precisely nothing")
        .subcommand(
            Command::new("supports")
                .arg(Arg::new("renderer").required(true))
                .about("Check whether a renderer is supported by this preprocessor"),
        )
}

fn main() {
    let matches = make_app().get_matches();

    // Users will want to construct their own preprocessor here
    let preprocessor = Nop::new();

    if let Some(sub_args) = matches.subcommand_matches("supports") {
        handle_supports(&preprocessor, sub_args);
    } else if let Err(e) = handle_preprocessing(&preprocessor) {
        eprintln!("{e:?}");
        process::exit(1);
    }
}

fn handle_preprocessing(pre: &dyn Preprocessor) -> Result<(), Error> {
    let (ctx, book) = CmdPreprocessor::parse_input(io::stdin())?;

    let book_version = Version::parse(&ctx.mdbook_version)?;
    let version_req = VersionReq::parse(mdbook::MDBOOK_VERSION)?;

    if !version_req.matches(&book_version) {
        eprintln!(
            "Warning: The {} plugin was built against version {} of mdbook, \ \
             but we're being called from version {}",
            pre.name(),
            mdbook::MDBOOK_VERSION,
            ctx.mdbook_version
        );
    }

    let processed_book = pre.run(&ctx, book)?;
    serde_json::to_writer(io::stdout(), &processed_book)?;

    Ok(())
}

fn handle_supports(pre: &dyn Preprocessor, sub_args: &ArgMatches) -> ! {
    let renderer = sub_args
        .get_one::<String>("renderer")
        .expect("Required argument");
    let supported = pre.supports_renderer(renderer);

    // Signal whether the renderer is supported by exiting with 1 or 0.
    if supported {
        process::exit(0);
    } else {
        process::exit(1);
    }
}

/// The actual implementation of the `Nop` preprocessor. This would usually go
/// in your main `lib.rs` file.
mod nop_lib {
    use super::*;

    /// A no-op preprocessor.
    pub struct Nop;

    impl Nop {
        pub fn new() -> Nop {
            Nop
        }
    }

    impl Preprocessor for Nop {
        fn name(&self) -> &str {
            "nop-preprocessor"
        }

        fn run(&self, ctx: &PreprocessorContext, book: Book) -> Result<Book, Error> {
            // In testing we want to tell the preprocessor to blow up by setting a
            // particular config value
            if let Some(nop_cfg) = ctx.config.get_preprocessor(self.name()) {
                if nop_cfg.contains_key("blow-up") {
                    anyhow::bail!("Boom!!1!");
                }
            }

            // we *are* a no-op preprocessor after all
            Ok(book)
        }

        fn supports_renderer(&self, renderer: &str) -> bool {
            renderer != "not-supported"
        }
    }

    #[cfg(test)]
    mod test {
        use super::*;

        #[test]
        fn nop_preprocessor_run() {
            let input_json = r##"[
                {
                    "root": "/path/to/book",
                    "config": {

```

--------------------------------

### mdBook Rust Edition Specific Code Example

Source: https://rust-lang.github.io/mdBook/format/configuration/general

Demonstrates how to specify a particular Rust edition for individual code blocks in mdBook. This allows for showcasing features from different Rust editions.

```rust
// This only works in 2015.
let try = true;

```

--------------------------------

### Create New Binary Project with mdbook Dependency

Source: https://rust-lang.github.io/mdBook/print

This snippet shows the commands to create a new Rust binary project using Cargo and add `mdbook` as a dependency. This is the initial setup for creating a custom mdbook backend.

```bash
$ cargo new --bin mdbook-wordcount
$ cd mdbook-wordcount
$ cargo add mdbook
```

--------------------------------

### Mark Renderer Backend as Optional

Source: https://rust-lang.github.io/mdBook/print

Marks a renderer backend as optional, changing the default error behavior to a warning if the backend is not installed. This is useful for non-critical output formats.

```toml
[output.wordcount]
optional = true

```

--------------------------------

### Show Hidden Lines in Python Code Blocks

Source: https://rust-lang.github.io/mdBook/format/mdbook

When a custom prefix (e.g., '~' for Python) is configured, lines starting with that prefix are hidden. This example demonstrates how Python code with '~hidden()' lines renders.

```python
~hidden()
nothidden():
    ~hidden()
    ~hidden()
    nothidden()

```

--------------------------------

### Configure Custom Line Hiding Prefixes

Source: https://rust-lang.github.io/mdBook/format/mdbook

You can configure custom line-hiding prefixes for languages other than Rust in your book.toml file. For example, setting 'python = "~"' will hide lines starting with '~' in Python code blocks.

```toml
[output.html.code.hidelines]
python = "~"

```

--------------------------------

### Specify Renderer for Preprocessor

Source: https://rust-lang.github.io/mdBook/format/configuration/preprocessors

This TOML configuration shows how to explicitly define which renderer a preprocessor should be active for. In this case, the 'example' preprocessor is configured to only run when the 'html' renderer is used.

```toml
[preprocessor.example]
renderers = ["html"]
```

--------------------------------

### Mark mdBook Backend as Optional

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

This TOML configuration shows how to mark a backend plugin as optional using `optional = true`. If the 'wordcount' backend is not found or installed, mdBook will issue a warning instead of a critical error, allowing the build to continue.

```toml
[output.wordcount]
optional = true
```

--------------------------------

### Control Preprocessor Execution Order

Source: https://rust-lang.github.io/mdBook/print

Specifies the execution order of preprocessors using `before` and `after` fields. This ensures that preprocessors run in the desired sequence, for example, running after the built-in `links` preprocessor. Preprocessors with the same priority are sorted by name.

```toml
[preprocessor.linenos]
after = [ "links" ]

```

```toml
[preprocessor.links]
before = [ "linenos" ]

```

--------------------------------

### Configure Rust Edition for Code Blocks in mdBook

Source: https://rust-lang.github.io/mdBook/format/configuration/general

Sets the default Rust edition for code snippets within an mdBook. This configuration ensures consistent compilation for code examples across the book.

```toml
[rust]
edition = "2015"   # the default edition for code blocks

```

--------------------------------

### Configure Hidden Lines in Code Blocks

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

Defines prefixes that, when present at the start of a line (preceded by whitespace), will hide that line in the rendered code blocks. This is specified per language.

```toml
__
[output.html.code]
# A prefix string per language (one or more chars).
# Any line starting with whitespace+prefix is hidden.
hidelines = { python = "~" }

```

--------------------------------

### Include Sections Using Anchors in mdBook

Source: https://rust-lang.github.io/mdBook/format/mdbook

Shows how to include specific sections of a file defined by anchors (start and end markers). This method is more robust to file changes than using line numbers.

```mdbook
/* ANCHOR: all */

// ANCHOR: component
struct Paddle {
    hello: f32,
}
// ANCHOR_END: component

////////// ANCHOR: system
impl System for MySystem { ... }
////////// ANCHOR_END: system

/* ANCHOR_END: all */
```

```mdbook
Here is a component:
```rust,no_run,noplayground
{{#include file.rs:component}}
```

Here is a system:
```rust,no_run,noplayground
{{#include file.rs:system}}
```

This is the full file.
```rust,no_run,noplayground
{{#include file.rs:all}}
```
```

--------------------------------

### Override Configuration with Environment Variables (Shell)

Source: https://rust-lang.github.io/mdBook/print

This example demonstrates how to override mdBook configuration values using environment variables. The `MDBOOK_` prefix is used, with double underscores (`__`) separating nested keys and single underscores replaced by dashes. Values are parsed as JSON, falling back to strings if parsing fails.

```shell
> __
> $ export MDBOOK_BOOK='{"title": "My Awesome Book", "authors": ["Michael-F-Bryan"]}'
$ mdbook build
```

--------------------------------

### Serve an mdBook Project Locally

Source: https://rust-lang.github.io/mdBook/print

Illustrates how to build and serve an mdBook project locally using the `serve` command. The `--open` flag automatically opens the book in the default web browser.

```bash
mdbook serve --open

```

--------------------------------

### Mark Rust Code Block as Editable

Source: https://rust-lang.github.io/mdBook/format/theme/editor

This example demonstrates how to make a specific Rust code block editable by adding the `editable` attribute. This will render an interactive playground in the generated HTML, allowing users to modify and run the code. It assumes editable playgrounds are enabled in `book.toml`.

```rust
```rust,editable
fn main() {
    let number = 5;
    print!("{}", number);
}
```
```

--------------------------------

### Hide Python Code Lines with Custom Prefix

Source: https://rust-lang.github.io/mdBook/print

Demonstrates hiding lines in Python code blocks using a custom prefix configured in `book.toml`. Lines starting with the specified prefix are hidden.

```python
~hidden()
nothidden():
~    hidden()
    ~hidden()
    nothidden()

```

--------------------------------

### Initialize an mdBook Project

Source: https://rust-lang.github.io/mdBook/print

Shows the command to initialize a new mdBook project. This command creates a new directory with the specified name and sets up the basic structure for a book.

```bash
mdbook init my-first-book

```

--------------------------------

### Initialize a New mdBook Project

Source: https://rust-lang.github.io/mdBook/cli/init

This command initializes a new mdBook project in the current directory. It sets up the basic file structure for a new book, including the 'src' and 'book' directories and essential markdown files.

```bash
mdbook init
```

--------------------------------

### Serve Book Locally with mdbook serve

Source: https://rust-lang.github.io/mdBook/print

The `serve` command previews your book by hosting it on a local HTTP server. It watches for changes, rebuilds, and refreshes clients. You can specify the root directory, hostname, and port. The `--open` flag automatically opens the book in your default browser.

```shell
mdbook serve
mdbook serve path/to/book
mdbook serve path/to/book -p 8000 -n 127.0.0.1
mdbook serve -o path/to/book
```

--------------------------------

### Floating Images with CSS Classes in mdBook

Source: https://rust-lang.github.io/mdBook/print

Provides examples of using CSS classes for inline HTML elements in mdBook, specifically for floating images. The `right` class is used to position an image to the right, allowing text to wrap around it.

```HTML
<img class="right" src="images/rust-logo-blk.svg" alt="The Rust logo">
```

--------------------------------

### Initialize a new mdBook project

Source: https://rust-lang.github.io/mdBook/guide/creating

The `mdbook init` command creates a new directory with an empty book structure. You provide the name of the directory to be created. The command will then ask a few questions to configure the new book.

```bash
mdbook init my-first-book
```

--------------------------------

### mdbook init - Create a New Book

Source: https://rust-lang.github.io/mdBook/print

Initializes a new mdBook project with a basic structure. It creates necessary files like SUMMARY.md and a src directory for markdown content. This command can be customized with options for title, gitignore, and theme.

```bash
mdbook init
```

```bash
mdbook init path/to/book
```

```bash
mdbook init --title="my amazing book"
```

```bash
mdbook init --ignore=none
```

```bash
mdbook init --ignore=git
```

--------------------------------

### Create New Binary Project and Add mdBook Dependency

Source: https://rust-lang.github.io/mdBook/for_developers/backends

This snippet demonstrates the initial steps to create a new Rust binary project for an mdBook backend and adds the 'mdbook' crate as a dependency. This is essential for interacting with mdBook's rendering context.

```bash
cargo new --bin mdbook-wordcount
cd mdbook-wordcount
cargo add mdbook
```

--------------------------------

### Navigate to the new book directory

Source: https://rust-lang.github.io/mdBook/guide/creating

After initializing a new mdBook project, you need to change your current directory to the newly created book directory to perform further operations like serving or building.

```bash
cd my-first-book
```

--------------------------------

### Initialize mdBook Project in a Specific Directory

Source: https://rust-lang.github.io/mdBook/cli/init

This command initializes a new mdBook project in a specified directory, using that directory as the book's root instead of the current working directory.

```bash
mdbook init path/to/book
```

--------------------------------

### Initialize mdBook Project with a Specific Title

Source: https://rust-lang.github.io/mdBook/cli/init

This command initializes a new mdBook project and sets a specific title for the book. If the --title flag is not provided, the user will be interactively prompted for a title.

```bash
mdbook init --title="my amazing book"
```

--------------------------------

### Enable a Custom Preprocessor in book.toml

Source: https://rust-lang.github.io/mdBook/print

Adds a custom preprocessor, such as `mdbook-example`, to the build process. This allows for extending Markdown processing with custom logic. Additional key-value pairs can be included for preprocessor-specific configuration.

```toml
[preprocessor.example]


```

```toml
[preprocessor.example]
some-extra-feature = true

```

--------------------------------

### Serve a book preview from a specific directory

Source: https://rust-lang.github.io/mdBook/cli/serve

This command serves an mdBook preview from a directory other than the current working directory. Replace 'path/to/book' with the actual path to your book's root directory.

```bash
mdbook serve path/to/book
```

--------------------------------

### Serve a book preview with a custom output directory

Source: https://rust-lang.github.io/mdBook/cli/serve

This command allows you to specify a different directory for the built HTML output using the '--dest-dir' or '-d' flag. Relative paths are relative to the book's root. If not specified, it defaults to 'build.build-dir' in book.toml or './book'.

```bash
mdbook serve -d custom_output_dir
```

--------------------------------

### mdbook help - View Commands

Source: https://rust-lang.github.io/mdBook/print

Displays a list of all available commands for the mdBook tool. This command is useful for new users to understand the full range of functionality provided by mdBook.

```bash
mdbook help
```

--------------------------------

### Build mdBook project for deployment

Source: https://rust-lang.github.io/mdBook/guide/creating

The `mdbook build` command generates the static HTML content of the book. The output is placed in a directory named `book`, which can then be deployed to any web server.

```bash
mdbook build

```

--------------------------------

### Configure book.toml to Use HTML and Custom Backend

Source: https://rust-lang.github.io/mdBook/for_developers/backends

This snippet shows how to modify the `book.toml` file to enable both the default HTML output and the custom 'wordcount' backend. It demonstrates adding output sections for each renderer.

```toml
[book]
title = "mdBook Documentation"
description = "Create book from markdown files. Like Gitbook but implemented in Rust"
authors = ["Mathieu David", "Michael-F-Bryan"]

[output.html]

[output.wordcount]
```

--------------------------------

### Build mdBook and Open in Browser

Source: https://rust-lang.github.io/mdBook/cli/build

Renders your mdBook project and automatically opens the built book in the default web browser upon completion.

```shell
mdbook build --open
```

--------------------------------

### Build mdBook

Source: https://rust-lang.github.io/mdBook/cli/build

Renders your mdBook project. It parses SUMMARY.md to understand book structure and fetches corresponding files, creating missing ones. Output maintains source directory structure.

```shell
mdbook build
```

--------------------------------

### Serve a book preview with custom hostname and port

Source: https://rust-lang.github.io/mdBook/cli/serve

This command allows you to specify a custom hostname and port for the mdBook preview server. '-p 8000' sets the port to 8000, and '-n 127.0.0.1' sets the hostname to localhost. Adjust these values as needed.

```bash
mdbook serve path/to/book -p 8000 -n 127.0.0.1
```

--------------------------------

### mdbook build - Render Book

Source: https://rust-lang.github.io/mdBook/print

Renders the mdBook project into static HTML files. The command parses the SUMMARY.md file to determine the book's structure and creates a 'book' directory containing the output. It supports specifying a custom root directory and automatically opening the rendered book in a browser.

```bash
mdbook build
```

```bash
mdbook build path/to/book
```

```bash
mdbook build --open
```

```bash
mdbook build -o
```

--------------------------------

### Add Custom HTML ID and Classes to Heading in Markdown

Source: https://rust-lang.github.io/mdBook/format/markdown

This example demonstrates how to add a custom HTML ID and multiple classes to a Markdown heading. The ID and classes are specified in curly braces after the heading text, separated by spaces. This allows for precise control over the heading's attributes in the generated HTML.

```markdown
# Example heading { #first .class1 .class2 }
```

--------------------------------

### Specify Custom Backend Command in book.toml

Source: https://rust-lang.github.io/mdBook/for_developers/backends

This configuration in `book.toml` explicitly defines the command to execute for the 'wordcount' backend, allowing for custom execution paths or arguments. This is useful if the backend is not a directly executable binary or requires specific invocation details.

```toml
[book]
title = "mdBook Documentation"
description = "Create book from markdown files. Like Gitbook but implemented in Rust"
authors = ["Mathieu David", "Michael-F-Bryan"]

[output.html]

[output.wordcount]
command = "python /path/to/wordcount.py"
```

--------------------------------

### Enable Custom Renderer Backend

Source: https://rust-lang.github.io/mdBook/print

Includes a custom renderer backend by adding an `output` table to `book.toml`. mdBook will execute the specified backend (e.g., `mdbook-wordcount`). Additional key-value pairs can be passed as configuration options specific to the backend.

```toml
[output.wordcount]

```

```toml
[output.wordcount]
ignores = ["Example Chapter"]

```

--------------------------------

### Load RenderContext from JSON Input in Rust Backend

Source: https://rust-lang.github.io/mdBook/for_developers/backends

This Rust code snippet shows how to initialize the `RenderContext` by reading JSON data from standard input. This context contains book and configuration information necessary for the backend's operation. It uses the `mdbook` crate's `RenderContext::from_json()` method.

```rust
extern crate mdbook;

use std::io;
use mdbook::renderer::RenderContext;

fn main() {
    let mut stdin = io::stdin();
    let ctx = RenderContext::from_json(&mut stdin).unwrap();
}
```

--------------------------------

### mdBook Build Configuration Options

Source: https://rust-lang.github.io/mdBook/cli/test

mdBook provides command-line options to customize the build process. The '--dest-dir' option sets the output directory, defaulting to 'book.toml' configuration or './book'. The '--chapter' option allows testing specific chapters.

```bash
# Example for setting destination directory
mdbook build --dest-dir my-output-folder

# Example for testing a specific chapter
mdbook test --chapter chapter-name
```

--------------------------------

### Configure mdBook Build Process Settings

Source: https://rust-lang.github.io/mdBook/format/configuration/general

Controls the build output and behavior of an mdBook project. Options include specifying the output directory, managing missing files, and enabling default preprocessors.

```toml
[build]
build-dir = "book"                # the directory where the output is placed
create-missing = true             # whether or not to create missing pages
use-default-preprocessors = true  # use the default preprocessors
extra-watch-dirs = []             # directories to watch for triggering builds

```

--------------------------------

### Build mdBook with Custom Output Directory

Source: https://rust-lang.github.io/mdBook/cli/build

Renders your mdBook project to a specified output directory. Relative paths are relative to the book's root. Defaults to 'build.build-dir' in book.toml or './book'.

```shell
mdbook build --dest-dir path/to/output
```

--------------------------------

### Enable Multiple Renderers Including HTML

Source: https://rust-lang.github.io/mdBook/print

Includes multiple renderer backends, including the default HTML renderer, in the `book.toml` configuration. If multiple `[output]` tables are defined, the output is organized into separate directories for each backend.

```toml
[book]
title = "My Awesome Book"

[output.wordcount]

[output.html]

```

--------------------------------

### mdBook TOML Configuration for HTML Output

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

This TOML snippet demonstrates how to configure various HTML output options for an mdBook project. It includes settings for themes, navigation, and external resource integration.

```toml
[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."

[output.html]
theme = "my-theme"
default-theme = "light"
preferred-dark-theme = "navy"
smart-punctuation = true
mathjax-support = false
copy-fonts = true
additional-css = ["custom.css", "custom2.css"]
additional-js = ["custom.js"]
no-section-label = false
git-repository-url = "https://github.com/rust-lang/mdBook"
git-repository-icon = "fa-github"
edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
site-url = "/example-book/"
cname = "myproject.rs"
input-404 = "not-found.md"
```

--------------------------------

### Initialize mdBook Project Ignoring .gitignore Creation

Source: https://rust-lang.github.io/mdBook/cli/init

This command initializes a new mdBook project and explicitly controls the creation of a .gitignore file. '--ignore=none' prevents the creation of a .gitignore file, while '--ignore=git' ensures a gitignore file is created to ignore the 'book' directory.

```bash
mdbook init --ignore=none
```

```bash
mdbook init --ignore=git
```

--------------------------------

### Configure mdBook Project Settings

Source: https://rust-lang.github.io/mdBook/format/configuration/general

Defines the fundamental settings for an mdBook project, including the book's title, authors, and a brief description. These settings are crucial for metadata and presentation.

```toml
[book]
title = "Example book"
authors = ["John Doe"]
description = "The example book covers examples."

[rust]
edition = "2018"

[build]
build-dir = "my-example-book"
create-missing = false

[preprocessor.index]

[preprocessor.links]

[output.html]
additional-css = ["custom.css"]

[output.html.search]
limit-results = 15

```

--------------------------------

### Configure mdBook `site-url` for 404 Page

Source: https://rust-lang.github.io/mdBook/continuous-integration

This configuration snippet shows how to set the `site-url` in the `book.toml` file. This is essential for the 404 page to correctly load static assets like CSS when the book is not deployed at the root of a domain. It specifies the base path for the deployed website.

```toml
[output.html]
site-url = "/mdBook/"

```

--------------------------------

### Configure mdBook Backend Plugin

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

This configuration snippet shows how to add a custom backend plugin named 'wordcount' to your mdBook project by defining an `[output.wordcount]` table in `book.toml`. This enables mdBook to invoke the specified backend during the build process.

```toml
[output.wordcount]
```

--------------------------------

### Enable Multiple mdBook Backends

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

This TOML configuration shows how to enable both a custom backend ('wordcount') and the default 'html' backend. When multiple backends are defined, mdBook organizes their output into separate subdirectories within the build directory.

```toml
[book]
title = "My Awesome Book"

[output.wordcount]

[output.html]
```

--------------------------------

### MDBook Preprocessor CLI and Support Check (Rust)

Source: https://rust-lang.github.io/mdBook/print

This Rust code defines the command-line interface for an MDBook preprocessor. It handles checking renderer support and executing the preprocessing logic. It requires `clap` for argument parsing and `mdbook` for preprocessing types.

```rust
use crate::nop_lib::Nop;
use clap::{Arg, ArgMatches, Command};
use mdbook::book::Book;
use mdbook::errors::Error;
use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext};
use semver::{Version, VersionReq};
use std::io;
use std::process;

pub fn make_app() -> Command {
    Command::new("nop-preprocessor")
        .about("A mdbook preprocessor which does precisely nothing")
        .subcommand(
            Command::new("supports")
                .arg(Arg::new("renderer").required(true))
                .about("Check whether a renderer is supported by this preprocessor"),
        )
}

fn main() {
    let matches = make_app().get_matches();

    // Users will want to construct their own preprocessor here
    let preprocessor = Nop::new();

    if let Some(sub_args) = matches.subcommand_matches("supports") {
        handle_supports(&preprocessor, sub_args);
    } else if let Err(e) = handle_preprocessing(&preprocessor) {
        eprintln!("{e:?}");
        process::exit(1);
    }
}

fn handle_preprocessing(pre: &dyn Preprocessor) -> Result<(), Error> {
    let (ctx, book) = CmdPreprocessor::parse_input(io::stdin())?;

    let book_version = Version::parse(&ctx.mdbook_version)?;
    let version_req = VersionReq::parse(mdbook::MDBOOK_VERSION)?;

    if !version_req.matches(&book_version) {
        eprintln!(
            "Warning: The {} plugin was built against version {} of mdbook, \             but we're being called from version {}",
            pre.name(),
            mdbook::MDBOOK_VERSION,
            ctx.mdbook_version
        );
    }

    let processed_book = pre.run(&ctx, book)?;
    serde_json::to_writer(io::stdout(), &processed_book)?;

    Ok(())
}

fn handle_supports(pre: &dyn Preprocessor, sub_args: &ArgMatches) -> ! {
    let renderer = sub_args
        .get_one::<String>("renderer")
        .expect("Required argument");
    let supported = pre.supports_renderer(renderer);

    // Signal whether the renderer is supported by exiting with 1 or 0.
    if supported {
        process::exit(0);
    } else {
        process::exit(1);
    }
}

```

--------------------------------

### Add serde dependencies using cargo

Source: https://rust-lang.github.io/mdBook/for_developers/backends

Adds the `serde` and `serde_derive` crates as dependencies to a Rust project using cargo. These crates are essential for serializing and deserializing data structures, which is required for handling configuration files.

```bash
$ cargo add serde serde_derive
```

--------------------------------

### Build mdBook with Custom Root Directory

Source: https://rust-lang.github.io/mdBook/cli/build

Renders your mdBook project using a specified directory as the book's root instead of the current working directory.

```shell
mdbook build path/to/book
```

--------------------------------

### Configure Rust Code Blocks and Playground Integration

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

Options for enhancing code blocks, including enabling editing, copying, line numbers, and running code directly in the Rust Playground. Requires specific settings for JavaScript dependencies.

```toml
__
[output.html.playground]
editable = false         # allows editing the source code
copyable = true          # include the copy button for copying code snippets
copy-js = true           # includes the JavaScript for the code editor
line-numbers = false     # displays line numbers for editable code
runnable = true          # displays a run button for rust code

```

--------------------------------

### Configure mdBook with Source and Language Options

Source: https://rust-lang.github.io/mdBook/format/configuration/general

Specifies advanced configuration for an mdBook project, including custom source directory, book language, and text direction. These options affect content organization and accessibility.

```toml
[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
src = "my-src"  # the source files will be found in `root/my-src` instead of `root/src`
language = "en"
text-direction = "ltr"

```

--------------------------------

### Task List Syntax in mdBook

Source: https://rust-lang.github.io/mdBook/format/markdown

Demonstrates the mdBook extension for creating task lists, using list items with `[x]` for completed tasks and `[ ]` for incomplete tasks.

```markdown
__
- [x] Complete task
- [ ] Incomplete task

```
```

--------------------------------

### Handlebars 'resource' Helper for Static Files

Source: https://rust-lang.github.io/mdBook/format/theme/index-hbs

The 'resource' helper in mdBook's Handlebars templates generates the correct path to static files. It automatically includes 'path_to_root' and handles filename hashing for cache busting.

```HTML
<link rel="stylesheet" href="{{ resource "css/chrome.css" }}">
```

--------------------------------

### Enable Markdown Renderer in mdBook

Source: https://rust-lang.github.io/mdBook/format/configuration/renderers

Activates the Markdown renderer in mdBook, which runs preprocessors before outputting the resulting Markdown. This is useful for debugging preprocessors and is enabled by adding an empty table to `book.toml` under `[output.markdown]`.

```toml
__
[output.markdown]

```

--------------------------------

### Enable Editable Playgrounds in mdBook

Source: https://rust-lang.github.io/mdBook/format/theme/editor

This configuration enables editable code blocks within the HTML output of an mdBook project. It requires adding a specific section to the `book.toml` file. No external dependencies are needed beyond mdBook itself.

```toml
[output.html.playground]
editable = true
```

--------------------------------

### Configure Custom Renderer Command

Source: https://rust-lang.github.io/mdBook/print

Defines a custom command to be executed for a renderer backend. This allows specifying an alternative executable name or passing command-line arguments. The `command` field overrides the default behavior of invoking `mdbook-backend-name`.

```toml
[output.random]
command = "python random.py"

```

--------------------------------

### URL and Local File Linking in mdBook

Source: https://rust-lang.github.io/mdBook/print

mdBook facilitates linking to external URLs, local files (including Markdown files which are automatically converted to HTML), and internal page anchors. Bare URLs are also supported. Links to `.md` files are recommended for cross-platform compatibility.

```markdown
Use [mdBook](https://github.com/rust-lang/mdBook). 

Read about [mdBook](mdbook.md).

And now [an mdBook link] that is not inline, unlike the above.

A bare url: <https://www.rust-lang.org>.

[an mdBook link]: https://github.com/rust-lang/mdBook
```

--------------------------------

### mdBook Clean Command Usage

Source: https://rust-lang.github.io/mdBook/print

Shows how to use the `mdbook clean` command to delete generated book files and build artifacts. It illustrates specifying a book root directory and overriding the output directory with `--dest-dir`.

```bash
mdbook clean
```

```bash
mdbook clean path/to/book
```

```bash
mdbook clean --dest-dir=path/to/book
```

--------------------------------

### Generate Zsh Shell Completions for mdBook (Oh My Zsh)

Source: https://rust-lang.github.io/mdBook/cli/completions

This command generates shell completion scripts for the 'mdbook' command in zsh, specifically for use with Oh My Zsh. The output is redirected to the Oh My Zsh completions directory. After placing the file, 'autoload -U compinit && compinit' is typically run to load the new completions.

```zsh
mdbook completions zsh > ~/.oh-my-zsh/completions/_mdbook
autoload -U compinit && compinit
```

--------------------------------

### Table Formatting in mdBook

Source: https://rust-lang.github.io/mdBook/print

mdBook supports table creation using pipes (|) and dashes (-) to define columns and rows, translating directly into HTML tables. This follows the GitHub Tables extension specification.

```markdown
| Header1 | Header2 |
|---------|---------|
| abc     | def     |
```

--------------------------------

### Configure Preprocessor with Extra Options

Source: https://rust-lang.github.io/mdBook/format/configuration/preprocessors

This TOML configuration demonstrates how to include additional key-value pairs within a preprocessor table for custom preprocessors. These options can be used to provide specific settings to your preprocessor, such as enabling a feature.

```toml
[preprocessor.example]
some-extra-feature = true
```

--------------------------------

### Configure mdBook HTML Output Site URL

Source: https://rust-lang.github.io/mdBook/print

This configuration sets the base URL for the HTML output of an mdBook project. It's crucial for ensuring that static assets and the 404 page load correctly when the book is deployed to a non-root path on a domain. This setting is defined in the `book.toml` file under the `[output.html]` section.

```toml
# book.toml
[output.html]
site-url = "/mdBook/"
```
Tokens:
Raw