【mdBook】6 在持续集成中运行 mdbook

有多种服务（如 GitHub Actions 或 GitLab CI/CD）可用于自动测试和部署您的书籍。

以下提供了一些关于如何配置服务来运行 mdBook 的通用指南。具体的使用方法可以在"自动部署" Wiki 页面找到。

安装 mdBook

有几种不同的安装 mdBook 的策略。具体方法取决于您的需求和偏好。

预编译二进制文件

也许最简单的方法是使用 GitHub Releases 页面上的预编译二进制文件。一个简单的方法是使用流行的 curl 命令行工具下载可执行文件：

bash 复制代码

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 版本。例如：

bash 复制代码

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 设置如下：

toml 复制代码

# book.toml
[output.html]
site-url = "/mdBook/"

自定义 404 页面

您可以通过在书籍中创建名为 src/404.md 的文件来自定义 404 页面的外观。如果要使用不同的文件名，可以将 output.html.input-404 设置为其他文件名。