mdbook-autosummary

根据您的文件夹结构为您的 mdBook 生成 SUMMARY.md！

[!WARNING] 实现方式较为粗糙，存在一些限制，更多信息请见 下面。

示例

src
├── bar
│   ├── chapter_5.md
│   ├── chapter_6.md
│   └── index.md
├── chapter_1.md
├── chapter_2.md
├── foo
│   ├── baz
│   │   ├── chapter_7.md
│   │   └── index.md
│   ├── chapter_3.md
│   ├── chapter_4.md
│   └── index.md
├── index.md
└── SUMMARY.md

变为

<!-- Generated by mdbook-autosummary v0.1.0 - do not edit manually! -->

[Home](index.md)
[Chapter 1](chapter_1.md)
[Chapter 2](chapter_2.md)
- [Section Bar](bar/index.md)
  - [Chapter 5](bar/chapter_5.md)
  - [Chapter 6](bar/chapter_6.md)
- [Section Foo](foo/index.md)
  - [Chapter 3](foo/chapter_3.md)
  - [Chapter 4](foo/chapter_4.md)
  - [Section Baz](foo/baz/index.md)
    - [Chapter 7](foo/baz/chapter_7.md)

安装

二进制文件

二进制文件可在所有主要平台的 GitHub 发布部分 获取。

从源代码安装

要从源代码安装，您需要一个可工作的 Rust 工具链 安装。

安装工具链后，运行

cargo install mdbook-autosummary

使用方法

要使用预处理器，请将以下内容添加到您的 book.toml 文件中

[preprocessor.autosummary]

# This is so that mdBook doesn't start regenerating 
# deleted folders before autosummary can remove them from SUMMARY.md
[build]
create-missing = false

此外，建议将 SUMMARY.md 添加到 .gitignore。

要求

• 您想要包含在 SUMMARY.md 中的所有文件夹 必须 包含一个 index.md（或等效）文件。这是将链接到 SUMMARY.md 的文件。
  • 没有 index.md（或等效）的文件夹将被忽略。
• 所有文件都应从 h1（#）标题开始，该标题将用作 SUMMARY.md 中页面的标题。
  • 如果找不到 h1 标题，则将使用文件/文件夹的名称作为后备。

与其他预处理器一起使用

[!WARNING] 这 必须 是第一个运行的预处理器，否则其他预处理器的输出可能会被忽略！

为确保这一点，请将以下内容添加到 book.toml 文件中的其他预处理器

[preprocessor.foo]
after = ["autosummary"]

配置

所有配置选项都是可选的，并位于 book.toml 中的 preprocessor.autosummary 表格下。

[preprocessor.autosummary]
# Controls the name of the index.md file that is looked for in each folder.
index-name = "index.md"
# If true, files that start with . or _ are ignored.
ignore-hidden = true

限制

当运行 mdbook build 时，如果不存在 SUMMARY.md 或无效，mdBook 默认在调用任何预处理器之前失败构建。

这有以下影响

• 在删除之前位于 SUMMARY.md 中的文件或文件夹时，必须手动清空或截断 SUMMARY.md，以强制重新生成。
• 在运行 mdbook build 之前，必须存在一个 SUMMARY.md，即使它是空的。

因此，建议不要将 SUMMARY.md 提交到源代码控制，并将其添加到 .gitignore。此外，在 CI/CD 中，在运行 mdbook build 之前，必须创建一个空的 SUMMARY.md，即使启用了此预处理器也是如此。

它是如何工作的？

由于预处理器不应该直接修改 SUMMARY.md，因此内部工作方式相当“狡猾”。

当调用预处理器时，它会在内存中生成一个新的 SUMMARY.md 并将其与现有文件进行比较。如果不匹配，则生成的文件将覆盖现有文件，并且整本书将从磁盘重新加载。如果它们匹配，则预处理器不执行任何操作。据我所知，这是强制 mdBook 重新解析 SUMMARY.md 文件的唯一方法，除非您从头开始解析和构建 Book 对象。

此方法的副作用是，当 SUMMARY.md 发生变化时，mdBook 被迫重新加载整本书，并且可能会多次调用一些预处理器。（如果它们在 mdbook-autosummary 之前定义）此外，由于这是一个预处理器，它会在构建每个后端时调用，尽管使用了文件哈希比较来避免不必要的操作。

为什么不直接告诉 mdBook 使用您生成的新的摘要呢？

在 mdBook 中存在一个用于执行此操作的函数 存在，但遗憾的是它是私有的。鉴于此预处理器的狡猾性质，我认为不值得费力向 mdBook 提交一个 PR 以使其公开，相反，应探索此问题的替代方法。（例如，添加将摘要的来源指定为扩展/预处理器而不是文件的能力）

贡献

欢迎贡献！如果您有任何建议或改进，请打开一个问题或 PR。

创建新版本

1. 更新 Cargo.toml 中的版本
2. 更新 CHANGELOG.md
3. 推送一个新的标签，版本号前缀为 v（例如 v0.1.0）
4. CD 将自动构建并将新版本发布到 crates.io 和 github