【mdBook】5.2.3 渲染器配置详解

渲染器概述

渲染器（也称为"后端"）负责生成书籍的最终输出格式。

内置渲染器

系统提供以下内置渲染器：

markdown 复制代码

**html** - 将书籍渲染为 HTML。如果 `book.toml` 中未定义其他 [output] 表，则默认启用此渲染器。

**markdown** - 在运行预处理器后将书籍输出为 Markdown 格式。这对调试预处理器非常有用。

社区渲染器

社区已开发多个后端渲染器，可在"第三方插件" Wiki 页面查看完整列表。

开发者创建新后端的指南请参阅"开发者后端"章节。

输出配置表

基础配置

在 book.toml 中添加输出配置表即可启用后端：

toml 复制代码

[output.wordcount]

此配置会使 mdBook 执行名为 mdbook-wordcount 的后端。

自定义配置

输出表可包含特定的键值对配置：

toml 复制代码

[output.wordcount]
ignores = ["Example Chapter"]

HTML 渲染器默认行为

重要规则：如果定义了任何 [output] 表，则 html 后端不再默认启用。如需保留 HTML 输出，必须显式包含：

toml 复制代码

[book]
title = "我的书籍"

[output.wordcount]
[output.html]  # 必须显式添加以启用 HTML 输出

多后端输出目录结构

markdown 复制代码

- **单后端**：输出直接放置在书籍目录中
- **多后端**：每个后端在书籍目录下创建独立子目录
  - `book/html/`
  - `book/wordcount/`

自定义后端命令

默认情况下，mdBook 会尝试调用 mdbook-foo 可执行文件。可通过 command 字段覆盖此行为：

toml 复制代码

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

可选后端

如果启用了未安装的后端，默认会报错。可通过标记为可选来改变此行为：

toml 复制代码

[output.wordcount]
optional = true  # 将错误降级为警告

HTML 渲染器配置选项

基础配置示例

toml 复制代码

[output.html]
theme = "my-theme"
default-theme = "light"
preferred-dark-theme = "navy"
smart-punctuation = true
mathjax-support = false
additional-css = ["custom.css"]
additional-js = ["custom.js"]
git-repository-url = "https://github.com/user/repo"
site-url = "/my-book/"

主要配置选项说明

选项	描述	默认值
`theme`	自定义主题目录，覆盖默认主题文件	默认主题
`default-theme`	"更改主题"下拉框的默认配色方案	`light`
`preferred-dark-theme`	浏览器请求深色版本时使用的主题	`navy`
`smart-punctuation`	智能标点转换（直引号转弯引号等）	`false`
`mathjax-support`	启用 MathJax 数学公式支持	`false`
`additional-css`	附加 CSS 样式表，用于微调样式	空数组
`additional-js`	附加 JavaScript 文件，用于添加功能	空数组
`no-section-label`	禁用目录中的数字节标签（如"1."、"2.1"）	`false`
`git-repository-icon`	Git 仓库链接的 FontAwesome 图标类	`fa-github`
`edit-url-template`	"建议编辑"按钮的 URL 模板	未设置
`site-url`	书籍托管的基础 URL	`/`
`cname`	自定义域名（用于 GitHub Pages）	未设置
`hash-files`	在静态资源文件名中包含内容哈希指纹	`false`

子配置表

打印输出配置

toml 复制代码

[output.html.print]
enable = true    # 启用打印支持
page-break = true # 章节间插入分页符

章节折叠配置

toml 复制代码

[output.html.fold]
enable = false   # 启用章节折叠
level = 0        # 折叠起始深度（0=全部折叠）

代码 playground 配置

toml 复制代码

[output.html.playground]
editable = false    # 允许编辑源代码
copyable = true     # 显示代码复制按钮
runnable = true     # 显示运行按钮（Rust代码）
line-numbers = false # 显示行号（需editable=true）

代码块配置

toml 复制代码

[output.html.code]
hidelines = { python = "~" }  # 定义各语言的隐藏行前缀

搜索功能配置

toml 复制代码

[output.html.search]
enable = true
limit-results = 30
teaser-word-count = 30
use-boolean-and = true
boost-title = 2
heading-split-level = 3

章节级搜索配置

toml 复制代码

[output.html.search.chapter]
"appendix" = { enable = false }           # 禁用附录目录的搜索索引
"appendix/glossary.md" = { enable = true } # 启用特定附录章节的搜索

页面重定向配置

toml 复制代码

[output.html.redirect]
# 完整页面重定向
"/old-page.html" = "/new-page.html"
# 外部重定向
"/external.html" = "https://example.com"
# 锚点重定向
"/page.html#old-section" = "/page.html#new-section"

Markdown 渲染器

Markdown 渲染器运行预处理器后输出最终的 Markdown，主要用于调试：

toml 复制代码

[output.markdown]  # 启用 Markdown 输出（无其他配置选项）

用途：结合 mdbook test 查看传递给 rustdoc 的 Markdown 内容。