mdBook Rust 文档工具¶

一句话概述：mdBook 是 Rust 官方文档使用的工具，用 Markdown 写内容，自动生成类似书籍的静态网站，简单快速。

核心知识点¶

概念	白话解释
mdBook	Rust 文档工具 = Markdown 变电子书
SUMMARY.md	目录文件 = 定义书的章节结构
book.toml	配置文件 = 书的元信息和设置
Preprocessor	预处理器 = 构建前处理 Markdown
Renderer	渲染器 = 输出格式（HTML/PDF）

安装配置¶

# 安装（需要 Rust 工具链）
cargo install mdbook                                   # Cargo 安装

# 或下载预编译二进制
# https://github.com/rust-lang/mdBook/releases

# macOS
brew install mdbook                                    # Homebrew 安装

# 验证
mdbook --version                                      # 查看版本

快速开始¶

# 创建新书
mdbook init my-book                                    # 初始化项目
cd my-book                                            # 进入目录

# 项目结构
# my-book/
# ├── book.toml                                       # 配置文件
# └── src/                                            # 源文件目录
#     ├── SUMMARY.md                                  # 目录结构
#     └── chapter_1.md                                # 第一章

# 启动开发服务器
mdbook serve                                          # 本地预览（http://localhost:3000）
mdbook serve -p 8080                                   # 指定端口

# 构建
mdbook build                                          # 生成静态网站（输出到 book/）

配置文件¶

# book.toml
[book]
title = "生信分析指南"                                    # 书名
authors = ["彭文强"]                                    # 作者
language = "zh"                                        # 语言
src = "src"                                            # 源文件目录

[build]
build-dir = "book"                                     # 输出目录

[output.html]
default-theme = "light"                                # 默认主题
preferred-dark-theme = "navy"                          # 深色主题
git-repository-url = "https://github.com/..."          # GitHub 链接
edit-url-template = "https://github.com/.../edit/main/{path}" # 编辑链接

[output.html.search]
enable = true                                          # 启用搜索

SUMMARY.md 目录¶

# 目录

[前言](preface.md)

# 基础篇

- [Linux 基础](basic/linux.md)
  - [常用命令](basic/linux-commands.md)
  - [Shell 脚本](basic/shell.md)
- [Python 基础](basic/python.md)

# 分析篇

- [质控流程](analysis/qc.md)
- [物种注释](analysis/taxonomy.md)
- [功能注释](analysis/function.md)

# 附录

- [常见问题](appendix/faq.md)
- [参考资料](appendix/references.md)

常见报错¶

报错	原因	解决
`SUMMARY.md not found`	src 目录下缺少 SUMMARY.md	创建 SUMMARY.md 文件
`Chapter file not found`	SUMMARY 引用了不存在的文件	创建对应的 .md 文件
`Port already in use`	端口被占	`mdbook serve -p 8080`
`TOML parse error`	配置文件语法错	检查 book.toml 语法

速查表¶

# 常用命令
mdbook init <name>                                     # 创建新书
mdbook serve                                          # 开发预览
mdbook build                                          # 构建
mdbook clean                                          # 清理输出
mdbook test                                           # 测试代码块

# 文件结构
# book.toml     → 配置
# src/SUMMARY.md → 目录结构
# src/*.md       → 章节内容
# book/          → 构建输出

# 适用场景
# 技术文档、教程、学习笔记、内部知识库
# Rust 生态项目的标准文档工具