mdBook 评测：2.1万星的Rust文档工具，用Markdown写书

写技术文档的人一定对 GitBook 不陌生。当年它从免费开源转向收费闭源的时候，不少人想找替代方案。mdBook 就是 Rust 官方团队给出的答案 —— 21k+ Star，用 Markdown 写书，输出漂亮的静态网站。

Rust 官方文档、Rust Cookbook、甚至很多开源项目的文档都是用它生成的。质量有保障。

它到底解决什么问题

用 Markdown 写书或长文档，自动生成交互式在线阅读站点。

不需要懂前端，不需要配构建工具。你只管写 Markdown 文件，mdBook 负责生成带目录导航、搜索、代码高亮、主题切换的完整网站。

典型场景：

• 技术书籍（Rust 官方教程就是例子）
• 项目文档
• API 文档站点
• 知识库
• 课程教材

核心功能

Markdown 原生支持 不需要学习新语法，就是标准 Markdown。支持代码块高亮、表格、数学公式（通过插件）。对写作者来说零门槛。

自动目录导航 按照 SUMMARY.md 中定义的章节顺序，自动生成左侧目录树。支持多级嵌套章节。读者可以像翻书一样浏览。

内置搜索 不需要额外配置 Algolia 或 Elasticsearch。mdBook 自带全文搜索，基于客户端索引，搜索速度挺快。

多主题 默认主题简洁干净，支持暗色/亮色切换。也可以通过自定义 CSS 和 JS 扩展样式。不少项目用它做出了很有辨识度的文档站。

代码可执行 这个挺有意思。通过插件支持，书中的代码块可以直接运行。Rust 官方教程里有些示例代码是可以点击运行的，用的就是这个功能。

插件系统 支持自定义预处理器和渲染器。可以做很多扩展：自动生成 API 文档、集成测试、自定义输出格式等。

实际使用场景

写开源项目文档 我给自己的几个项目用 mdBook 搭了文档站。配置简单，部署到 GitHub Pages 一条命令搞定。比 Sphinx 轻量多了。

整理技术笔记 把零散的技术笔记整理成一本”书”。SUMMARY.md 当目录，每篇笔记一个 Markdown 文件。读起来有体系，不像 wiki 那么散。

课程材料 给朋友公司做过内部培训，用 mdBook 整理了一套入门教程。学员反馈说”像看在线书一样，比发 PDF 方便”。

快速上手

安装（需要 Rust 环境）：

cargo install mdbook

创建新书：

mdbook init my-book
cd my-book

目录结构：

my-book/
├── book.toml      # 配置文件
├── src/
│   ├── SUMMARY.md # 目录结构
│   ├── chapter_1.md
│   └── chapter_2.md

编辑 SUMMARY.md 定义章节：

# Summary

- [第一章](chapter_1.md)
- [第二章](chapter_2.md)

构建：

mdbook build    # 生成到 book/ 目录
mdbook serve    # 本地预览，带热更新

优缺点

优点：

• 纯 Markdown，写作者零学习成本
• 生成的站点美观、专业
• 搜索、目录、主题切换开箱即用
• Rust 官方背书，持续维护
• 插件系统扩展性强

缺点：

• 需要 Rust 环境才能安装
• 对非技术用户来说，cargo 安装有门槛
• 多语言支持需要额外配置
• 没有内置的在线编辑功能（不像 GitBook 那样可以直接在网页上改）

跟 GitBook 比怎么样

	mdBook	GitBook
价格	免费开源	收费（有免费额度）
托管	自建/任意静态托管	GitBook 平台
编辑	本地 Markdown	在线 WYSIWYG
定制性	高	低
搜索	内置	内置

如果你希望完全控制文档站点、不想被平台绑定，mdBook 是更好的选择。如果你需要非技术人员也能在线编辑，GitBook 更合适。

适合谁用

• 开源项目维护者，想搭建专业文档站
• 技术作者，用 Markdown 写书
• 团队内部知识库建设
• 喜欢静态站点、不想依赖第三方平台的人

mdBook 属于那种”配置一次，长期受益”的工具。前期花 10 分钟搭好框架，后面只管写内容就行。Rust 团队自己都在用，靠谱。

---

关于作者

柳钉鱼，全栈开发者，GitHub 重度用户。过去 3 年 Star 了 900+ 仓库，这里只写我真正用过或深度调研过的工具。

📧 发现好工具想推荐？发邮件到 [email protected]