mdBook 通用配置指南：book.toml 中的 book、rust 与 build 配置项详解-开发者社区

开发工具
文档

【免费下载链接】mdBook

Create book from markdown files. Like Gitbook but implemented in Rust

项目地址：https://gitcode.com/gh_mirrors/md/mdBook

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 表形式保存，分别交给各渲染器与预处理器自行消费。

每个配置结构体都标注了#[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] 配置表

[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] 配置表

[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] 配置表

[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会禁用这两个默认预处理器；
但只要你显式声明了某个预处理器表（例如[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 的配置体系还包括：

预处理器配置：[preprocessor.xxx]各键的详细说明见 format/configuration/preprocessors.md；
渲染器配置：[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 的构建产物。