--- title: "Configuring Renderers" documentId: "mdbook:guide/src/format/configuration/renderers.md" order: 18 licenseSource: "mdbook-guide" documentContext: [{"kind": "source", "html": "

mdBook 0.5.4 fixed documentation, MPL-2.0. Original chapter · Original Markdown · Editable Libx document · Complete fixed upstream source. · Editable source and build context.

"}, {"kind": "editorial", "html": "

Original example assets retained. Rust logo: CC BY 4.0, unchanged, no affiliation or endorsement. Font Awesome SVG: CC BY 4.0; non-icon code: MIT. The original MIT wording and literal SVG example remain unchanged. Original example materials retain their separate terms; Libx provides an unofficial static edition.

"}, {"kind": "editorial", "html": "

Static Libx presentation: examples show their complete code, including lines hidden in the original demo. Editing, code execution and MathJax rendering are provided by the original project; formula examples retain their original TeX notation here. The document text and expanded examples are retained. This is an unofficial Libx static edition. Original text and examples are preserved; translated pages are identified separately.

"}] prev: {"text": "Preprocessors", "link": "/v0-5-4/en/01-guide/18-format-configuration-preprocessors"} next: {"text": "Environment variables", "link": "/v0-5-4/en/01-guide/16-format-configuration-environment-variables"} ---

Configuring Renderers

Renderers (also called “backends”) are responsible for creating the output of the book.

The following backends are built-in:

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

For information on how to create a new backend, see the Backends for Developers chapter.

Output tables

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

[output.wordcount]

With this table, mdBook will execute the mdbook-wordcount backend.

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

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

If you define any [output] tables, then the html backend is not enabled by default. If you want to keep the html backend running, then just include it in the book.toml file. For example:

[book]
title = "My Awesome Book"

[output.wordcount]

[output.html]

If more than one output table is included, this changes the behavior for the layout of the output directory. If there is only one backend, then it places its output directly in the book directory (see build.build-dir to override this location). If there is more than one backend, then each backend is placed in a separate directory underneath book. For example, the above would have directories book/html and book/wordcount.

Custom backend commands

By default when you add an [output.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.

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

Optional backends

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

[output.wordcount]
optional = true

This demotes the error to a warning.

HTML renderer options

The HTML renderer has a variety of options detailed below. They should be specified in the [output.html] table of the book.toml file.

# Example book.toml file with all output options.
[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
definition-lists = true
admonitions = true
mathjax-support = false
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 = "fab-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"
sidebar-header-nav = true

The following configuration options are available:

[output.html.print]

The [output.html.print] table provides options for controlling the printable output. By default, mdBook will include an icon on the top right of the book (which looks like ) that will print the book as a single page.

[output.html.print]
enable = true    # include support for printable output
page-break = true # insert page-break after each chapter

[output.html.fold]

The [output.html.fold] table provides options for controlling folding of the chapter listing in the navigation sidebar.

[output.html.fold]
enable = false    # whether or not to enable section folding
level = 0         # the depth to start folding

[output.html.playground]

The [output.html.playground] table provides options for controlling Rust sample code blocks, and their integration with the Rust Playground.

[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

[output.html.code]

The [output.html.code] table provides options for controlling code blocks.

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

[output.html.search]

The [output.html.search] table provides options for controlling the built-in text search. mdBook must be compiled with the search feature enabled (on by default).

[output.html.search]
enable = true            # enables the search feature
limit-results = 30       # maximum number of search results
teaser-word-count = 30   # number of words used for a search result teaser
use-boolean-and = true   # multiple search terms must all match
boost-title = 2          # ranking boost factor for matches in headers
boost-hierarchy = 1      # ranking boost factor for matches in page names
boost-paragraph = 1      # ranking boost factor for matches in text
expand = true            # partial words will match longer terms
heading-split-level = 3  # link results to heading levels
copy-js = true           # include Javascript code for search

[output.html.search.chapter]

The [output.html.search.chapter] table provides the ability to modify search settings per chapter or directory. Each key is the path to the chapter source file or directory, and the value is a table of settings to apply to that path. This will merge recursively, with more specific paths taking precedence.

[output.html.search.chapter]
# Disables search indexing for all chapters in the `appendix` directory.
"appendix" = { enable = false }
# Enables search indexing for just this one appendix chapter.
"appendix/glossary.md" = { enable = true }

[output.html.redirect]

The [output.html.redirect] table provides a way to add redirects. This is useful when you move, rename, or remove a page to ensure that links to the old URL will go to the new location.

[output.html.redirect]
"/appendices/bibliography.html" = "https://rustc-dev-guide.rust-lang.org/appendix/bibliography.html"
"/other-installation-methods.html" = "../infra/other-installation-methods.html"

# Fragment redirects also work.
"/some-existing-page.html#old-fragment" = "some-existing-page.html#new-fragment"

# Fragment redirects also work for deleted pages.
"/old-page.html" = "new-page.html"
"/old-page.html#old-fragment" = "new-page.html#new-fragment"

The table contains key-value pairs where the key is where the redirect file needs to be created, as an absolute path from the build directory, (e.g. /appendices/bibliography.html). The value can be any valid URI the browser should navigate to (e.g. https://rust-lang.org/, /overview.html, or ../bibliography.html).

This will generate an HTML page which will automatically redirect to the given location.

When fragment redirects are specified, the page must use JavaScript to redirect to the correct location. This is useful if you rename or move a section header. Fragment redirects work with existing pages and deleted pages.

Markdown renderer

The Markdown renderer will run preprocessors and then output the resulting Markdown. This is mostly useful for debugging preprocessors, especially in conjunction with mdbook test to see the Markdown that mdbook is passing to rustdoc.

The Markdown renderer is included with mdbook but disabled by default. Enable it by adding an empty table to your book.toml as follows:

[output.markdown]

There are no configuration options for the Markdown renderer at this time; only whether it is enabled or disabled.

See the preprocessors documentation for how to specify which preprocessors should run before the Markdown renderer.