mdBook 通用配置指南：book.toml 中的 book、rust 与 build 配置项详解

mdBook 将一本书的全部构建参数集中存放在根目录的 book.toml 文件中，本文以官方文档 General configuration 为骨架，结合仓库源码逐项拆解 [book]、[rust]、[build] 三个核心配置表：你会掌握每个键的含义、默认值、生效范围与典型用法，并了解这些配置在 mdBook 源码中的实际解析与调用位置，从而能够独立完成一本多语言、可定制构建流程的书籍配置。

配置文件入口：book.toml 从哪来、如何加载

mdBook 在运行 mdbook build、mdbook serve 等命令时，会从书籍根目录读取 book.toml。配置加载的核心实现在 crates/mdbook-core/src/config.rs：

• Config::from_str 直接调用 toml::from_str 解析 TOML 内容（config.rs）；
• Config::from_disk 负责把磁盘上的配置文件读成字符串再交给 from_str（config.rs）；
• Config 结构体由 book、build、rust、output、preprocessor 五个顶层表组成（config.rs），其中 output 与 preprocessor 以松散 TOML 表形式保存，分别交给各渲染器与预处理器自行消费。

每个配置结构体都标注了 #<a href="https://link.gitcode.com/i/3ec4401d5b71c80cf4c2c22b6907e11e" target="_blank">serde(default, rename_all = "kebab-case", deny_unknown_fields)]（如 [config.rs），这意味着：

• 所有键均采用 kebab-case 命名（如 build-dir、text-direction）；
• 未在配置文件中出现的键会自动回落到结构体的 Default 实现，不会报错；
• 而未知键则会因 deny_unknown_fields 直接导致解析失败，避免拼写错误被静默吞掉。

下面的完整示例覆盖了本文讲解的全部配置节（来自文档 general.md）：

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

[rust]
edition = "2018"

[build]
build-dir = "my-example-book"
create-missing = false

[preprocessor.index]

[preprocessor.links]

[output.html]
additional-css = ["custom.css"]

[output.html.search]
limit-results = 15

一个必须牢记的全局规则是：配置文件中出现的任何相对路径，始终以存放 book.toml 的书籍根目录为基准，而不是以当前终端的工作目录为基准（文档 general.md 明确强调）。这一点对 src、build-dir、extra-watch-dirs 等路径型键都适用。

书籍元信息：[book] 配置表

<a href="https://link.gitcode.com/i/39b1575c04f3be96a25329cccd71cc28" target="_blank">book] 表存放书籍的通用元数据，对应源码中的 [BookConfig 结构体。各键说明如下：

• title：书名，类型为可选字符串（Option<String>，默认 None）；
• authors：作者列表，Vec<String>，默认空数组；在 HTML 渲染时会被写入 <meta name="author"> 等元信息；
• description：书籍描述，写入每个页面 HTML <head> 中的 meta 信息（默认 None）；
• src：源码目录，默认值是 src——即书籍根目录下名为 src 的文件夹（config.rs）。可通过此键改到任意目录，如 src = "my-src" 表示源码位于 root/my-src；
• language：书籍主语言，默认 Some("en")（config.rs），会用于生成 <html lang="en"> 之类的语言属性；
• text-direction：文字方向，可选值为 ltr（从左到右）与 rtl（从右到左），对应枚举 TextDirection。未指定时由 language 自动推导。

示例配置（来自文档 general.md）：

[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
src = "my-src"  # 源码将位于 root/my-src 而不是 root/src
language = "en"
text-direction = "ltr"

language 与 text-direction 的推导规则

从源码可以确认两者并非独立生效，而是存在优先级关系。BookConfig::realized_text_direction（config.rs）的逻辑是：显式设置了 text-direction 就用它；否则调用 TextDirection::from_lang_code 根据语言代码推导（config.rs）。

推导时内置了一张 RTL 语言清单，包含 ar/ara、he/heb、fa/per/fas、ur/urd、yi/yid、ku/kur 等常见从右到左书写系统的语言代码；清单之外的语言一律视为 LTR。仓库中的测试用例也印证了这套规则，例如语言设为 ar/he 时推导结果为 RightToLeft，en/ja 为 LeftToRight；而一旦显式设置 text-direction，无论语言为何都以显式值为准（config.rs 的 test_text_direction 测试）。

因此，编写阿拉伯语、希伯来语或波斯语书籍时，即使不写 text-direction，只要正确设置 language，mdBook 也会自动为页面输出 RTL 方向；若个别书籍需要"阿拉伯语内容但整体 LTR 排版"这类特殊场景，则可用 text-direction 显式覆盖。

Rust 语言选项：[rust] 配置表

<a href="https://link.gitcode.com/i/a2bed52f8fbadfbb3181a33db5200a2e" target="_blank">rust] 表控制与 Rust 代码块、测试和 playground 相关的行为，对应源码中的 [RustConfig，目前只有一个公开键：

• edition：代码块默认使用的 Rust edition，可选值为 2015、2018、2021、2024，对应枚举 RustEdition。默认值是 "2015"（RustEdition 的 Default 派生自结构体，且文档明确说明默认为 2015）。

[rust]
edition = "2015"   # 代码块的默认 edition

单个代码块可以通过注解覆盖全局默认值，例如只让某一块按 2015 版编译（文档 general.md）：

```rust,edition2015
// 这段代码仅在 2015 edition 下有效。
let try = true;
```

对应的注解依次是 edition2015、edition2018、edition2021、edition2024。仓库配置解析测试也验证了 edition 键与 RustEdition 枚举的映射关系：edition = "2018" 解析为 RustEdition::E2018，"2021" 对应 E2021（config.rs）。此外 rust.edition 也可以借助 Config::set 在运行时动态覆盖，测试 set("rust.edition", "2024") 后解析结果为 RustEdition::E2024（config.rs）。

构建选项：[build] 配置表

<a href="https://link.gitcode.com/i/e7a836184701a88e96cd739c0676e80e" target="_blank">build] 表控制书籍的构建流程，对应源码中的 [BuildConfig，共有四个键：

[build]
build-dir = "book"                # 输出目录
create-missing = true             # 是否自动创建缺失页面
use-default-preprocessors = true  # 是否使用默认预处理器
extra-watch-dirs = []             # 额外监听目录，触发自动重建

build-dir：输出目录

渲染结果输出到书籍根目录下的 book/ 目录，默认值 book（config.rs）。构建生成的 index.html 路径即为 build_dir_for("html") 与 index.html 拼接的结果（src/cmd/build.rs）。

该配置可以被命令行参数 --dest-dir（短选项 -d）覆盖。从 command_prelude.rs 可以看到，--dest-dir 的帮助信息明确说明：省略时使用 build.build-dir，再缺省则回落到 ./book；而 set_dest_dir 函数（command_prelude.rs）在提供该参数时，会用"当前工作目录 + 参数路径"直接覆写 book.config.build.build_dir。注意此处的路径基准是当前工作目录，与 book.toml 内相对路径以书籍根目录为基准的规则不同。

create-missing：缺失章节自动创建

SUMMARY.md 中列出的 Markdown 文件如果不存在，默认（true）会在构建时自动创建空文件；设为 false 后，构建遇到缺失文件会直接报错退出（文档 general.md）。

源码层面，该行为发生在书籍加载阶段：load_book 在解析完 SUMMARY.md 后检查 cfg.create_missing，为 true 时调用 create_missing(src_dir, &summary) 补齐缺失章节（crates/mdbook-driver/src/load.rs）。仓库测试集里也有对应的集成用例 tests/testsuite/build/create_missing/book.toml 与 tests/testsuite/build.rs，验证了该开关的实际行为。

use-default-preprocessors：默认预处理器开关

mdBook 自带 links 与 index 两个默认预处理器，此键控制它们是否运行，默认 true（config.rs）。判定规则在 crates/mdbook-driver/src/mdbook.rs：

• 不配置任何预处理器时，默认的 links 与 index 照常运行；
• use-default-preprocessors = false 会禁用这两个默认预处理器；
• 但只要你显式声明了某个预处理器表（例如 <a href="https://link.gitcode.com/i/d973f178d5ec1fc0c11428581f28af43" target="_blank">preprocessor.links]），无论该开关是 true 还是 false，这个预处理器都会运行（文档 [general.md）。换言之，显式声明具有最高优先级。

这意味着你可以在保留默认预处理器的同时追加自定义预处理器；也可以关闭默认行为、完全用自己声明的预处理器替代。

extra-watch-dirs：扩展监听目录

一个字符串列表（Vec<PathBuf>，默认空），在 mdbook watch 与 mdbook serve 命令下生效：这些目录中的文件变化会触发重建。当书籍依赖 src 目录之外的内容（例如外部数据文件、模板、脚本生成的中间产物）时非常有用（文档 general.md）。相关命令的实现位于 src/cmd/watch.rs 与 src/cmd/serve.rs。

完整配置实战示例

综合以上内容，一份面向实际项目的 book.toml 可以这样组织：

[book]
title = "My Team Handbook"
authors = ["Alice", "Bob"]
description = "Team internal documentation built with mdBook."
language = "zh-CN"      # 设置语言属性 lang="zh-CN"

[rust]
edition = "2021"        # 全书记代码块默认使用 2021 edition

[build]
build-dir = "dist"      # 自定义输出目录，也可用 -d/--dest-dir 覆盖
create-missing = true   # SUMMARY.md 中缺失的章节自动创建
extra-watch-dirs = ["data"]  # data/ 下的改动也会触发 watch/serve 重建

[preprocessor.links]
# 显式声明 links 预处理器（即使关闭默认也会运行）

[output.html]
additional-css = ["custom.css"]

配置的进一步扩展

本文只覆盖了通用配置三表；mdBook 的配置体系还包括：

• 预处理器配置：<a href="https://link.gitcode.com/i/2914ee6b7b824ecc2717ada7bf34a2d7" target="_blank">preprocessor.xxx] 各键的详细说明见 [format/configuration/preprocessors.md；
• 渲染器配置：<a href="https://link.gitcode.com/i/becfe1b96a4f546362dd9a7558cf4ac2" target="_blank">output.html] 等渲染器专属键见 [format/configuration/renderers.md；
• 环境变量覆盖：所有配置都可以通过 MDBOOK_ 前缀的环境变量覆盖，例如 MDBOOK_BOOK__TITLE 对应 book.title，底层实现在 config.rs 的 update_from_env，详细规则见 format/configuration/environment-variables.md。

掌握了 book.toml 的通用配置骨架后，再配合预处理器与渲染器配置，即可完整定制一本 mdBook 的构建产物。