mdBook-specific features - mdBook Documentation
Description: Create book from markdown files. Like Gitbook but implemented in Rust

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# mdBook-specific features

## Hiding code lines

There is a feature in mdBook that lets you hide code lines by prepending them with a specific prefix.

For the Rust language, you can prefix lines with `#` (`#` followed by a space) to hide them like you would with Rustdoc. This prefix can be escaped with `##` to prevent the hiding of a line that should begin with the literal string `#` (see Rustdoc’s docs for more details)

    # fn main() {
        let x = 5;
        let y = 6;

        println!("{}", x + y);
    # }

Will render as

    fn main() {
        let x = 5;
        let y = 6;

        println!("{}", x + y);
    }

When you tap or hover the mouse over the code block, there will be an eyeball icon (
) which will toggle the visibility of the hidden lines.

By default, this only works for code examples that are annotated with `rust`. However, you can define custom prefixes for other languages by adding a new line-hiding prefix in your `book.toml` with the language name and prefix character(s):

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

The prefix will hide any lines that begin with the given prefix. With the python prefix shown above, this:

    ~hidden()
    nothidden():
    ~    hidden()
        ~hidden()
        nothidden()

will render as

    hidden()
    nothidden():
        hidden()
        hidden()
        nothidden()

This behavior can be overridden locally with a different prefix. This has the same effect as above:

    ```python,hidelines=!!!
    !!!hidden()
    nothidden():
    !!!    hidden()
        !!!hidden()
        nothidden()
    ```

## Rust playground

Rust language code blocks will automatically get a play button (
) which will execute the code and display the output just below the code block. This works by sending the code to the Rust Playground.

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

If there is no `main` function, then the code is automatically wrapped inside one.

If you wish to disable the play button for a code block, you can include the `noplayground` option on the code block like this:

    ```rust,noplayground
    let mut name = String::new();
    std::io::stdin().read_line(&mut name).expect("failed to read line");
    println!("Hello {}!", name);
    ```

Or, if you wish to disable the play button for all code blocks in your book, you can write the config to the `book.toml` like this.

    [output.html.playground]
    runnable = false

## Rust code block attributes

Additional attributes can be included in Rust code blocks with comma, space, or tab-separated terms just after the language term. For example:

    ```rust,ignore
    # This example won't be tested.
    panic!("oops!");
    ```

These are particularly important when using `mdbook test` to test Rust examples. These use the same attributes as rustdoc attributes, with a few additions:

- `editable` — Enables the editor.
- `noplayground` — Removes the play button, but will still be tested.
- `mdbook-runnable` — Forces the play button to be displayed. This is intended to be combined with the `ignore` attribute for examples that should not be tested, but you want to allow the reader to run.
- `ignore` — Will not be tested and no play button is shown, but it is still highlighted as Rust syntax.
- `should_panic` — When executed, it should produce a panic.
- `no_run` — The code is compiled when tested, but it is not run. The play button is also not shown.
- `compile_fail` — The code should fail to compile.
- `edition2015`, `edition2018`, `edition2021`, `edition2024` — Forces the use of a specific Rust edition. See `rust.edition` to set this globally.

## Including files

With the following syntax, you can include files into your book:

    {{#include file.rs}}

The path to the file has to be relative from the current source file.

mdBook will interpret included files as Markdown. Since the include command is usually used for inserting code snippets and examples, you will often wrap the command with ````` to display the file contents without interpreting them.

    ```
    {{#include file.rs}}
    ```

## Including portions of a file

Often you only need a specific part of the file, e.g. relevant lines for an example. We support four different modes of partial includes:

    {{#include file.rs:2}}
    {{#include file.rs::10}}
    {{#include file.rs:2:}}
    {{#include file.rs:2:10}}

The first command only includes the second line from file `file.rs`. The second command includes all lines up to line 10, i.e. the lines from 11 till the end of the file are omitted. The third command includes all lines from line 2, i.e. the first line is omitted. The last command includes the excerpt of `file.rs` consisting of lines 2 to 10.

To avoid breaking your book when modifying included files, you can also include a specific section using anchors instead of line numbers. An anchor is a pair of matching lines. The line beginning an anchor must match the regex `ANCHOR:\s*[\w_-]+` and similarly the ending line must match the regex `ANCHOR_END:\s*[\w_-]+`. This allows you to put anchors in any kind of commented line.

Consider the following file to include:

    /* ANCHOR: all */

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

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

    /* ANCHOR_END: all */

Then in the book, all you have to do is:

    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}}
    ```

Lines containing anchor patterns inside the included anchor are ignored.

## Including a file but initially hiding all except specified lines

The `rustdoc_include` helper is for including code from external Rust files that contain complete examples, but only initially showing particular lines specified with line numbers or anchors in the same way as with `include`.

The lines not in the line number range or between the anchors will still be included, but they will be prefaced with `#`. This way, a reader can expand the snippet to see the complete example, and Rustdoc will use the complete example when you run `mdbook test`.

For example, consider a file named `file.rs` that contains this Rust program:

    fn main() {
        let x = add_one(2);
        assert_eq!(x, 3);
    }

    fn add_one(num: i32) -> i32 {
        num + 1
    }

We can include a snippet that initially shows only line 2 by using this syntax:

    To call the `add_one` function, we pass it an `i32` and bind the returned value to `x`:

    ```rust
    {{#rustdoc_include file.rs:2}}
    ```

This would have the same effect as if we had manually inserted the code and hidden all but line 2 using `#`:

    To call the `add_one` function, we pass it an `i32` and bind the returned value to `x`:

    ```rust
    # fn main() {
        let x = add_one(2);
    #     assert_eq!(x, 3);
    # }
    #
    # fn add_one(num: i32) -> i32 {
    #     num + 1
    # }
    ```

That is, it looks like this (click the “expand” icon to see the rest of the file):

    fn main() {
        let x = add_one(2);
        assert_eq!(x, 3);
    }

    fn add_one(num: i32) -> i32 {
        num + 1
    }

## Inserting runnable Rust files

With the following syntax, you can insert runnable Rust files into your book:

    {{#playground 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 Playground 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:

    fn main() {
        println!("Hello World!");

        // You can even hide lines! :D
        println!("I am hidden! Expand the code snippet to see me");
    }

Any additional values passed after the filename will be included as attributes of the code block. For example `{{#playground example.rs editable}}` will create the code block like the following:

    ```rust,editable
    # Contents of example.rs here.
    ```

And the `editable` attribute will enable the editor as described at Rust code block attributes.

## Controlling page <title>

A chapter can set a <title> that is different from its entry in the table of contents (sidebar) by including a `{{#title ...}}` near the top of the page.

    {{#title My Title}}

## HTML classes provided by mdBook

### `class="left"` and `"right"`

These classes are provided by default, for inline HTML to float images.

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

### `class="hidden"`

HTML tags with class `hidden` will not be shown.

    <div class="hidden">This will not be seen.</div>

This will not be seen.

## Font-Awesome icons

mdBook includes a copy of version 6 of Font Awesome Free’s MIT-licensed SVG files. It emulates the `<i>` syntax, but converts the results to inline SVG. Only the regular, solid, and brands icons are included; paid features like the light icons are not.

For example, given this HTML syntax:

    The result looks like this: <i class="fa-solid fa-print"></i>

The result looks like this:

See the free icon set for the available icons.