Preprocessors - 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

# Configuring Preprocessors

Preprocessors are extensions that can modify the raw Markdown source before it gets sent to the renderer.

The following preprocessors are built-in and included by default:

- `links`: Expands the `{{ #playground }}`, `{{ #include }}`, and `{{ #rustdoc_include }}` handlebars helpers in a chapter to include the contents of a file. See Including files for more.
- `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.

The built-in preprocessors can be disabled with the `build.use-default-preprocessors` config option.

The community has developed several preprocessors. See the Third Party Plugins wiki page for a list of available preprocessors.

For information on how to create a new preprocessor, see the Preprocessors for Developers chapter.

## Custom preprocessor configuration

Preprocessors can be added by including a `preprocessor` table in `book.toml` with the name of the preprocessor. For example, if you have a preprocessor called `mdbook-example`, then you can include it with:

    [preprocessor.example]

With this table, mdBook will execute the `mdbook-example` preprocessor.

This table can include additional key-value pairs that are specific to the preprocessor. For example, if our example preprocessor needed some extra configuration options:

    [preprocessor.example]
    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.example]
    renderers = ["html"]  # example preprocessor only runs with the HTML renderer

## Provide your own command

By default when you add a `[preprocessor.foo]` table to your `book.toml` file, `mdbook` will try to invoke the `mdbook-foo` executable. If you want to use a different program name or pass in command-line arguments, this behaviour can be overridden by adding a `command` field.

    [preprocessor.random]
    command = "python random.py"

### Optional preprocessors

If you enable a preprocessor that isn’t installed, the default behavior is to throw an error. This behavior can be changed by marking the preprocessor as optional:

    [preprocessor.example]
    optional = true

This demotes the error to a warning.

## Require a certain order

The order in which preprocessors are run can be controlled with the `before` and `after` fields. For example, suppose you want your `linenos` preprocessor to process lines that may have been `{{#include}}`d; then you want it to run after the built-in `links` preprocessor, which you can require using either the `before` or `after` field:

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

or

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

It would also be possible, though redundant, to specify both of the above in the same config file.

Preprocessors having the same priority specified through `before` and `after` are sorted by name. Any infinite loops will be detected and produce an error.