【mdBook】6 在持续集成中运行 mdbook
有多种服务（如 GitHub Actions 或 GitLab CI/CD）可用于自动测试和部署您的书籍。
以下提供了一些关于如何配置服务来运行 mdBook 的通用指南。具体的使用方法可以在"自动部署" Wiki 页面找到。
安装 mdBook
有几种不同的安装 mdBook 的策略。具体方法取决于您的需求和偏好。
预编译二进制文件
也许最简单的方法是使用 GitHub Releases 页面上的预编译二进制文件。一个简单的方法是使用流行的 curl 命令行工具下载可执行文件：
mkdir bin
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.52/mdbook-v0.4.52-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
bin/mdbook build
这种方法的考虑因素：
- 速度较快，不一定需要处理缓存
- 不需要安装 Rust
- 指定特定 URL 意味着您必须手动更新脚本以获取新版本。如果您想锁定特定版本，这可能是一个好处。但有些用户更喜欢在发布时自动获取新版本
- 依赖 GitHub CDN 的可用性
从源码构建
从源码构建需要安装 Rust。有些服务已预装 Rust，但如果您的服务没有，则需要添加安装步骤。
安装 Rust 后，可以使用 cargo install 来构建和安装 mdBook。我们建议使用 SemVer 版本说明符，以便获得最新的不破坏兼容性的 mdBook 版本。例如：
cargo install mdbook --no-default-features --features search --vers "^0.4" --locked
这包含几个推荐选项：
| 选项 | 说明 |
|---|---|
--no-default-features | 禁用 CI 上可能不需要的功能（如 mdbook serve 使用的 HTTP 服务器），显著加快构建时间 |
--features search | 禁用默认功能后，应手动启用所需功能（如内置搜索功能） |
--vers "^0.4" | 安装 0.4 系列的最新版本，但不会安装 0.5.0 等后续版本（可能破坏构建） |
--locked | 使用 mdBook 发布时使用的依赖版本，避免使用最新依赖可能导致的构建问题 |
您可能需要研究缓存选项，因为构建 mdBook 可能有些慢。
运行测试
您可能希望在每次推送更改或创建拉取请求时使用 mdbook test 运行测试。这可用于验证书中的 Rust 代码示例。
这需要安装 Rust。有些服务已预装 Rust，但如果您的服务没有，则需要添加安装步骤。
除了确保安装适当版本的 Rust 外，只需从书籍目录运行 mdbook test 即可。
您可能还想考虑运行其他类型的测试，例如：
mdbook-linkcheck：检查损坏的链接- 自定义样式检查、拼写检查器或其他测试
部署
您可能希望自动部署您的书籍。有些人可能希望在每次推送更改时部署，而其他人可能只想在标记特定版本时部署。
您还需要了解如何将更改推送到 Web 服务的具体细节。例如：
- GitHub Pages：只需要将输出提交到特定的 git 分支
- 其他服务：可能需要使用 SSH 等方式连接到远程服务器
基本流程是运行 mdbook build 生成输出，然后将文件（位于 book 目录中）传输到正确的位置。
您可能还需要考虑是否需要在 Web 服务上使任何缓存失效。
有关各种不同服务的示例，请参阅"自动部署" Wiki 页面。
404 处理
mdBook 会自动生成用于损坏链接的 404 页面。默认输出是位于书籍根目录下名为 404.html 的文件。
- GitHub Pages 等服务会自动将此页面用于损坏链接
- 其他服务可能需要配置 Web 服务器使用此页面，以便为读者提供返回书籍的导航
站点 URL 配置
如果您的书籍未部署在域的根目录下，则应设置 output.html.site-url，以便 404 页面正常工作。它需要知道书籍的部署位置才能正确加载静态文件（如 CSS）。
示例：本指南部署在 https://rust-lang.github.io/mdBook/，站点 URL 设置如下：
# book.toml
[output.html]
site-url = "/mdBook/"
自定义 404 页面
您可以通过在书籍中创建名为 src/404.md 的文件来自定义 404 页面的外观。如果要使用不同的文件名，可以将 output.html.input-404 设置为其他文件名。