野渡
搜索 K

主题

关系图谱

05_mdbook

1,494 字 5 分钟

mdBook 深度笔记（增强版） ​

1. 一句话定位 ​

mdBook 是 Rust 生态最成熟的书籍式文档工具，适合“按章节线性学习”的教程、课程和手册型内容。

2. 设计哲学与适用边界 ​

2.1 设计哲学 ​

  1. 把内容当“书”而非“门户”
  2. 章节顺序优先于复杂页面布局
  3. 低门槛构建和稳定阅读体验优先

2.2 适用边界 ​

适合：

  1. 教程、课程、学习路径型内容
  2. 需要线性阅读节奏的知识体系
  3. Rust 工具链偏好的作者

不适合：

  1. 强依赖复杂多语言和版本治理的文档平台
  2. 需要大量营销页和交互组件的门户站

3. 能力地图（Capability Map） ​

能力表现说明
章节化阅读强SUMMARY.md 提供明确阅读路径
上手成本强配置简洁，快速起步
搜索中内建基础搜索可用
主题定制中可改样式，但品牌化能力一般
i18n中低可实现但通常偏手工
版本化中低需依赖发布策略或多套构建
维护成本低长期维护友好

4. 架构与构建机制 ​

4.1 核心文件 ​

  1. book.toml：全局配置
  2. src/SUMMARY.md：章节目录
  3. src/*.md：正文内容

4.2 构建流程 ​

  1. 解析 book.toml
  2. 读取 SUMMARY.md 形成章节树
  3. 处理 Markdown 与预处理器
  4. 输出静态站点（默认 book/）

4.3 常用命令 ​

  • mdbook serve：开发预览
  • mdbook build：生产构建
  • mdbook test：代码块测试（可选）

5. 推荐目录结构 ​

text
my-book/
  book.toml
  src/
    SUMMARY.md
    index.md
    chapter-01/
      intro.md
      setup.md
    chapter-02/
      architecture.md
      practice.md
  theme/
    custom.css

建议：

  1. 目录按“卷/章/节”组织
  2. 文件名包含序号，便于长期维护
  3. 主题覆盖文件保持最小集

6. 配置详解（实践版） ​

toml
[book]
authors = ["your-name"]
language = "zh"
multilingual = false
src = "src"
title = "Engineering Handbook"

[build]
build-dir = "book"
create-missing = false

[output.html]
default-theme = "light"
preferred-dark-theme = "ayu"
copy-fonts = true
git-repository-url = "https://github.com/your-org/your-repo"
edit-url-template = "https://github.com/your-org/your-repo/edit/main/{path}"

关键点：

  1. create-missing=false 可减少误生成空文件
  2. edit-url-template 对公开协作非常有帮助
  3. 若做多语言，需在内容组织上提前规划

7. 内容工程与写作规范 ​

7.1 SUMMARY.md 示例 ​

md
# Summary

- [首页](./index.md)
- [第一章：基础](./chapter-01/intro.md)
  - [环境搭建](./chapter-01/setup.md)
- [第二章：实践](./chapter-02/architecture.md)
  - [案例拆解](./chapter-02/practice.md)

7.2 写作规范建议 ​

  1. 每章开头说明学习目标
  2. 每节结尾给出小结与练习
  3. 统一术语和代码示例风格
  4. 保持章节粒度一致

8. 搜索与导航优化 ​

  1. 标题命名具体，避免泛化词
  2. 章节首段给摘要，提升检索可读性
  3. 长章节拆分为多个节，降低跳读成本
  4. 增加“术语索引页”辅助检索

9. 多语言策略 ​

9.1 现实建议 ​

  1. 若是个人项目，优先单语言保证更新节奏
  2. 多语言项目建议拆分目录或拆分构建目标
  3. 术语表必须先行，否则翻译质量难稳定

9.2 协作建议 ​

  1. 翻译 PR 与原文 PR 分离
  2. 发布时检查语言缺失页
  3. 为每个语言设置维护责任人

10. 主题与样式定制 ​

10.1 定制顺序 ​

  1. 默认主题
  2. CSS 变量和少量样式覆盖
  3. 必要时再做主题深改

10.2 原则 ​

  1. 保证文本可读性优先
  2. 避免为了风格牺牲章节导航
  3. 深改前评估升级成本

11. 预处理器与扩展能力 ​

mdBook 的扩展亮点在预处理器：

  1. 可在构建前自动注入内容
  2. 可做链接校验、语法转换、术语替换
  3. 可与自定义工具链结合，形成内容流水线

建议：先用最小扩展，避免过早复杂化。

12. 性能、SEO 与可访问性 ​

  1. 章节拆分可降低单页体积
  2. 图片压缩和懒加载策略同样重要
  3. 标题层级规范有助 SEO 与可访问性
  4. 保证代码块和表格在移动端可阅读

13. CI/CD 与部署模板 ​

13.1 GitHub Actions 示例 ​

yaml
name: mdbook
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo install mdbook
      - run: mdbook build

13.2 发布建议 ​

  1. PR 构建检查章节完整性
  2. 主分支自动发布 book/
  3. 发布后自动做死链检测

14. 安全与治理 ​

  1. 固定构建工具版本
  2. 审阅外部脚本和第三方资源
  3. 避免文档仓库出现敏感信息
  4. 建立章节审校流程

15. 迁移路线图 ​

15.1 从零散 Markdown 到 mdBook ​

  1. 先按主题分卷
  2. 再写 SUMMARY.md
  3. 最后统一章节模板

15.2 从门户型框架迁回书籍结构 ​

  1. 保留核心学习路径
  2. 将页面式内容压缩为章节式叙事
  3. 通过索引页弥补门户导航能力

16. 成本预估（经验值） ​

  1. 最小可用：0.5~1 天
  2. 100 篇内容重组为章节体系：4~12 天
  3. 加入多语言和自动化校验：2~4 周

17. 常见坑与规避 ​

  1. SUMMARY.md 过长难维护
    做法：按卷拆分并保持层级简洁。

  2. 章节粒度不一致
    做法：定义章节模板和字数范围。

  3. 误把 mdBook 当门户系统
    做法：明确它是“书”导向工具。

18. 上线检查清单 ​

  1. 章节顺序正确
  2. 所有目录链接可达
  3. 关键术语已统一
  4. 移动端阅读可用
  5. 构建无错误

19. 学习路线建议（5~7 天） ​

  1. Day1：初始化并写目录
  2. Day2：完成两章完整示例
  3. Day3：统一写作模板
  4. Day4：接入 CI
  5. Day5：优化样式与可读性
  6. Day6-7：复盘并扩展预处理器

20. 官方资料 ​

  1. 仓库：https://github.com/rust-lang/mdBook
  2. 在线文档：https://rust-lang.github.io/mdBook/

21. 总结 ​

如果你的目标是“系统教学与连贯阅读”，mdBook 的体验往往优于通用文档站框架。它最擅长把知识组织成一条可持续学习路径。