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": "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": "General", "link": "/v0-5-4/en/01-guide/17-format-configuration-general"} next: {"text": "Renderers", "link": "/v0-5-4/en/01-guide/19-format-configuration-renderers"} ---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.
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
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
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"
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.
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.