mdbook-fs-summary

一个预处理程序，它从您的书籍的文件结构中生成摘要，而不是使用显式的 SUMMARY.md 文件。

优势

通常，您希望您的文件组织在 SUMMARY.md 文件中简单地反映出来，而不是手动设置它。我们可以通过遵循一些约定来自动化这一过程

这些约定应该创建一个文件系统结构，当按字母数字排序时，在最终渲染中是相同的。

00_prologue.md                    → prefix chapter
01_intro.md
02_install/
├─ 00.md                          → chapter index 
├─ 01_linux.md
├─ 02_mac.md                      ↓ files sorted naturally
├─ 03_windows.md
├─ 04_______                      → separator
├─ 05_post_install.md
├─ _common_install_tips.md        → ignored "partial"
03_caveat.md
04_##_guide_##.md                 → part title 
05_usage.md/
├─ 00.md
├─ 01_basics/
│  ├─ 00.md
│  ├─ 01_setup.md
│  ├─ 02_monitoring.md
06_administration()/              → draft chapter
├─ 00.md
├─ 01_install().md                → nested draft chapter
ZZ_final_words.md                 → suffix chapter

用法

您必须创建一个虚拟的 SUMMARY.md 文件，否则在调用预处理器之前，mdbook 将出错。 (内容不重要。它只需在第一行有 # SUMMARY 即可。)

使用 cargo 安装项目。当前版本是 v0.2.1。

cargo install mdbook-fs-summary

目前没有太多配置。

# book.toml

[preprocessor.fs-summary]
# (default: true)
clean-paths = true

# other preprocessors will naturally need to 
# run after the summary has been generated 
[preprocessor.links]
after = ["fs-summary"] 

清洁路径

我们正在使用文件名指示符来应用对生成的摘要的配置。这并不理想，因此它们被剥离为它们的自然路径。

而不是

http://127.0.0.1:3000/02_team/05_onboarding.html

我们剥离了用于排序的数字前缀以及任何其他人工指示符。

http://127.0.0.1:3000/team/onboarding.html

⚠️ 清洁路径目前破坏了对 mdbook 提供的默认链接预处理器支持。 查看这个请求。 如果您打算使用部分内容，建议在解决这个问题之前禁用清洁路径。

禁用清洁路径

您可以关闭此行为。

[preprocessor.fs-summary]
clean-paths = false

[preprocessor.links]
after = ["fs-summary"]

数字前缀格式

此处理器不指定用于排序的数字前缀的任何特殊格式，除非在清洁路径时。目前惯例是这种格式

如果文件名以 2 或 3 个数字或大写字母开头，后面跟一个下划线，则它们将在生成的 URL 中被删除。

如果您计划为文件名制定其他排序策略，请注意这一点。

替代方案

• mdbook-auto-gen-summary - 具有类似目标但不同约定，并将生成的目录表写入 SUMMARY.md。