mdBook 预处理器（Preprocessor）配置完全指南：book.toml 配置项、内置插件与源码原理

Preprocessor（预处理器）是 mdBook 中在 Markdown 源文件被送入渲染器（Renderer）之前对其进行修改的扩展机制，承担 {{#include}} 文件引入、README.md 转 index.md 等核心职责，也是社区插件生态的接入点。本文以官方配置文档 guide/src/format/configuration/preprocessors.md 为骨架，结合仓库源码深入讲解 book.toml 中 [preprocessor.*] 表的全部配置项、执行顺序控制、命令覆盖机制，并带你理解其底层实现原理，读完后你可以熟练地为自己的书籍配置、编排甚至编写自定义预处理器。

什么是预处理器

预处理器是在书籍（Book）被加载之后、渲染（Render）之前运行的代码片段，用于更新和修改书籍内容。它接收原始的 Markdown 源，可以在渲染前执行文本替换、文件引入、结构转换等操作，典型用途包括：

• 创建自定义辅助指令，例如 \{{#include /path/to/file.md}}；
• 将 LaTeX 风格表达式（$$ \frac{1}{3} $$）替换为对应的 MathJax 等价形式；
• 统计章节字数、校验文档结构、生成目录等。

mdBook 发现第三方插件的方式非常简单：在 book.toml 中新增一个表（例如 <a href="https://link.gitcode.com/i/e5c44cc9354ea7fed5765c20a3826507" target="_blank">preprocessor.foo]），构建时 mdBook 便会尝试调用名为 mdbook-foo 的可执行程序作为构建流程的一部分。这一机制与自定义渲染器（Renderer）的发现方式对称，可参见 [guide/src/format/configuration/README.md。

内置预处理器

mdBook 内置两个预处理器，并默认启用：

• links：展开章节中的 {{ #playground }}、{{ #include }}、{{ #rustdoc_include }} 以及 {{ #title }} 等 Handlebars 辅助指令，将外部文件内容包含进当前章节。它同时支持按行区间或锚点截取文件片段，详见 guide/src/format/mdbook.md#including-files。从源码看，其实现位于 crates/mdbook-driver/src/builtin_preprocessors/links.rs，正则 {{ \s*#([a-zA-Z0-9_]+)\s+([^}]+)}} 用于识别各类链接，并对嵌套引入设置了最大深度 MAX_LINK_NESTED_DEPTH = 10 以防循环引用导致栈溢出。
• index：将所有名为 README.md 的章节文件转换为 index.md，也就是说 README.md 最终会被渲染为构建产物中的 index.html。源码位于 crates/mdbook-driver/src/builtin_preprocessors/index.rs，其判定逻辑使用大小写不敏感的正则 (?i)^readme$ 匹配文件主干名，因此 Readme.md、rEaDmE.md 等写法都会被识别，同时若同一目录下同时存在 README.md 与 index.md 会输出冲突警告。

内置预处理器可通过 build.use-default-preprocessors 配置项禁用，具体说明见 guide/src/format/configuration/general.md#build-options。

社区还开发了大量第三方预处理器（如代码行号、文件校验、数学公式等），官方在 Third Party Plugins wiki 页面维护了可用预处理器列表。若需要自己实现一个预处理器，可参考 guide/src/for_developers/preprocessors.md。

自定义预处理器配置

要启用一个自定义预处理器，只需在 book.toml 中加入以预处理器名称命名的 preprocessor 表。例如，假设你有一个名为 mdbook-example 的预处理器：

[preprocessor.example]

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

该表还可以包含特定于该预处理器的附加键值对。例如，假设你的示例预处理器需要一些额外配置选项：

[preprocessor.example]
some-extra-feature = true

这些额外的键值对会被原样传递给预处理器（以配置上下文的形式通过 JSON 提供），由预处理器自行解释。需要说明的是，before、after、optional、command、renderers 属于 mdBook 保留的调度相关字段，其余键值对则作为自定义配置透传。

将预处理器锁定到特定渲染器

默认情况下，预处理器是否运行取决于其是否声明支持当前渲染器。你也可以通过 renderers 字段显式指定预处理器只为某个渲染器运行，将两者绑定：

[preprocessor.example]
renderers = ["html"]  # example preprocessor only runs with the HTML renderer

当 renderers 列表存在时，mdBook 会直接按列表匹配渲染器名称，而不再询问预处理器自身的支持情况。对应实现位于 crates/mdbook-driver/src/mdbook.rs 的 preprocessor_should_run 函数：它优先读取 preprocessor.<名称>.renderers 配置，配置缺失时才回退到调用 Preprocessor::supports_renderer() 方法。

提供自定义命令

默认情况下，当你在 book.toml 中添加 [preprocessor.foo] 表时，mdbook 会尝试调用名为 mdbook-foo 的可执行文件。如果你想使用不同的程序名，或需要传入命令行参数，可以通过添加 command 字段覆盖这一行为：

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

需要注意的是，command 的内容会作为完整命令行解析执行，因此可以携带参数。从源码看（crates/mdbook-driver/src/builtin_preprocessors/cmd.rs 与 crates/mdbook-driver/src/mdbook.rs），当 command 未配置时，默认命令按 mdbook-{name} 拼接；自定义预处理器统一包装为 CmdPreprocessor 执行。

可选预处理器

如果你启用的预处理器未被安装，默认行为是抛出错误、构建失败。你可以通过将预处理器标记为 optional 来改变这一行为：

[preprocessor.example]
optional = true

这会将错误降级为警告。从源码实现看（cmd.rs 中 handle_command_error 的调用），命令无法启动（如 NotFound）时会根据 optional 决定是直接报错还是记录警告并跳过该预处理器。

控制预处理器的执行顺序

预处理器按什么顺序运行，可以通过 before 与 after 字段控制。例如，假设你希望自己的 linenos 预处理器处理那些可能通过 {{#include}} 引入的行，那么它需要在内置 links 预处理器之后运行，可以使用 after 字段：

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

或者使用 before 字段（语义等价）：

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

在同一个配置文件中同时指定上述两者也是可行的，尽管略显冗余。

底层实现（crates/mdbook-driver/src/mdbook.rs）使用 topological_sort 库对所有预处理器构建有向无环图：after 语义上等价于"将自身排在被依赖者之后"，before 等价于"将被依赖者排在自己之前"，两者最终都转化为依赖关系。值得注意的细节有：

• 同名优先级按名称排序：通过 before/after 指定了相同优先级的预处理器，会按名称排序后执行。源码中明确注释，topological_sort 对并列项不保证稳定顺序，因此 mdBook 在 pop_batch() 取出同批次名称后手动调用 names.sort() 来打破平局。
• 循环依赖检测：如果配置形成了环形依赖（例如 A 在 B 之后、B 又在 A 之后），拓扑排序无法排出合法顺序，mdBook 会抛出 Cyclic dependency detected in preprocessors 错误终止构建。
• 缺失依赖仅告警：如果 before/after 中引用的预处理器不存在（既非内置默认预处理器，也未在配置表中声明），mdBook 只输出警告而不会失败，这样便于在排查问题时临时启停预处理器而无需担心顺序约束。

此外，build.use-default-preprocessors = false 会跳过内置的 links、index；但若你显式声明了 <a href="https://link.gitcode.com/i/b1857862ae3fe6f2c521a30592b1f5a6" target="_blank">preprocessor.links] 表，那么无论该选项取值如何，links 都会被强制启用运行。general.md 中对这一交互有明确说明（[guide/src/format/configuration/general.md）。

预处理器与渲染器的协作流程

理解了配置项之后，再看整体运行机制。mdBook 的构建入口在 MDBook::build()（crates/mdbook-driver/src/mdbook.rs），它会为每个渲染器调用 execute_build_process()，流程如下：

1. 根据配置确定要运行的预处理器集合与顺序（determine_preprocessors）；
2. 为当前渲染器构建 PreprocessorContext（包含书籍根目录、配置快照与渲染器名称）；
3. 按序执行每个预处理器的 run()，前一个的输出作为后一个的输入；
4. 将最终处理后的 Book 交给渲染器输出。

对于外部命令型预处理器（CmdPreprocessor），mdBook 会执行该命令两次：

• 第一次：以 supports <renderer> 两个参数调用，预处理器返回退出码 0 表示支持该渲染器，非 0 表示不支持；
• 第二次（若支持）：向 stdin 写入 JSON 数据，格式为 <a href="https://link.gitcode.com/i/f3cc372110ff436f2db249a3565c666f" target="_blank">context, book] 数组，其中 context 是序列化的 PreprocessorContext，book 是待处理的 Book 对象；预处理器将修改后的 Book 以 JSON 格式输出到 stdout，mdBook 从 stdout 解析并继续后续流程（[crates/mdbook-driver/src/builtin_preprocessors/cmd.rs）。

这一 stdin/stdout 协议意味着预处理器并不限定使用 Rust 实现，任何语言只要遵循该 JSON 协议即可接入，例如用 Python 读取 stdin 后修改 book['items'][0]['Chapter']['content'] 再打印回 stdout。完整的协议说明与示例代码见 guide/src/for_developers/preprocessors.md。

实战示例：一份完整的 book.toml 预处理器配置

将上述配置项整合起来，一个典型的 book.toml 预处理器配置段如下：

[book]
title = "Example book"
authors = ["John Doe"]
description = "The example book covers examples."

[build]
use-default-preprocessors = true  # 显式保持内置 links、index 启用

# 自定义预处理器：默认执行 mdbook-foo 命令，额外配置透传
[preprocessor.foo]
some-extra-feature = true

# 绑定渲染器：仅当 HTML 渲染器运行时才执行
[preprocessor.example]
renderers = ["html"]

# 自定义命令：使用 python 脚本代替 mdbook-random 可执行文件
[preprocessor.random]
command = "python random.py"

# 可选预处理器：未安装时降级为警告而非报错
[preprocessor.example2]
optional = true

# 顺序控制：确保 linenos 在 links（处理 {{#include}}）之后运行
[preprocessor.linenos]
after = [ "links" ]

配置完成后运行 mdbook build，即可在日志中观察到各预处理器的执行顺序与结果。若需要调试顺序问题，可将 use-default-preprocessors 临时设为 false 以隔离内置预处理器的影响。

总结

mdBook 的预处理器机制是书籍内容处理管线的核心扩展点：内置的 links 与 index 承担了文件引入和 README 归一化的基础职责，而 [preprocessor.*] 表则为任意第三方工具提供了标准接入方式。通过 command、renderers、optional 以及 before/after 四个关键字段，你可以精确控制外部程序的调用方式、作用渲染器范围、失败容忍度与执行顺序；其底层基于拓扑排序和 stdin/stdout JSON 协议的实现，既保证了顺序的确定性与循环依赖的检测，也让多语言实现预处理器成为可能。掌握这些配置与原理后，你便可以根据书籍的特定需求自由组合、编排预处理流水线。