SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场md-book

md-book

写作与研究

查看项目

更新于 10-16 06:01

技能介绍

用途

MD-Book 是一个基于 Rust 的文档生成器，定位为 mdbook 的现代替代方案，用于将 Markdown 文件转换为美观、可搜索的 HTML 文档。本技能在需要处理 MD-Book 时使用。

主要能力

  • 将 Markdown 转换为 HTML 文档。
  • 支持多种 Markdown 格式：Markdown、GFM、MDX。
  • 服务端语法高亮（通过 syntect），支持主要语言。
  • 内置开发服务器，默认端口 3000，支持实时重载（WebSocket）。
  • 文件监听与自动重建。
  • 集成 Pagefind 全文搜索（需安装 pagefind CLI）。
  • 首页支持两种方式：自定义 index.md 内容，或自动生成基于 Shoelace UI 组件的卡片式导航。
  • 每页包含右侧页内目录（TOC）。
  • 使用 Tera 模板引擎进行模板定制。
  • 内置 Web Components：doc-toc.js、search-modal.js、doc-sidebar.js、simple-block.js。

使用方式

基本命令

# 构建文档（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 包含 Markdown 文件的输入目录（必填）
--output -o HTML 文件的输出目录（必填）
--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

配置

配置优先级（从高到低）：

  1. CLI 参数
  2. 环境变量（MDBOOK_ 前缀）
  3. 自定义配置文件（--config 标志）
  4. 当前目录下的 book.toml
  5. 默认值

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

项目结构

输入目录：

input/
  index.md          # 可选：自定义首页内容
                    # 存在时：将你的 markdown 渲染为首页
                    # 不存在时：自动生成卡片式导航
  getting-started.md
  configuration.md
  advanced/         # 子目录成为章节
    topic1.md
    topic2.md
  images/           # 静态资源复制到输出

输出目录：

output/
  index.html        # 生成的首页
  getting-started.html
  configuration.html
  advanced/
    topic1.html
    topic2.html
  css/             # 样式
  js/              # JavaScript（实时重载、搜索、语法高亮）
  pagefind/        # 搜索索引（若启用搜索功能）

首页两种方式

方式一：使用 index.md 自定义内容。在输入目录创建 index.md，其内容将渲染为首页，支持完整 Markdown。

方式二：自动生成卡片导航。若无 index.md，MD-Book 自动生成基于 Shoelace UI 组件的卡片式首页，显示“Documentation”标题、各章节/目录卡片、章节内各页面卡片以及指向各页面的“Read More”按钮。

选择建议：需要自定义欢迎内容、特定导航顺序或品牌信息时使用 index.md；快速搭建或希望由文档结构驱动导航时使用自动生成卡片。

搜索

搜索通过 Pagefind 内置。需安装 pagefind CLI：

cargo install pagefind

Pagefind 在构建期间自动运行。如需手动索引：

pagefind --site output_dir

模板定制

模板使用 Tera 模板引擎：

模板 用途
page.html.tera 单个页面布局
index.html.tera 首页
sidebar.html.tera 导航侧边栏
header.html.tera 页面头部
footer.html.tera 页面底部

部署

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 工作流：

- name: Build site
  run: cargo run -- -i docs -o _site

- name: Deploy to GitHub Pages
  uses: actions/deploy-pages@v4

其他平台：Vercel、AWS Amplify、Render、Railway、Fly.io 和 DigitalOcean 均受支持，详见 DEPLOYMENT.md。

测试

# 单元测试
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 features
default = ["server", "watcher", "search", "syntax-highlighting"]
server = ["warp", "tokio/full"]           # 带实时重载的开发服务器
watcher = ["notify", "tokio/full"]         # 文件监听
search = ["pagefind"]                      # Pagefind 搜索集成
syntax-highlighting = ["syntect"]          # 代码高亮
wasm = ["wasm-bindgen"]                    # WASM 支持

构建最小版本：

cargo build --no-default-features

适用场景

  • 为项目生成 HTML 文档站点。
  • 需要全文搜索、语法高亮和实时预览的文档工作流。
  • 从 mdbook 迁移或寻找现代替代方案。
  • 部署到 Cloudflare Pages、Netlify、GitHub Pages 等平台。

限制与安全注意事项

  • 默认禁用 Markdown 中的原始 HTML 以保证安全。仅在信任所有内容时启用：
[output.html]
allow-html = true  # 警告：启用 XSS 风险
  • 密钥管理：使用 1Password 集成或环境变量；切勿提交 .env 文件；安全设置见 docs/1PASSWORD_SETUP.md。
  • 搜索功能需要单独安装 pagefind CLI。
  • 实时重载需同时使用 --watch 和 --serve 标志。

故障排查

构建失败：

# 验证 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
  • Issues：https://github.com/terraphim/md-book/issues
  • Discussions：https://github.com/terraphim/md-book/discussions