md-book

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MD-Book Documentation Generator Skill

MD-Book文档生成工具使用指南

Use this skill when working with MD-Book, a modern mdbook replacement for generating HTML documentation from Markdown files.

当你使用MD-Book（一款替代传统mdbook的现代工具，可将Markdown文件生成HTML文档）时，可使用本指南。

Overview

概述

MD-Book is a Rust-based documentation generator that converts Markdown files to beautiful, searchable HTML documentation. It supports multiple markdown formats (Markdown, GFM, MDX), server-side syntax highlighting, live development server, and integrated Pagefind search.

MD-Book是一款基于Rust的文档生成工具，可将Markdown文件转换为美观、可搜索的HTML文档。它支持多种Markdown格式（Markdown、GFM、MDX）、服务端语法高亮、实时开发服务器以及集成的Pagefind搜索功能。

CLI Usage

命令行界面（CLI）使用方法

Basic Commands

基础命令

bash

undefined

bash

undefined

Build documentation (converts markdown to HTML)

构建文档（将Markdown转换为HTML）

md-book -i input_dir -o output_dir

Development mode with file watching

启用文件监听的开发模式

md-book -i input_dir -o output_dir --watch

Development with built-in server (default port 3000)

带内置服务器的开发模式（默认端口3000）

md-book -i input_dir -o output_dir --serve

Full development mode (watch + serve on custom port)

完整开发模式（监听+自定义端口服务）

md-book -i input_dir -o output_dir --watch --serve --port 8080

undefined

md-book -i input_dir -o output_dir --watch --serve --port 8080

undefined

CLI Options

CLI选项

Option	Short	Description
`--input`	`-i`	Input directory containing markdown files (required)
`--output`	`-o`	Output directory for HTML files (required)
`--config`	`-c`	Optional path to config file
`--watch`	`-w`	Watch for changes and rebuild
`--serve`	`-s`	Serve at http://localhost:3000
`--port`		Port to serve on (default: 3000)

选项	缩写	描述
`--input`	`-i`	包含Markdown文件的输入目录（必填）
`--output`	`-o`	HTML文件的输出目录（必填）
`--config`	`-c`	可选的配置文件路径
`--watch`	`-w`	监听文件变更并重新构建
`--serve`	`-s`	在http://localhost:3000提供服务
`--port`		服务使用的端口（默认：3000）

Running from Source

从源码运行

bash

undefined

bash

undefined

Clone and build

克隆并构建

git clone https://github.com/terraphim/md-book.git cd md-book cargo build --release

Run from source

从源码运行

cargo run -- -i docs -o output cargo run -- -i docs -o output --serve --watch

undefined

cargo run -- -i docs -o output cargo run -- -i docs -o output --serve --watch

undefined

Configuration

配置

Configuration Priority (highest to lowest)

配置优先级（从高到低）

CLI arguments
Environment variables (MDBOOK_ prefix)
Custom config file (--config flag)
book.toml in current directory
Default values

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

book.toml Configuration

book.toml配置

Create

book.toml

in your input directory:

toml

[book]
title = "My Documentation"
authors = ["Your Name"]
description = "Documentation description"
language = "en"

[output.html]

在输入目录中创建

book.toml

文件：

toml

[book]
title = "My Documentation"
authors = ["Your Name"]
description = "Documentation description"
language = "en"

[output.html]

Security: raw HTML in markdown is DISABLED by default

安全提醒：默认禁用Markdown中的原生HTML

allow-html = false # Set to true only if you trust all content authors mathjax-support = false

undefined

allow-html = false # 仅当你信任所有内容作者时才设置为true mathjax-support = false

undefined

Environment Variables

环境变量

bash

undefined

bash

undefined

Override book title

覆盖书籍标题

MDBOOK_BOOK.TITLE="My Book" md-book -i input -o output

Nested configuration values use underscore

嵌套配置值使用下划线

MDBOOK_OUTPUT.HTML.MATHJAX_SUPPORT=true md-book -i input -o output

undefined

MDBOOK_OUTPUT.HTML.MATHJAX_SUPPORT=true md-book -i input -o output

undefined

Project Structure

项目结构

Input Directory

输入目录

input/
  index.md          # OPTIONAL: Custom home page content
                    # If present: renders your markdown as home page
                    # If absent: auto-generates card-based navigation
  getting-started.md
  configuration.md
  advanced/         # Subdirectories become sections
    topic1.md
    topic2.md
  images/           # Static assets copied to output

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

Output Directory

输出目录

output/
  index.html        # Generated home page
  getting-started.html
  configuration.html
  advanced/
    topic1.html
    topic2.html
  css/             # Styles
  js/              # JavaScript (live reload, search, syntax highlighting)
  pagefind/        # Search index (if search feature enabled)

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

Features

功能特性

Syntax Highlighting

语法高亮

Server-side syntax highlighting via syntect. Supports all major languages:

markdown

```rust
fn main() {
    println!("Hello, world!");
}
```

```python
def hello():
    print("Hello, world!")
```

通过syntect实现服务端语法高亮，支持所有主流编程语言：

markdown

```rust
fn main() {
    println!("Hello, world!");
}
```

```python
def hello():
    print("Hello, world!")
```

Full-Text Search (Pagefind)

全文搜索（Pagefind）

Search is built in via Pagefind. Requires pagefind CLI:

bash

undefined

通过Pagefind内置搜索功能，需要安装Pagefind CLI：

bash

undefined

Install pagefind

安装pagefind

cargo install pagefind

Pagefind runs automatically during build

构建时会自动运行Pagefind

Manual indexing if needed:

如需手动索引：

pagefind --site output_dir

undefined

pagefind --site output_dir

undefined

Live Reload

实时重载

When using

--serve --watch

, pages automatically reload on file changes via WebSocket.

当同时使用

--serve --watch

标志时，文件变更后页面会通过WebSocket自动重载。

Index Page (Two Methods)

首页（两种方式）

MD-Book supports two ways to create your documentation home page:

MD-Book支持两种创建文档首页的方式：

Method 1: Custom Content with index.md

方式1：使用index.md自定义内容

Create an

index.md

file in your input directory for a custom home page:

markdown

undefined

在输入目录中创建

index.md

文件来定制首页：

markdown

undefined

Welcome to My Documentation

This is my custom home page content with full markdown support.

Quick Links

Getting Started
Configuration
API Reference


When `index.md` exists, its content is rendered as the home page. This gives you full control over the layout and content.

Getting Started
Configuration
API Reference


当`index.md`存在时，其内容会被渲染为首页，让你完全控制布局和内容。

Method 2: Auto-Generated Card Navigation

方式2：自动生成卡片式导航

If no
index.md
is present, MD-Book automatically generates a card-based home page using Shoelace UI components. This displays:

A "Documentation" header
Cards for each section/directory
Cards for each page within sections
"Read More" buttons linking to each page

This is ideal for quickly getting started or for projects where you want automatic navigation without maintaining a custom index.

Choosing Between Methods:

Use index.md when you want custom welcome content, specific navigation order, or branded messaging
Use auto-generated cards for quick setup or when documentation structure should drive navigation

如果没有index.md，MD-Book会使用Shoelace UI组件自动生成卡片式首页，包含：

“Documentation”标题
每个章节/目录对应的卡片
章节内每个页面对应的卡片
指向各页面的“Read More”按钮

这种方式非常适合快速启动项目，或者希望文档结构自动驱动导航的场景。

方式选择建议：

当你需要自定义欢迎内容、特定导航顺序或品牌信息时，使用index.md
当你需要快速搭建或希望文档结构主导导航时，使用自动生成卡片

Right-Hand TOC

右侧目录（TOC）

Each page includes a right-hand table of contents for in-page navigation.

每个页面都包含右侧目录，用于页面内导航。

Template Customization

模板定制

Templates use Tera templating engine:

Template	Purpose
`page.html.tera`	Individual page layout
`index.html.tera`	Home page
`sidebar.html.tera`	Navigation sidebar
`header.html.tera`	Page header
`footer.html.tera`	Page footer

模板使用Tera模板引擎：

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

Web Components

Web组件

Built-in Web Components:

```
doc-toc.js
```
- Table of contents
```
search-modal.js
```
- Search interface
```
doc-sidebar.js
```
- Responsive sidebar
```
simple-block.js
```
- Content blocks

内置Web组件：

```
doc-toc.js
```
- 目录组件
```
search-modal.js
```
- 搜索界面
```
doc-sidebar.js
```
- 响应式侧边栏
```
simple-block.js
```
- 内容块组件

Deployment

部署

Cloudflare Pages (Recommended)

Cloudflare Pages（推荐）

bash

undefined

bash

undefined

Setup

设置

./scripts/setup-cloudflare.sh

Deploy

部署

./scripts/deploy.sh production

undefined

./scripts/deploy.sh production

undefined

Netlify

bash

undefined

bash

undefined

Build

构建

cargo run -- -i docs -o dist

Deploy

部署

netlify deploy --prod --dir=dist

undefined

netlify deploy --prod --dir=dist

undefined

GitHub Pages

Use the GitHub Actions workflow:

yaml

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

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

使用GitHub Actions工作流：

yaml

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

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

Other Platforms

其他平台

Vercel, AWS Amplify, Render, Railway, Fly.io, and DigitalOcean are all supported. See DEPLOYMENT.md for details.

Vercel、AWS Amplify、Render、Railway、Fly.io和DigitalOcean均支持部署。详情请查看DEPLOYMENT.md。

Testing

测试

bash

undefined

bash

undefined

Unit tests

单元测试

cargo test --lib --bins

Integration tests

集成测试

cargo test --test integration --features "tokio,search,syntax-highlighting"

All tests

所有测试

cargo test --all-targets --features "tokio,search,syntax-highlighting"

Quality checks

质量检查

make qa # Format, clippy, tests make ci-local # Simulate CI locally

undefined

make qa # 格式化、Clippy检查、测试 make ci-local # 本地模拟CI流程

undefined

Feature Flags

功能标志

toml

undefined

toml

undefined

Cargo.toml features

Cargo.toml中的功能

default = ["server", "watcher", "search", "syntax-highlighting"] server = ["warp", "tokio/full"] # Dev server with live reload watcher = ["notify", "tokio/full"] # File watching search = ["pagefind"] # Pagefind search integration syntax-highlighting = ["syntect"] # Code highlighting wasm = ["wasm-bindgen"] # WASM support


Build minimal version:
```bash
cargo build --no-default-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支持


构建最小版本：
```bash
cargo build --no-default-features

Security Considerations

安全注意事项

HTML in Markdown

Markdown中的HTML

Raw HTML is disabled by default for security. Enable only if you trust all content:

toml

[output.html]
allow-html = true  # WARNING: Enables XSS risk

默认禁用原生HTML以保障安全。仅当你信任所有内容作者时才启用：

toml

[output.html]
allow-html = true  # 警告：启用后存在XSS风险

Secrets Management

密钥管理

Use 1Password integration or environment variables
Never commit
```
.env
```
files
See
```
docs/1PASSWORD_SETUP.md
```
for secure setup

使用1Password集成或环境变量
切勿提交
```
.env
```
文件
安全设置详情请查看
```
docs/1PASSWORD_SETUP.md
```

Common Patterns

常见使用模式

Creating Documentation Project

创建文档项目

With custom index page:

bash

mkdir docs
cat > docs/index.md << 'EOF'

带自定义首页：

bash

mkdir docs
cat > docs/index.md << 'EOF'

Welcome to My Project

This is the home page with custom content.

Quick Start

See Getting Started to begin. EOF

cat > docs/getting-started.md << 'EOF'

See Getting Started to begin. EOF

cat > docs/getting-started.md << 'EOF'

Getting Started

Installation and setup instructions. EOF

md-book -i docs -o output --serve --watch


**With auto-generated card navigation:**
```bash
mkdir docs

Installation and setup instructions. EOF

md-book -i docs -o output --serve --watch


**带自动生成卡片导航：**
```bash
mkdir docs

No index.md - cards will be auto-generated

不创建index.md - 会自动生成卡片

cat > docs/getting-started.md << 'EOF'

Getting Started

Installation and setup instructions. EOF

cat > docs/configuration.md << 'EOF'

Installation and setup instructions. EOF

cat > docs/configuration.md << 'EOF'

Configuration

How to configure the project. EOF

md-book -i docs -o output --serve --watch

How to configure the project. EOF

md-book -i docs -o output --serve --watch

Home page shows cards linking to all pages automatically

首页会自动显示指向所有页面的卡片

undefined

undefined

Adding Search

添加搜索功能

Search works automatically when pagefind is installed:

bash

cargo install pagefind
md-book -i docs -o output  # Search index generated automatically

当安装Pagefind后，搜索功能会自动工作：

bash

cargo install pagefind
md-book -i docs -o output  # 会自动生成搜索索引

Custom Styling

自定义样式

Edit CSS in

src/templates/css/styles.css

or provide custom template directory.

编辑

src/templates/css/styles.css

中的CSS，或提供自定义模板目录。

Troubleshooting

故障排除

Build Fails

构建失败

bash

undefined

bash

undefined

Verify Rust installation

验证Rust安装

rustc --version cargo --version

Clean and rebuild

清理并重新构建

cargo clean cargo build --release

undefined

cargo clean cargo build --release

undefined

Search Not Working

搜索功能不工作

bash

undefined

bash

undefined

Verify pagefind installed

验证pagefind已安装

which pagefind

Manually run indexing

手动运行索引

pagefind --site output_dir

undefined

pagefind --site output_dir

undefined

Live Reload Not Working

实时重载不工作

Ensure using both flags together:

bash

md-book -i docs -o output --watch --serve

确保同时使用两个标志：

bash

md-book -i docs -o output --watch --serve

Repository

代码仓库

GitHub: https://github.com/terraphim/md-book
Issues: https://github.com/terraphim/md-book/issues
Discussions: https://github.com/terraphim/md-book/discussions

GitHub: https://github.com/terraphim/md-book
Issues: https://github.com/terraphim/md-book/issues
Discussions: https://github.com/terraphim/md-book/discussions