Configuring Preprocessors 配置预处理器

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

预处理器是在将原始 Markdown 源发送到渲染器之前对其进行修改的扩展。

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.
  • 扩展 {{ #playground }}、{{ #include }}和{{ #rustdoc_include }}章节中的帮助程序，用于包含文件的内容。 有关详细信息，请参阅Including files。
  • 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.
  • 将所有名为README.md的章节文件转换为index.md。也就是说，书中所有README.md都将渲染成索引文件index.html。

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

可以使用 build.use-default-preprocessors 配置选项禁用内置预处理器。

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

社区已经开发了几个预处理器。 请参阅Third Party Plugins wiki 页面，了解可用的预处理器列表。

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

有关如何创建新的预处理器的信息，请参阅Preprocessors for Developers 一章。

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:

可以通过在book.toml中包含带有预处理器名称的preprocessor 表来添加预处理器。 例如，如果您有一个名为mdbook-example的预处理器，则可以将其包含在以下位置：

[preprocessor.example]

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

有了这个表，mdBook将执行mdbook-example 预处理器。

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 需要一些额外的配置选项：

[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"]  # 示例预处理器仅使用 HTML 呈现器运行

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.foo] 表添加到book.toml文件时， mdbook将尝试调用mdbook-foo 可执行文件。如果要使用 不同的程序名称或传入命令行参数，此行为可以 通过添加 command字段进行覆盖。

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

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:

预处理器的运行顺序可以通过before 和after 字段进行控制。 例如，假设您希望linenos预处理器处理可能是{{#include}}的行;然后，您希望它在内置的“链接”预处理器之后运行，您可以要求使用 before或after字段：

[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.

通过before 和 after指定了相同优先级的预处理器按名称排序。 将检测到任何无限循环并产生错误。