mdBook
将 Markdown 章节构建为带目录、搜索和主题的在线书籍与技术文档站点，支持本地预览、自动刷新和静态 HTML 输出。
mdBook 如何组织一本书
mdBook 把 Markdown 文件构建为现代在线书籍。book.toml 保存书籍与构建设置，src/SUMMARY.md 决定章节顺序和层级，src 下的 Markdown 文件保存正文。目录文件格式严格，章节只有被列入 SUMMARY 才会作为书籍结构出现。
本地预览与静态构建
mdbook serve 会启动默认仅用于开发的本地服务，监听源文件变化、重新构建并刷新浏览器。正式发布应使用 mdbook build 生成静态 HTML，默认输出到 book 目录。预览服务器并不是生产级 Web 服务，不应直接公开部署。
发布前容易忽略的内容
源目录中的图片和其他非 Markdown 文件会复制到输出目录，因此需要检查文件体积、授权和隐藏信息。Windows 对大小写不敏感时可正常打开的链接，部署到区分大小写的服务器后可能失效；发布前还应检查章节层级、断链、搜索和站点子路径。
维护记录
本页于 2026-08-06 根据 mdBook 的初始化、SUMMARY 目录格式、本地预览、静态构建和发布说明复核。归档文件为 v0.5.4 Windows x64 MSVC 压缩包。
保存到自己的网盘
打开网盘后可直接获取，也可以先保存到自己的网盘，方便换设备继续使用。
夸克网盘（无需提取码）
推荐将「mdBook」保存到该网盘
百度网盘
将「mdBook」保存到该网盘
mdBook Windows 创建和发布文档教程
先用 init 建立最小书籍，理解 book.toml、src/SUMMARY.md 与章节文件的关系；本地预览通过后再构建静态目录。
安装前准备
- 准备一个独立版本控制目录和几篇不含敏感信息的 Markdown 示例章节。
- 确认发布路径、链接大小写和目标 Web 服务规则，Windows 本地正常不代表 Linux 主机路径也正确。
- 将本地预览和正式托管分开，避免把开发预览服务直接暴露到公网。
安装步骤
- 01
解压 mdBook 程序
将 Windows x64 压缩包解压到固定工具目录，通过完整路径检查版本，需要长期使用时再加入用户 PATH。
- 02
初始化测试书籍
运行 mdbook init 并指定新目录，回答初始化问题后检查生成的 book.toml、src/SUMMARY.md 和章节文件。
- 03
纳入版本控制
提交源文件和配置，但把生成目录作为构建产物处理；团队先约定链接、图片和章节命名规则。
快速上手
- 01
编辑目录与章节
在 src/SUMMARY.md 中按层级列出章节相对路径，再编辑对应 Markdown 文件；不存在的已列出章节可能在构建时被创建。
- 02
启动本地预览
在包含 book.toml 的目录运行 mdbook serve --open，保存章节后确认页面自动重建、目录、搜索和内部链接正常。
- 03
构建静态输出
运行 mdbook build，检查默认生成的 book 目录；用静态服务器复测后，再上传该构建产物而不是预览进程。
使用建议
- SUMMARY.md 格式严格，调整层级后同时检查章节文件路径和最终 URL，避免出现静默遗漏。
- src 中非 Markdown 文件也会复制到输出目录，放入图片、下载文件前应检查版权、体积和敏感信息。
- 在持续集成中固定 mdBook 版本，并对断链、构建警告和生成目录做发布前检查。
故障排查与卸载方法
构建时为什么自动出现空章节文件？
mdBook 会为 SUMMARY.md 中列出但不存在的章节创建文件。检查目录是否误写路径，并在提交前查看新增文件。
预览正常但部署后图片或链接失效怎么办？
检查相对路径、文件名大小写、站点子路径和 Web 服务根目录；用接近生产环境的静态服务器测试构建目录。
- 删除程序与生成产物从 PATH 中移除工具目录后删除可执行文件；源 Markdown 和配置应保留，book 构建目录可在确认无发布依赖后重新生成或清理。
常见问题
mdBook 适合制作什么内容？
它适合技术手册、课程讲义、项目文档和由多个 Markdown 章节组成的在线书籍。它不是通用博客 CMS，也不提供账号、评论或动态数据库功能。
为什么新章节没有出现在目录中？
章节必须按严格格式写入 src/SUMMARY.md。单独放入 src 目录不会自动成为目录项，应检查相对路径、缩进、列表符号和文件名大小写。
mdbook serve 可以直接作为生产服务器吗？
不应该。官方说明 serve 用于测试输出，会监听文件并自动刷新，不是完整的网站服务器。正式发布应运行 mdbook build，再把生成的静态目录交给可靠的 Web 服务或托管平台。
下载时需要提取码吗？
夸克网盘无需提取码；百度网盘所需的四位提取码会直接显示在下载入口旁。