当前位置：首页 > news >正文

【mdBook】5.2.1 通用配置

news 2025/9/29 5:52:06

您可以在 book.toml 文件中配置书籍的各项参数。

以下是一个 book.toml 文件的示例：

[book]
title = “示例书籍”
authors = [“张三”]
description = “本示例书籍涵盖各种示例。”

[rust]
edition = “2018”

[build]
build-dir = “我的示例书籍”
create-missing = false

[preprocessor.index]

[preprocessor.links]

[output.html]
additional-css = [“custom.css”]

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

支持的配置选项

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

通用元数据

这是关于书籍的基本信息。

title: 书籍的标题
authors: 书籍的作者（们）
description: 书籍的描述，将作为 meta 信息添加到每个页面的 HTML <head> 中
src: 默认情况下，源目录位于根目录下名为 src 的文件夹中。但可以通过配置文件中的 src 键进行配置。
language: 书籍的主要语言，用作语言属性，例如 <html lang="en">。这也用于推导书籍内文本的方向（RTL, LTR）。
text-direction: 书籍中文本的方向：从左到右（LTR）或从右到左（RTL）。可能的值：ltr, rtl。如果未指定，文本方向将从书籍的 language 属性推导得出。

book.toml 示例：

[book]
title = “示例书籍”
authors = [“张三”, “李四”]
description = “本示例书籍涵盖各种示例。”
src = “我的源文件” # 源文件将在 根目录/我的源文件 中找到，而不是 根目录/src
language = “zh”
text-direction = “ltr”

Rust 选项

与运行测试和 Playground 集成相关的 Rust 语言选项。

[rust]
edition = “2015” # 代码块的默认版本

edition: 代码片段默认使用的 Rust 版本。默认为 “2015”。单个代码块可以通过 edition2015、edition2018、edition2021 或 edition2024 注解来控制，例如：
```
// 这仅在 2015 版本中有效。
let try = true;
```

构建选项

这控制着书籍的构建过程。

[build]
build-dir = “book” # 放置输出文件的目录
create-missing = true # 是否创建缺失的页面
use-default-preprocessors = true # 是否使用默认预处理器
extra-watch-dirs = [] # 用于触发构建的额外监视目录

build-dir: 存放渲染后书籍的目录。默认是书籍根目录下的 book/ 文件夹。可以通过 --dest-dir 命令行选项覆盖此设置。
create-missing: 默认情况下，当构建书籍时，任何在 SUMMARY.md 中指定但缺失的文件都会被创建（即 create-missing = true）。如果设置为 false，那么如果任何文件不存在，构建过程将报错并退出。
use-default-preprocessors: 通过将此选项设置为 false 来禁用默认的预处理器（links 和 index）。
- 如果您通过配置表声明了相同和/或其他预处理器，它们将取而代之运行。
  - 为明确起见，在没有预处理器配置的情况下，默认的 links 和 index 会运行。
  - 设置 use-default-preprocessors = false 将阻止这些默认预处理器运行。
  - 添加 [preprocessor.links] 等配置将确保，无论 use-default-preprocessors 如何设置，links 预处理器都会运行。
extra-watch-dirs: 一个路径列表，指向在 watch 和 serve 命令中将被监视的目录。对这些目录下文件的更改将触发重新构建。当您的书籍依赖于其 src 目录之外的文件时非常有用。