MD-Book 是一个基于 Rust 的文档生成器，定位为 mdbook 的现代替代品，用于将 Markdown 文件转换为美观、可搜索的 HTML 文档站点。
概述
MD-Book 支持多种 Markdown 格式（Markdown、GFM、MDX）、服务器端语法高亮、实时开发服务器以及集成的 Pagefind 搜索。
CLI 使用
基础命令：
# 构建文档（将 markdown 转换为 HTML）
md-book -i input_dir -o output_dir
# 带文件监听的开发模式
md-book -i input_dir -o output_dir --watch
# 使用内置服务器的开发模式（默认端口 3000）
md-book -i input_dir -o output_dir --serve
# 完整开发模式（监听 + 自定义端口服务）
md-book -i input_dir -o output_dir --watch --serve --port 8080
CLI 选项包括：--input / -i（输入目录，必填）、--output / -o（输出目录，必填）、--config / -c（可选配置文件路径）、--watch / -w（监听变化并重建）、--serve / -s（在 http://localhost:3000 提供服务）、--port（服务端口，默认 3000）。
从源码运行：
git clone https://github.com/terraphim/md-book.git
cd md-book
cargo build --release
cargo run -- -i docs -o output
cargo run -- -i docs -o output --serve --watch
配置
配置优先级从高到低为：CLI 参数、环境变量（MDBOOK_ 前缀）、自定义配置文件（--config 标志）、当前目录的 book.toml、默认值。
book.toml 示例（在输入目录中创建）：
[book]
title = "My Documentation"
authors = ["Your Name"]
description = "Documentation description"
language = "en"
[output.html]
# 安全：markdown 中的原始 HTML 默认禁用
allow-html = false # 仅在信任所有内容作者时设为 true
mathjax-support = false
环境变量示例：
MDBOOK_BOOK.TITLE="My Book" md-book -i input -o output
MDBOOK_OUTPUT.HTML.MATHJAX_SUPPORT=true md-book -i input -o output
项目结构
输入目录中，index.md 为可选的自定义首页内容（存在则渲染为首页，缺失则自动生成卡片式导航）；子目录会成为章节；images/ 等静态资源会被复制到输出。输出目录生成对应的 HTML 文件、css/、js/（实时重载、搜索、语法高亮）以及 pagefind/（若启用搜索）。
功能
语法高亮：通过 syntect 进行服务器端高亮，支持包括 Rust、Python 在内的主要语言。
全文搜索（Pagefind）：内置搜索，需要 pagefind CLI（cargo install pagefind）。构建时 Pagefind 自动运行，必要时可手动执行 pagefind --site output_dir。
实时重载：使用 --serve --watch 时，页面通过 WebSocket 在文件变化时自动重载。
首页（两种方式）：
- 方式一：在输入目录创建 index.md 作为自定义首页，完全控制布局与内容。
- 方式二：若无 index.md，自动使用 Shoelace UI 组件生成卡片式首页，显示“Documentation”标题、各章节/目录卡片、章节内各页面卡片及“Read More”按钮。
选择建议：需要自定义欢迎内容、特定导航顺序或品牌信息时用 index.md；快速搭建或希望由文档结构驱动导航时用自动卡片。
右侧目录：每页包含用于页面内导航的右侧目录。
模板定制：使用 Tera 模板引擎，模板包括 page.html.tera（单页布局）、index.html.tera（首页）、sidebar.html.tera（导航侧边栏）、header.html.tera（页头）、footer.html.tera（页脚）。
内置 Web Components：doc-toc.js（目录）、search-modal.js（搜索界面）、doc-sidebar.js（响应式侧边栏）、simple-block.js（内容块）。
部署
Cloudflare Pages（推荐）：./scripts/setup-cloudflare.sh 然后 ./scripts/deploy.sh production。
Netlify：cargo run -- -i docs -o dist 然后 netlify deploy --prod --dir=dist。
GitHub Pages：使用 GitHub Actions 工作流，构建步骤 cargo run -- -i docs -o _site，部署使用 actions/deploy-pages@v4。
其他支持平台包括 Vercel、AWS Amplify、Render、Railway、Fly.io 和 DigitalOcean。
测试
# 单元测试
cargo test --lib --bins
# 集成测试
cargo test --test integration --features "tokio,search,syntax-highlighting"
# 全部测试
cargo test --all-targets --features "tokio,search,syntax-highlighting"
# 质量检查
make qa # 格式化、clippy、测试
make ci-local # 本地模拟 CI
功能标志
Cargo.toml 中默认功能为 default = ["server", "watcher", "search", "syntax-highlighting"]，另有 server（warp、tokio/full）、watcher（notify、tokio/full）、search（pagefind）、syntax-highlighting（syntect）、wasm（wasm-bindgen）。最小构建：cargo build --no-default-features。
安全注意事项
Markdown 中的原始 HTML 默认禁用；仅在信任所有内容时通过 [output.html] 的 allow-html = true 启用（注意 XSS 风险）。密钥管理建议使用 1Password 集成或环境变量，切勿提交 .env 文件。
常见用法模式
创建文档项目（自定义首页）：
mkdir docs
cat > docs/index.md << 'EOF'
# Welcome to My Project
This is the home page with custom content.
## Quick Start
See [Getting Started](getting-started.md) to begin.
EOF
cat > docs/getting-started.md << 'EOF'
# Getting Started
Installation and setup instructions.
EOF
md-book -i docs -o output --serve --watch
创建文档项目（自动卡片导航）：不创建 index.md，直接添加各页面 Markdown 文件后运行同一命令，首页会自动显示指向所有页面的卡片。
添加搜索：安装 pagefind 后搜索自动生效：cargo install pagefind 然后 md-book -i docs -o output。
自定义样式：编辑 src/templates/css/styles.css 中的 CSS，或提供自定义模板目录。
故障排查
构建失败：检查 Rust 安装（rustc --version、cargo --version），清理并重建（cargo clean、cargo build --release）。
搜索不工作：确认 pagefind 已安装（which pagefind），必要时手动运行 pagefind --site output_dir。
实时重载不工作：确保同时使用两个标志：md-book -i docs -o output --watch --serve。
仓库
GitHub：https://github.com/terraphim/md-book 问题反馈：https://github.com/terraphim/md-book/issues 讨论：https://github.com/terraphim/md-book/discussions