SEO中文网

Appearance

mdBook ​

什么是mdBook ​

mdBook 是 Rust 官方团队开发维护，专门用来把 Markdown 生成在线电子书、技术文档的静态站点生成器，大名鼎鼎的《The Rust Programming Language》（Rust圣经）就是用 mdBook 构建出来的。 定位偏向书籍、教程、API手册、项目文档，不是博客系统。许可证 MPL‑2.0，GitHub 开源项目。

起源与历史 ​

  • 由 rust‑lang 组织维护，诞生目的：为 Rust 官方教程提供构建工具。
  • 早期替代笨重的 GitBook，GitBook Node 依赖重、构建慢；mdBook 使用 Rust 重写，单二进制程序，无 Node 环境依赖。
  • 持续迭代，现在广泛用于 Rust 生态项目文档，很多开源项目直接用它写教程。

mdBook技术栈 ​

  • 核心本体：Rust 语言编写，编译成独立可执行文件，Windows/Linux/macOS 全平台单文件程序。
  • 模板引擎：Handlebars
  • 前端：少量 JS + CSS，默认主题 JS 体积很小。
  • 源文件：纯 Markdown。
  • 配置文件格式：TOML，和 Cargo 配置格式一样。
  • 输出产物：纯静态 HTML、CSS、JS，没有服务端代码，可以直接丢 GitHub Pages / Netlify / Vercel 部署。

mdBook核心特点 ​

  1. 构建速度极快 Rust 实现，几百个 md 文件也秒级构建，内存占用很低，没有 Node 一堆依赖包。
  2. 开箱即用客户端全文搜索 不需要后端服务器，构建时就把索引打包进静态页面，浏览器本地完成搜索，中文也支持。
  3. Rust 代码块专属能力mdbook test 可以直接跑文档里的 Rust 代码片段，自动校验示例代码能不能编译运行，保证教程代码不会过时失效，这个是它独有的王牌功能。
  4. 内置开发服务器 + 热重载mdbook serve 启动本地预览，保存 md 文件自动重新构建刷新浏览器。
  5. 目录完全受控于 SUMMARY.md 导航目录不是扫描文件夹，完全靠 SUMMARY.md 文件手动编排章节顺序，和旧版 GitBook 逻辑几乎一样。
  6. 基础能力内置 暗色模式切换、代码语法高亮、打印视图（单页全部文档）、上一页下一页导航。
  7. 扩展能力 支持预处理器插件、自定义主题CSS，第三方插件可以输出 PDF、EPUB 电子书格式。

mdBook优点 ​

  • ✅ 零依赖：只需要一个 mdbook 二进制，不需要 Node、npm，项目目录干净，没有 node_modules。
  • ✅ 性能优秀，大型文档构建快，启动预览流畅。
  • ✅ 对 Rust 项目极度友好，代码片段测试非常实用。
  • ✅ 上手门槛极低：只有 book.toml + src/SUMMARY.md 两个核心配置。
  • ✅ 输出纯静态产物，部署简单，几乎所有静态托管平台都兼容。
  • ✅ 默认主题简洁清爽，阅读体验好。

mdBook缺点 ​

  • ❌ 扩展能力偏弱：不像 VitePress 可以直接嵌入 Vue 组件；mdBook 很难写复杂交互组件，要写预处理器插件开发成本高。
  • ❌ 只适合书籍/文档，不适合做博客，没有标签、分类、文章列表原生支持。
  • ❌ Markdown 是标准 CommonMark，高级语法支持有限，表格、数学公式需要额外插件。
  • ❌ 主题生态少，自定义界面样式只能改 CSS，没有丰富主题市场。
  • ❌ 目录必须手动维护 SUMMARY.md，不能自动扫描 md 文件生成侧边栏。

安装 mdBook ​

前提：安装 Rust 环境（cargo），一条命令完成安装

bash
cargo install mdbook

验证是否成功

bash
mdbook --version

没有 Rust 环境：可以直接去 GitHub Releases 下载各平台二进制可执行文件。

创建mdBook项目 ​

  1. 初始化项目
bash
mdbook init my_docs

交互提示会问：是否生成 .gitignore、填写书籍标题。

  1. 生成的目录结构
my_docs/
├── book.toml        # 主配置文件（标题、作者、语言等）
├── book/            # 构建输出目录，生成好的静态网页在这里
└── src/             # 所有markdown源码目录
    ├── SUMMARY.md   # 最重要！侧边栏目录大纲
    └── chapter_1.md
  1. 简单示例 book.toml
toml
[book]
title = "Rust学习笔记"
authors = ["你的名字"]
language = "zh"
description = "Rust学习教程文档"
  1. SUMMARY.md（控制侧边栏导航）
markdown
# 目录

- [第一章 基础](chapter_1.md)
- [第二章 结构体](chapter_2.md)
    - [2.1 结构体方法](chapter2/method.md)
- [附录](appendix.md)
  1. 本地预览开发
bash
mdbook serve --open

浏览器自动打开 http://localhost:3000，修改md保存，页面自动刷新。

  1. 构建静态网页
bash
mdbook build

输出全部静态文件到 book/ 文件夹，把 book 目录部署到网站即可。

  1. Rust 代码示例测试（特色功能）
bash
mdbook test

自动执行文档中所有rust代码块，检测代码报错。

mdBook vs VitePress对比 ​

项目mdBookVitePress
底层RustVite + Vue3
依赖单二进制，无依赖需要Node环境
嵌入组件很难，靠插件直接写Vue组件
搜索内置客户端搜索内置搜索
Rust代码测试原生支持不支持
目录管理SUMMARY.md手动写可自动扫描文件
JS交互弱强，适合交互文档

适合 & 不适合场景 ​

适合：

  • Rust项目官方教程、开源项目手册
  • 电子书、系列教程、长篇学习笔记
  • 追求简单，不想管理 node_modules 的文档项目

不适合：

  • 博客网站（没有标签、归档）
  • 需要大量交互式组件、demo演示文档（优先VitePress）

部署mdBook ​

mdbook build 输出的 book 文件夹可以直接部署：GitHub Pages、Gitee Pages、Netlify、Vercel。GitHub Actions 可以配置CI自动构建发布。

mdBook 资源 ​

Copyright © 2026 SEO中文网