配置

您可以在 book.toml 文件中配置图书的参数.

这是一个 book.toml 文件示例，如下所示:

  1. [book]
  2. title = "Example book"
  3. author = "John Doe"
  4. description = "The example book covers examples."
  6. [build]
  7. build-dir = "my-example-book"
  8. create-missing = false
  10. [preprocessor.index]
  12. [preprocessor.links]
  14. [output.html]
  15. additional-css = ["custom.css"]
  17. [output.html.search]
  18. limit-results = 15

支持的配置选项

重要的是要注意到，配置中指定的任何相对路径，都是相对于配置文件所在的书籍的根目录.

通用元数据

这是有关您图书的一般

信息描述
title这本书的标题
author本书的作者
description该书的描述,作为元信息,添加在每页 html 的<head>
src默认情况下,源目录位于名为src的目录中(在根文件夹)。但这src是可配置的，就在book.toml。
language:国家语言, 例如用在网页的 <html lang=”en”> 属性。

book.toml

  1. [book]
  2. title = "Example book"
  3. authors = ["John Doe", "Jane Doe"]
  4. description = "The example book covers examples."
  5. src = "my-src"  # 源文件夹，用 `root/my-src` 替代 `root/src`
  6. language = "zh-CN"

Build 选项

这可以控制您图书的构建过程.

  • build-dir | 放置渲染图书的目录。默认情况下在根目录的book/:

  • create-missing | 默认情况(create-missing = true)下，在书籍建成时，会创建SUMMARY.md中缺失的文件。如果是false，则有文件不存在,那么构建过程将以错误退出。

  • use-default-preprocessors | 设为 false，会禁用(links&index)的默认预处理器。

    如果您通过配置文件声明了，相同的和/或其他预处理器,由它们主导.

    • 为清楚起见,没有预处理器配置,默认links和index运行.
    • 设置use-default-preprocessors = false，将禁用这些默认预处理器运行.
    • 若添加[preprocessor.links]，那无论如何,都能确保use-default-preprocessors运行links。

配置,预处理器

默认情况下,以下预处理器运行，并包含:

  • links:扩展章节中{{ #playpen }}和{{ #include }}控制条，能帮助引入文件的内容.
  • index:将所有名为README.md的章节文件转换index.md。也就是说,所有README.md将被渲染成index.html，在渲染的书中.

book.toml

  1. [build]
  2. build-dir = "build"
  3. create-missing = false
  5. [preprocessor.links]
  7. [preprocessor.index]

自定义预处理器配置

与渲染器一样,预处理器需要有自己的表格(例如[preprocessor.mathjax])。在该部分中,您可以通过向特有表中，添加键值对来将额外配置传递给预处理器.

例如

  1. [preprocessor.links]
  2. # 设置此预处理器将运行的渲染器
  3. renderers = ["html"]
  4. some_extra_feature = true

锁住一个预处理依赖给一个渲染器

您可以通过将两者绑定在一起，显式指定预处理器将运行的渲染器

  1. [preprocessor.mathjax]
  2. renderers = ["html"]  # mathjax 只HTML渲染合作

添加你的命令

默认情况下,添加[preprocessor.foo]到你的book.toml文件,mdbook将尝试调用mdbook-foo启动。如果你想使用不同的程序名 或传递一个命令行参数。这些都能通过command字段覆盖完成。

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

配置渲染器

HTML 渲染器选项

HTML 渲染器也有几个选项,在 TOML 下指定渲染器的所有选项.

[output.html]可以使用以下配置选项:描述
thememdBook 附带一个默认主题，及其所需的所有资源文件.但是如果设置了此选项,mdBook 将选择性地使用，能在指定文件夹中找到的主题文件，覆盖主题文件。
default-theme默认情况下在”更改主题”下拉列表中，选择的主题颜色方案。默认为light。
curly-quotes将直引号转换为反引号,除了代码块和代码 spans 中出现的引号。默认为false。
mathjax-support:增加对 MathJax 的支持。 默认是

false。 google-analytics | 如果您使用 Google Analytics,则可以通过在配置文件中指定 ID 来启用此选项。 additional-css | 如果您需要稍微更改图书的外观，而不覆盖整个样式,则可以指定一组 css 样式表,这些样式表将在默认情况下加载,这样您就通过’外科手术’更改样式。 additional-js | 如果您需要在不删除当前行为的情况下，向书中添加某些行为,则可以指定一组，将与默认文件一起加载的 JavaScript 文件。 no-section-label | 默认情况下,mdBook 在目录列中，添加章节标签编号。例如,”1.”,”2.1”。将此选项设置为 true 可禁用这些标签.默认为false。 playpen | 用于配置各种 playpen 设置的子表。 search | 用于配置浏览器内搜索功能的子表。mdBook 必须启用search功能编译(默认情况下已启用)。 git-repository-url | 这本书的 git 存储库的 URL。如果提供,将在书的菜单栏中，输出图标链接。 git-repository-icon | 用于 git 存储库链接的 FontAwesome 图标类。默认为fa-github.

[output.html.playpen]可用的配置选项表:描述
editable允许编辑源代码。默认为false。
copy-js将编辑器的 JavaScript 文件，复制到输出目录。默认为true.
[output.html.search]可用的配置选项表:描述
enable启用搜索功能.默认为true。
limit-results搜索结果的最大数量.默认为30。
teaser-word-count搜索结果预告的单词数。默认为30。
use-boolean-and定义多个搜索词之间的逻辑链接。如果为 true,则所有搜索词必须出现在每个结果中。默认为true。
boost-title如果标题中出现搜索词,则提升搜索结果。默认为2。
boost-hierarchy如果搜索结果出现在层次结构中,则提升搜索结果。层次结构包含父文档的所有标题，和所有父标题。默认为1。
boost-paragraph如果搜索词出现在文本中,则提升搜索结果。默认为1。
expand默认搜索匹配更长的结果。搜索micro应该匹配microwave。默认为true。
heading-split-level搜索结果将链接到包含结果的文档部分。文档按此级别或更低级别划分为多个部分。默认为3.(### This is a level 3 heading)
copy-js将搜索实现的 JavaScript 文件，复制到输出目录。默认为true.

这显示了book.toml所有可用的 HTML 输出选项:

  1. [book]
  2. title = "Example book"
  3. authors = ["John Doe", "Jane Doe"]
  4. description = "The example book covers examples."
  6. [output.html]
  7. theme = "my-theme"
  8. default-theme = "light"
  9. curly-quotes = true
  10. mathjax-support = false
  11. google-analytics = "123456"
  12. additional-css = ["custom.css", "custom2.css"]
  13. additional-js = ["custom.js"]
  14. no-section-label = false
  15. git-repository-url = "https://github.com/rust-lang-nursery/mdBook"
  16. git-repository-icon = "fa-github"
  18. [output.html.playpen]
  19. editable = false
  20. copy-js = true
  22. [output.html.search]
  23. enable = true
  24. limit-results = 30
  25. teaser-word-count = 30
  26. use-boolean-and = true
  27. boost-title = 2
  28. boost-hierarchy = 1
  29. boost-paragraph = 1
  30. expand = true
  31. heading-split-level = 3
  32. copy-js = true

Markdown 渲染器

Markdown 渲染器会运行预处理器，再输出结果的 Markdown。 最大的用途就是调试预处理器, 尤其是，可以结合 mdbook test看到，mdbook 传递给rustdoc的 Markdown 文本。

Markdown 渲染器 已包含在 mdbook ，但默认禁用。 启用方式，是在book.toml中，添加:

  1. [output.markdown]

现在还没有配置选项; 只能开和关

查看 preprocessors 文档 ，关于如何指定哪个 preprocessors 应在 the Markdown renderer 之前运行。

自定义 Renderers

可以通过添加一个[output.foo]表到你的book.toml，来启用自定义渲染器。与preprocessors相似，指示mdbook将书的表达传递给mdbook-foo渲染.

自定义渲染器可以访问其表中的所有配置(即,在其[output.foo]下的任何内容),并且可以使用command字段手动指定要调用的命令.

环境 变量

通过设置相应的环境变量,命令行的运行，覆盖到所有配置值。因为许多操作系统将环境变量限制为_字母数字字符,配置字段需要格式化成，正常情况的foo.bar.baz形式。

变量以MDBOOK_开头配置。通过删除MDBOOK_前缀，并将结果字符串转换为kebab-case。双下划线(__)变. ，而单个下划线(_)用短划线代替(-).

例如:

  • MDBOOK_foo -> foo
  • MDBOOK_FOO -> foo
  • MDBOOK_FOO__BAR -> foo.bar
  • MDBOOK_FOO_BAR -> foo-bar
  • MDBOOK_FOO_bar__baz -> foo-bar.baz

所以通过设置MDBOOK_BOOK__TITLE环境变量,你可以覆盖书的标题,而无需修改你的book.toml.

注意 为了便于设置更复杂的配置项,首先将环境变量的值解析为 JSON,如果解析失败，则返回到字符串.

这意味着,如果您愿意,可以在构建书籍时覆盖所有书籍元数据

  1. $ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
  2. $ mdbook build

后一种情况，在以下情况下可能有用，

  • 脚本或 CI 调用mdbook,
  • 有时在构建前，无法更新book.toml.