mdBook 开源笔记
基本信息
- 项目名称: mdBook
- 开源地址: https://github.com/rust-lang/mdBook
- 许可证: Mozilla Public License 2.0 (MPL-2.0)
- 开发语言: Rust
- 维护者: Rust 官方团队
项目简介
mdBook 是一个用于从 Markdown 文件创建现代在线书籍的命令行工具。它是 Rust 官方文档（如《Rust 程序设计语言》）的构建工具。
核心特点
内容组织
- 基于
SUMMARY.md文件定义书籍结构 - 自动生成导航和章节层级
- 支持多章节书籍的完整目录管理
开发体验
- 实时预览服务器 (
mdbook serve) - 文件修改后自动重载浏览器
- 纯文本工作流，兼容任何编辑器
功能丰富
- 支持代码语法高亮（数百种语言）
- 数学公式渲染（通过插件）
- 可自定义主题和模板
- 插件系统扩展功能
技术优势
- 基于高性能的
pulldown-cmark解析器 - 构建速度快，资源占用低
- 生成静态 HTML，易于部署
安装方法
使用 Cargo 安装
cargo install mdbook
包管理器安装
# macOS (Homebrew)
brew install mdbook# Ubuntu (Snap)
sudo snap install mdbook# Arch Linux (Pacman)
sudo pacman -S mdbook
基本使用
创建新书
mdbook init my-book
cd my-book
项目结构
my-book/
├── book/ # 构建输出目录
├── src/ # 源文件目录
│ ├── SUMMARY.md # 书籍大纲
│ └── chapter_1.md
└── book.toml # 配置文件
常用命令
# 构建书籍
mdbook build# 启动实时预览服务器
mdbook serve# 在构建前清理旧文件
mdbook clean# 测试代码示例
mdbook test
配置文件 (book.toml)
基本配置示例
[book]
title = "我的书籍"
authors = ["作者名"]
description = "书籍描述"[build]
build-dir = "book"
create-missing = true
插件配置示例
[output.html]
mathjax-support = true[preprocessor.links]
command = "mdbook-linkcheck"
插件生态系统
常用官方/社区插件
mdbook-linkcheck: 链接有效性检查mdbook-toc: 增强目录生成mdbook-plantuml: PlantUML 图表支持mdbook-katex: 数学公式渲染mdbook-mermaid: Mermaid 图表支持
插件安装使用
cargo install mdbook-linkcheck
然后在 book.toml 中配置：
[preprocessor.linkcheck]
command = "mdbook-linkcheck"
适用场景
理想用例
✅ 开源项目文档
✅ 技术教程和课程教材
✅ 团队知识库和规范文档
✅ 个人作品集和技术博客
不适用场景
❌ 零散的个人笔记管理
❌ 需要富文本编辑器的用户
❌ 实时协作编辑需求
优势总结
- 性能优异: Rust 编写，构建速度快
- 结构清晰: 专为长篇内容设计
- 生态丰富: 插件系统扩展性强
- 部署简单: 生成静态文件，兼容所有 Web 服务器
- 社区活跃: Rust 官方维护，更新及时
学习资源
- 官方文档: https://rust-lang.github.io/mdBook/
- 示例项目: GitHub 仓库中的
examples目录 - 用户指南: 详细的使用说明和最佳实践