Configuring Renderers 配置渲染器

渲染器（也称为“后端”）负责创建书籍的输出。

以下是内置的后端：

  • html — 这会将书籍呈现为 HTML。 如果book.toml中未定义其他[output] 表，则默认启用此功能。
  • markdown —这将在运行预处理器后将书籍输出为markdown。 这对于调试预处理器非常有用。

社区已经开发了几个后端。 请参阅 Third Party Plugins wiki页面以获取可用后端的列表。

有关如何创建新的后端的信息，请参阅 Backends for Developers 一章。

Output tables

可以通过在 book.toml中包含带有后端名称的output表来添加后端。 例如，如果你有一个名为mdbook-wordcount的后端，那么你可以用：

[output.wordcount]

有了这个表，mdBook将执行mdbook-wordcount后端。

此表可以包含特定于后端的其他键值对。 例如，如果我们的示例后端需要一些额外的配置选项：

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

如果定义任何 [output]表，则默认情况下不启用html后端。 如果你想保持html后端运行，那么只需将其包含在book.toml文件中。 例如：

[book]
title = "My Awesome Book"
[output.wordcount]
[output.html]

如果包含多个输出表，则会更改输出目录布局的行为。 如果只有一个后端，则将其输出直接放在book目录中（请参阅build.build-dir以覆盖此位置）。 如果有多个后端，则每个后端都放在book下的单独目录中。 例如，上面将有目录book/html和book/wordcount。

Custom backend commands 自定义后端命令

默认情况下，当您将 [output.foo] 表添加到book.toml文件时， mdbook将尝试调用mdbook-foo可执行文件。 如果要使用其他程序名称或传入命令行参数， 可以通过添加command字段来覆盖此行为。

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

Optional backends 可选后端

如果启用未安装的后端，则默认行为是引发错误。 可以通过将后端标记为可选来更改此行为：

[output.wordcount]
optional = true

这会将错误降级为警告

HTML renderer options. HTML 呈现器选项

HTML 呈现器具有下面详细介绍的各种选项。 它们应该在book.toml文件的[output.html]表中指定。

# 包含所有输出选项的示例 book.toml 文件。
[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
[output.html]
theme = "my-theme"
default-theme = "light"
preferred-dark-theme = "navy"
curly-quotes = true
mathjax-support = false
copy-fonts = true
additional-css = ["custom.css", "custom2.css"]
additional-js = ["custom.js"]
no-section-label = false
git-repository-url = "https://github.com/rust-lang/mdBook"
git-repository-icon = "fa-github"
edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
site-url = "/example-book/"
cname = "myproject.rs"
input-404 = "not-found.md"

以下可用配置选项:

  • theme: mdBook附带了默认主题和所需的所有资源文件 为它。但是，如果设置了此选项，mdBook将有选择地覆盖主题 文件，其中包含在指定文件夹中找到的文件。
  • default-theme: 默认情况下要在 “更改主题”下拉列表。默认为“浅”。
  • preferred-dark-theme: 默认的深色主题。在以下情况下将使用本主题： 浏览器通过 'prefers-color-scheme' CSS 媒体查询。默认为navy.
  • curly-quotes: false.将直引号转换为卷引号，但那些 出现在代码块和代码中。默认值为false。
  • mathjax-support: 添加了对 MathJax 支持。默认值为 false。
  • copy-fonts: 将字体.css和相应的字体文件复制到输出目录，并在默认主题中使用它们。默认为true。
  • google-analytics: 此字段已被弃用，并将在将来的版本中删除。 使用 theme/head.hbs文件来添加相应的Google Analytics（分析）代码。
  • additional-css: 如果您需要稍微更改图书的外观 在不覆盖整个样式的情况下，您可以指定一组样式表， 将在默认的之后加载，您可以在其中更改 风格。
  • additional-js: 如果您需要在书中添加一些行为，而无需 删除当前行为，您可以指定一组 JavaScript 文件 将与默认一起加载。
  • no-section-label: 默认情况下，mdBook 会添加 内容列。例如，“1.”、“2.1”。将此选项设置为 true 可禁用 那些标签。默认值为false.
  • git-repository-url: 书籍的 git 存储库的 url。如果提供 图标链接将输出到书籍的菜单栏中。
  • git-repository-icon: 用于 git 的 FontAwesome 图标类 存储库链接。默认为fa-github，看起来像 . 如果你没有使用GitHub，另一个要考虑的选项是fa-code-fork，它看起来像.。
  • edit-url-template: 编辑网址模板（如果提供）显示 “建议编辑”按钮（看起来像）用于直接跳转到编辑当前 已查看页面。例如，对于 GitHub 项目，将其设置为 https://github.com/<owner>/<repo>/edit/master/{path}或 for Bitbucket 项目将其设置为 https://bitbucket.org/<owner>/<repo>/src/master/{path}?mode=edit 其中 {path} 将被替换为 存储 库。
  • input-404: 用于不存在的 markdown 文件的名称。 相应的输出文件将相同，扩展名将替换为“html”。 默认值为404.md。
  • site-url: 将托管图书的网址。这是确保 404 文件中的导航链接和脚本/css 导入可以正常工作，即使在访问 子目录中的网址。默认值为/
  • cname: 将托管图书的 DNS 子域或顶点域。 此字符串将写入站点根目录中名为 CNAME 的文件中，如下所示 GitHub Pages 所需的 (see Managing a custom domain for your GitHub Pages site).

[output.html.print]

[output.html.print] 表提供了用于控制可打印输出的选项。 默认情况下，mdBook 将在书籍的右上角包含一个图标（看起来像 ），该图标会将书籍打印为一页。

[output.html.print]
enable = true    # include support for printable output
page-break = true # insert page-break after each chapter
  • enable: 启用打印支持。当false时，所有打印支持将不会 呈现。默认为true。
  • page-break 在章节之间插入分页符。默认为true。

[output.html.fold]

The [output.html.fold] 表提供了用于控制导航侧栏中章节列表折叠的选项。

[output.html.fold]
enable = false    #是否启用截面折叠
level = 0         # 开始折叠的深度
  • enable: 启用截面折叠。关闭时，所有折叠都打开。 默认值为false。
  • level: 折叠区域越高，打开的区域就越多。当级别为 0 时，全部 褶皱是闭合的。默认值为 0。

[output.html.playground]

[output.html.playground] 提供了用于控制 Rust 示例代码块及其与 Rust Playground 集成的选项。

[output.html.playground]
editable = false         # 允许编辑源代码
copyable = true          # 包括用于复制代码片段的复制按钮
copy-js = true           # 包括代码编辑器的 JavaScript
line-numbers = false     # 显示可编辑代码的行号
runnable = true          # 显示Rust 代码的运行按钮
  • editable: 允许编辑源代码。默认值为 false.
  • copyable: 在代码段上显示复制按钮。默认值为 true.
  • copy-js: 将编辑器的 JavaScript 文件复制到输出目录。 默认值为 true.
  • line-numbers 在可编辑的代码段上显示行号。要求editable和copy-js都是true。默认值为
  • runnable 显示 Rust 代码段的运行按钮。将此更改为false将全局禁用在操场中运行功能。默认值为true.

[output.html.search]

[output.html.search] 表提供了用于控制内置文本 search的选项。 mdBook 必须在启用search功能的情况下进行编译（默认情况下处于打开状态）。

[output.html.search]
enable = true            # 启用搜索功能
limit-results = 30       # 最大搜索结果数
teaser-word-count = 30   # 用于搜索结果摘要的字数
use-boolean-and = true   # 多个搜索词必须全部匹配
boost-title = 2          # 标题中匹配项的排名提升因子
boost-hierarchy = 1      # 页面名称中匹配项的排名提升因素
boost-paragraph = 1      # 文本中匹配项的排名提升因素
expand = true            # 部分字词将与较长的字词匹配
heading-split-level = 3  # 将结果链接到标题级别
copy-js = true           # 包括用于搜索的 Javascript 代码
  • enable: 启用搜索功能。默认值为 true.
  • limit-results: 搜索结果的最大数量。默认值为 30.
  • teaser-word-count: 用于搜索结果摘要的字数。 默认值为 30.
  • use-boolean-and: 定义多个搜索词之间的逻辑链接。如果 true，所有搜索词都必须出现在每个结果中。默认值为 false.
  • boost-title: 如果搜索词，则搜索结果分数的提升因素 将显示在页眉中。默认值为 2.
  • boost-hierarchy: 如果搜索词，则搜索结果分数的提升因素 将显示在层次结构中。层次结构包含父级的所有标题 文档和所有父标题。默认值为 1.
  • boost-paragraph: 如果搜索词，则搜索结果分数的提升因素 将显示在文本中。默认值为 1.
  • expand: 如果搜索应匹配较长的结果，例如搜索micro，则为 true 应该匹配microwave。默认为“true”。
  • heading-split-level: 搜索结果将链接到文档的某个部分 其中包含结果。文档按标题分成几个部分 级别或更低。默认值为3. (### This is a level 3 heading)
  • copy-js: 将搜索实现的 JavaScript 文件复制到输出 目录。默认值为 true.

[output.html.redirect]

[output.html.redirect] 表提供了一种添加重定向的方法。 当您移动、重命名或删除页面以确保指向旧 URL 的链接将转到新位置时，这很有用。

[output.html.redirect]
"/appendices/bibliography.html" = "https://rustc-dev-guide.rust-lang.org/appendix/bibliography.html"
"/other-installation-methods.html" = "../infra/other-installation-methods.html"

该表包含键值对，其中键是需要创建重定向文件的位置，作为构建目录的绝对路径（例如/appendices/bibliography.html）。 该值可以是浏览器应导航到的任何有效 URI（例如，https://rust-lang.org/,/overview.html或../bibliography.html）。

这将生成一个HTML页面，该页面将自动重定向到给定位置。 请注意，源位置不支持# 锚点重定向。

Markdown Renderer

Markdown 渲染器将运行预处理器，然后输出结果 Markdown。这对于调试预处理器非常有用，尤其是在 与mdbook test结合使用，以查看mdbook正在通过的Markdown 到rustdoc。

Markdown 渲染器包含在 mdbook 中，但默认情况下处于禁用状态。 通过向book.toml添加一个空表来启用它，如下所示：

[output.markdown]

目前没有Markdown渲染器的配置选项。 仅启用还是禁用。

参考 the preprocessors documentation 有关如何操作 指定哪些预处理器应在 Markdown 渲染器之前运行。