文档即代码：版本化、自动构建与协作

docs/ index.md getting-started/ installation.md quickstart.md user-guide/ configuration.md advanced.md developer-guide/ api-reference.md images/ architecture.png

### 与代码仓库的版本对应

为了让文档版本与软件版本严格绑定，可以在代码仓库中维护文档，并利用 Git 标签同时发布代码和文档。当用户检出 `v1.2.0` 时，他们也能看到对应版本的文档。如果使用独立仓库，则需建立版本映射关系，或者用子模块的方式将文档链接到代码库。

## 自动构建：从源代码到发布网站

### 静态站点生成器

把 Markdown 变成精美的在线文档需要**静态站点生成器**。这些工具在本地或 CI 环境中运行，将源文件转换为完整的 HTML 网站。推荐以下主流选择：

| 工具 | 语言/生态 | 特点 |
|------|----------|------|
| **MkDocs** | Python | 极简配置，Material 主题美观，YAML 配置文件 |
| **Docusaurus** | JavaScript (React) | 功能全面，支持版本化、多语言，React 可嵌入 |
| **Sphinx** | Python | 生态成熟，支持多种输出格式，广泛用于 Python 文档 |
| **VuePress** | JavaScript (Vue) | 为 Vue.js 项目优化，可嵌入 Vue 组件 |
| **Hugo** | Go | 生成速度极快，适合大型站点 |

### 构建流程自动化

将文档构建集成到持续集成流水线中，实现代码推送即自动生成最新网站并发布。以 GitHub Pages + MkDocs 为例，典型步骤：

1. **配置 MkDocs**：在文档根目录创建 `mkdocs.yml`

   ```yaml
   site_name: 项目文档
   site_url: https://your-project.github.io/docs/
   nav:
     - 首页: index.md
     - 快速入门: getting-started/quickstart.md
     - 用户指南:
       - 安装: getting-started/installation.md
       - 配置: user-guide/configuration.md
     - 开发者指南: developer-guide/api-reference.md
   theme: material

1. 编写构建脚本：在 CI 配置（如 GitHub Actions）中定义流水线

   name: Build and Deploy Docs
   on:
     push:
       branches: [main]
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - uses: actions/setup-python@v4
           with:
             python-version: '3.10'
         - run: pip install mkdocs-material
         - run: mkdocs build
         - uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./site