mdBook：Rust 官方出的 Markdown 文档生成器，28MB 搞定一切
做技术文档有很多选择。GitBook、VuePress、Docusaurus、Read the Docs……每个都要装一堆依赖，配半天才能跑起来。
mdBook 是 Rust 官方团队维护的文档工具，安装包只有 28MB，一条命令就能把 Markdown 文件变成一本带搜索、带导航的在线图书。Rust 官方文档就是用 mdBook 生成的。
它解决的问题很简单：你有一堆 Markdown 文件，想快速变成一本结构化的电子书——不需要数据库、不需要 Node.js、不需要编译前端。
为什么值得关注
极简主义者的福音。 装 mdBook 就是下载一个单文件二进制，没有任何运行时依赖。不像 GitBook 要 Node.js 和 npm，不像 VuePress 要装一整堆前端工具链。
Rust 官方背书。 项目由 Rust 核心团队维护，GitHub 上 21000+ Star。Rust 官方编程指南（The Rust Book）、Rust 参考手册、Rust 宏指南等几十本官方文档都在用。
开箱即用。 装好之后的命令就几个——mdbook init、mdbook build、mdbook serve。一个 SUMMARY.md 定义目录结构，剩下的全是 Markdown。
核心功能
全文搜索。 内置搜索功能，不需要配任何第三方搜索服务。纯 JavaScript 实现，所有索引文件在构建时生成，离线也能用。
代码高亮。 内置语法高亮，支持主流编程语言。
多主题。 默认主题简洁干净，也可以自定义样式。
数学公式。 通过 KaTeX 支持 LaTeX 数学公式渲染，适合文档中有公式的场景。
多语言。 支持多语言文档的构建和切换，一本技术书可以同时出英、中、日等多个版本。
自定义预处理。 可以通过预处理插件扩展 Markdown 语法——比如自动编号、链接检查、代码测试等。Rust 社区有不少现成的 preprocessor。
输出格式。 默认输出 HTML，但也可以通过插件输出 PDF、EPUB 等格式。
实时预览。 mdbook serve 启动本地服务器，文件变化自动刷新浏览器。
安装和使用
# macOS / Linux
curl -fsSL https://sh.rustup.rs | sh # 如果没有 Rust
cargo install mdbook
# 或者直接下载二进制
# 从 GitHub Releases 页面下载对应平台的二进制文件
# 通过包管理器
brew install mdbook # macOS
创建一个新文档项目：
mdbook init my-document
cd my-document
目录结构：
my-document/
├── book/ # 构建输出目录
├── src/ # Markdown 源文件
│ ├── chapter_1.md
│ └── SUMMARY.md # 目录定义文件
└── book.toml # 配置文件
SUMMARY.md 定义图书目录：
# Summary
[前言](README.md)
- [第一章：入门](chapter_1.md)
- [第二章：进阶](chapter_2.md)
- [第二节：高级用法](chapter_2/advanced.md)
构建和预览：
mdbook build # 构建输出到 book/ 目录
mdbook serve # 打开 http://localhost:3000 实时预览
mdbook clean # 清理构建产物
使用场景
我见过 mdBook 被用在不少地方：
- 开源项目文档 — 比 GitHub Wiki 好用，可以自定义域名
- 团队知识库 — Markdown 写文档，git 管理版本，CI 自动构建发布
- 技术书籍写作 — 先写 mdBook 版本，再考虑出版
- API / SDK 文档 — 搭配代码注释生成工具使用
- 课程教材 — 纯 Markdown，学生只需要浏览器
对比其他方案：
| 工具 | 依赖 | 安装包 | 学习成本 | 搜索 |
|---|
| mdBook | 无 | 28MB | 低 | 内置 |
| GitBook | Node.js | ~200MB | 中 | 内置 |
| VuePress | Node.js + npm | ~300MB | 中高 | 插件 |
| Docusaurus | Node.js + npm | ~400MB | 高 | 插件 |
| Sphinx | Python + pip | ~150MB | 中高 | 插件 |
我的看法
mdBook 不是什么新东西，2018 年就发布了，到今天已经是一个很成熟的项目。
但它的定位一直很清晰——如果你只需要用 Markdown 写文档，不想要复杂的前端框架，不想折腾构建工具链，mdBook 就是最佳选择。
它不做笔记、不做 CMS、不做博客。就是专注地把 Markdown 变成一本好看的书。这种「小而精」的思路，跟 Rust 语言本身的哲学一脉相承。
28MB 的大小在 2026 年听起来有点复古，但这恰恰是它的优势——装完即用，零配置，没有任何依赖烦恼。
如果你正在做一个开源项目需要写文档，或者团队需要一个轻量级的知识库工具，试试 mdBook。大概花 5 分钟就能上手。