第二十五章. 活文档工程：Docs as Code (文档即代码)

在开源界流传着一句话：“代码写得再好，文档烂也是垃圾”。

传统的文档维护方式（Word、Confluence 或随意更改的文本）最大的问题是“文档腐烂”——代码更新了，文档没跟上，导致用户照着文档跑不通，最后愤怒地关闭页面。

本章我们将引入“文档工程”的概念：将文档视为代码仓库的一部分，纳入版本控制，利用 CI/CD 自动化更新，并实现“图表即代码”的可视化管理。

25.1. 门面担当：README 的规范与自动化

25.1.1. 行业规范：合格 README 的必备要素

一个符合工业级规范的 README，必须 包含以下模块：

1. Header（页头）

• 高清 Logo（建议尺寸：512×512px，PNG 格式带透明背景）
• 项目名称（使用一级标题）
• 一句话核心价值主张（Value Proposition）

示例：

1
2
3

# 🚀 FastAPI Boilerplate

生产级 FastAPI 项目脚手架 —— 开箱即用的企业级后端解决方案

2. Badges（徽章）
徽章是项目的"生命体征监测器"，展示项目的健康状态。必备徽章包括：

• 构建状态：显示 CI/CD 是否通过
• 版本号：当前发布版本
• License：开源协议类型
• 代码覆盖率：测试覆盖百分比
• 下载量：npm/PyPI 下载统计

3. Demo（演示）

• 一张 GIF 动图或核心功能截图
• 遵循 No Pic No Truth 原则
• GIF 大小控制在 5MB 以内，推荐使用 ScreenToGif 录制

4. Features（核心特性）

• 3-5 个核心卖点，使用列表形式
• 每条特性用 动词 + 名词 结构
• 适当使用 Emoji 增强可读性（✅ ✨ 🚀 ⚡ 🔒）

5. Quick Start（快速开始）

• 必须让用户在 3 行命令内 跑起来
• 包含前置依赖说明（Node.js 版本、Python 版本等）
• 提供最简单的 Hello World 示例

6. Installation（安装指南）

• 详细的依赖安装步骤
• 常见操作系统的差异说明（Windows/macOS/Linux）

7. Contributing（贡献指南）

• 链接到 CONTRIBUTING.md 文件
• 简要说明如何提交 Issue 和 PR

8. License（开源协议）

• 声明项目采用的开源协议
• 链接到 LICENSE 文件

25.1.2. 徽章（Badges）制作实战指南

徽章的核心工具是 Shields.io，这是全球最大的徽章生成服务，GitHub 上超过 2000 万个项目 在使用。

常用徽章类型与生成方法

A. 构建状态徽章（GitHub Actions）

1. 进入你的 GitHub 仓库的 Actions 页面
2. 点击工作流右上角的 “…” 菜单
3. 选择 “Create status badge”
4. 复制生成的 Markdown 代码

1

![Build Status](https://github.com/用户名/仓库名/actions/workflows/ci.yml/badge.svg)

B. 版本号徽章（npm/PyPI）

访问 Shields.io，搜索对应的徽章类型：

1
2
3
4
5
6
7
8

<!-- npm 版本 -->
![npm](https://img.shields.io/npm/v/package-name)

<!-- PyPI 版本 -->
![PyPI](https://img.shields.io/pypi/v/package-name)

<!-- GitHub Release -->
![GitHub release](https://img.shields.io/github/v/release/用户名/仓库名)

C. License 徽章

1

![License](https://img.shields.io/github/license/用户名/仓库名)

D. 代码覆盖率徽章（Codecov）

1. 登录 Codecov.io
2. 关联你的 GitHub 仓库
3. 在 Settings → Badge 中复制 Markdown 链接

1

![Coverage](https://codecov.io/gh/用户名/仓库名/branch/main/graph/badge.svg)

E. 自定义徽章

Shields.io 支持完全自定义的徽章格式：

1
2
3
4
5

![自定义徽章](https://img.shields.io/badge/标签-信息-颜色)

<!-- 示例 -->
![Made with Love](https://img.shields.io/badge/Made%20with-❤️-red)
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)

徽章颜色代码：

• brightgreen：亮绿色（成功）
• red：红色（失败）
• blue：蓝色（信息）
• yellow：黄色（警告）
• orange：橙色
• 也支持十六进制颜色：#FF5733

徽章排版最佳实践

1
2
3
4
5
6
7
8
9
10
11
12
13

<!-- 推荐：分类排列 -->
<!-- 构建状态 -->
![Build](...)
![Tests](...)

<!-- 版本信息 -->
![Version](...)
![Python](...)

<!-- 社区指标 -->
![Stars](...)
![Forks](...)
![License](...)

25.1.3. Features（特性）的专业写法

糟糕示例 ❌

1
2
3

- 速度快
- 容易使用
- 功能强大

这种描述毫无说服力，没有提供任何具体信息。

优秀示例 ✅

1
2
3
4
5
6
7

## ✨ 核心特性

- ⚡ **极致性能** - 基于 Rust 内核，启动速度比传统方案快 10 倍
- 🎯 **零配置** - 内置 ESLint + Prettier + TypeScript，开箱即用
- 🔒 **类型安全** - 全量 TypeScript 支持，在编译期捕获 90% 的 Bug
- 🌐 **国际化** - 支持 20+ 语言，自动检测用户区域设置
- 📦 **轻量级** - 打包体积仅 15KB (gzipped)

25.1.4. Quick Start（快速开始）的黄金法则

法则 1：3 行命令内跑起来

糟糕示例 ❌

1

请先安装 Node.js，然后配置环境变量，接着执行...

优秀示例 ✅

1
2
3
4
5
6

## 🚀 快速开始

​```bash
npm install my-awesome-package
npx create-my-app my-project
cd my-project && npm start

打开浏览器访问 http://localhost:3000

1
2
3
4
5
6
7
8
9

#### **法则 2：前置依赖必须明确**

​```markdown
## 📋 前置要求

- Node.js >= 18.0.0
- npm >= 9.0.0 或 pnpm >= 8.0.0
- 操作系统：macOS / Linux / Windows 10+

法则 3：提供多种安装方式

1
2
3
4
5

## 📦 安装

**npm**
​```bash
npm install package-name

yarn

1

yarn add package-name

pnpm

1

pnpm add package-name

CDN（浏览器环境）

1

<script src="https://unpkg.com/package-name"></script>

25.1.5. AI 辅助生成 README

现在，请你扮演"审稿人"的角色，而不是"撰稿人"。将繁琐的格式排版工作交给 AI。

操作步骤

Step 1：准备代码上下文

复制你项目核心逻辑文件（如 main.py 或 App.vue）的前 50-100 行代码。

Step 2：使用专业 Prompt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# Role
你是一位专业的开源项目文档专家，擅长撰写符合 GitHub 顶级项目标准的 README。

# Task
我正在开发一个名为 [项目名称] 的开源项目，它是一个 [一句话描述，例如：基于 React 的轻量级状态管理库]。
请阅读我提供的核心代码片段，为我生成一份符合工业级规范的 README.md。

# Requirements
1. **结构要求**：必须包含以下章节（严格顺序）
   - Header（包含 Logo 占位符、项目名、价值主张）
   - Badges（预留 5 个徽章位置，用注释标注类型）
   - Demo（提示需要添加 GIF/截图）
   - Features（3-5 个核心卖点，使用 Emoji）
   - Quick Start（3 行命令）
   - Installation（详细步骤）
   - Usage（基于我的代码生成真实示例）
   - API Documentation（如果适用）
   - Contributing（链接到 CONTRIBUTING.md）
   - License（占位符）

2. **格式规范**：
   - 使用标准 Markdown 语法
   - 代码块必须指定语言（```bash、```javascript 等）
   - Features 每条前面使用 Emoji
   - 使用表格展示配置选项（如果适用）

3. **内容风格**：
   - 语气：专业、热情、简洁
   - 避免模糊词汇（"非常好""很快"等）
   - 使用具体数据和对比（"比 X 快 3 倍""体积仅 15KB"）

4. **Usage Example 要求**：
   - 根据我提供的代码逻辑，编写一个 Hello World 级别的最简示例
   - 示例必须能够直接复制运行
   - 在代码块后添加预期输出

# Context (My Code)
​```python
[在此处粘贴你的核心代码]

# Output Format

请直接输出完整的 README.md 内容，无需额外解释。
​````

**Step 3：迭代优化**

AI 生成初稿后，你可以追问：
- "Features 部分能否更具体？请加入性能数据对比"
- "Quick Start 的命令能否简化到 2 行？"
- "请为 Usage 部分增加 3 个进阶示例"

25.1.6. 检查清单：发布前的 README 审查

在推送代码前，请确保：

• [ ] 项目名称和描述清晰明确
• [ ] 至少包含 3 个徽章（构建状态、版本、License）
• [ ] 有至少 1 张截图或 GIF 演示
• [ ] Features 部分包含 3-5 个卖点，每条带 Emoji
• [ ] Quick Start 可以在 5 分钟内完成
• [ ] 所有代码示例经过测试，确保可运行
• [ ] 包含 Contributing 和 License 信息
• [ ] 链接全部有效（无 404 错误）
• [ ] 在手机端预览排版正常

25.2. 可视化思维：Mermaid 与“图表即代码”

1. 行业规范：一图胜千言

在复杂的业务逻辑、状态机流转、时序交互中，纯文字描述是苍白的。规范的工程文档必须配图。

传统的做法是：

1. 打开 Visio / Draw.io / Figma。
2. 画图。
3. 导出 PNG。
4. 上传到 Git 仓库的 /assets 目录。
5. 在 Markdown 里引用。

2. 传统痛点：二进制文件的“死局”

这种“贴图流”最大的问题在于维护成本极高：

• 无法 Diff： Git 无法对比图片的变化。你不知道 V2 版的图比 V1 版改了哪里。
• 同步漂移： 代码逻辑改了（比如登录多了一步验证），但维护者懒得重新打开画图软件修改，导致“图文不符”。这是误导开发者的元凶。

3. 解决方案：Mermaid.js

Mermaid 允许你用“写代码”的方式画图。GitHub 原生支持渲染。

• 版本控制： 图表就是文本，Git 可以完美记录每一行线条的改动。
• 就近维护： 就在 Markdown 文件里写，不用切换软件。

4. AI 赋能：逻辑直接转图表

你不需要专门去学 Mermaid 的语法（比如箭头是 --> 还是 ->>）。你只需要把业务逻辑告诉 AI。

Prompt 范式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Role
系统架构师 & Mermaid 专家

# Task
请分析下方的业务逻辑代码，将其转化为 Mermaid.js 的图表代码，以便我直接嵌入 Markdown 文档。

# Options
1. 如果是 API 交互或鉴权流程，请生成 Sequence Diagram (时序图)。
2. 如果是业务判断逻辑（if/else），请生成 Flowchart (流程图)。
3. 如果是类与继承关系，请生成 Class Diagram (类图)。

# Code Logic
[在此处粘贴你的代码，例如：用户登录的 if/else 判断逻辑]

# Output Requirement
请直接输出 ```mermaid 代码块。

23.3. 构建商业级文档站：Docusaurus + Vercel

README 再好，也承载不了几百页的 API 文档和教程。你需要一个独立的网站。为什么选 Docusaurus？因为它是 React 生态的王者，支持版本控制（V1.0/V2.0 文档共存）、支持博客、支持搜索，且被 Meta、ByteDance、Shopify 等大厂广泛使用，在我的博客文章中，之前教学过如何搭建vitepress作为文档站，所以这次我们选型为技术站为react的文档站，具体文档站的对比可以见下表：

23.3.1. 第一步：脚手架初始化 (Scaffolding)

我们需要在本地创建一个全新的 Docusaurus 项目。

1. 执行创建命令
找一个干净的文件夹，运行以下命令。我们将项目命名为 my-project-docs。

1

pnpm dlx create-docusaurus@latest my-project-docs classic

2. 交互式选择
终端会跳出一些选项，请按以下推荐选择：

• Javascript vs TypeScript: 选 TypeScript（现代前端标配，类型安全）。
• Git init: 选 Yes。

3. 启动预览
进入目录并启动本地服务器，看看它长什么样。

1
2

cd my-project-docs
pnpm start

浏览器会自动打开 http://localhost:3000。
🎉 恭喜！ 你已经拥有了一个包含“文档”、“博客”、“主页”的完整网站雏形。

23.3.2. 第二步：配置核心元数据 (Config)

现在的网站全是 Docusaurus 的默认信息（恐龙图标）。我们需要把它变成“你的”网站。

请使用 VS Code 打开 my-project-docs 文件夹，找到根目录下的 docusaurus.config.ts (或 .js)。这是整个网站的控制中心。

重点修改以下字段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

const config: Config = {
  title: 'My Project Name', // 修改：你的项目名称
  tagline: '这里写一句很酷的 Slogan', // 修改：你的标语
  favicon: 'img/favicon.ico',
  
  // 关键：用于部署生成的 URL 配置
  url: 'https://your-docusaurus-site.vercel.app', // 暂时先填这个占位，后面部署完再改
  baseUrl: '/',

  // 关键：GitHub 仓库信息（用于生成“编辑此页”按钮）
  organizationName: 'your-github-username', // 修改：你的 GitHub 用户名
  projectName: 'my-project-docs', // 修改：这个文档仓库的名字

  themeConfig: {
    // 修改导航栏
    navbar: {
      title: 'My Project',
      logo: {
        alt: 'My Project Logo',
        src: 'img/logo.svg', // 把你的 logo 图片放入 static/img/ 目录并替换
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'tutorialSidebar',
          position: 'left',
          label: '教程', // 修改菜单名称
        },
        {to: '/blog', label: '博客', position: 'left'},
        // 添加你的主项目 GitHub 链接
        {
          href: 'https://github.com/your-username/your-main-project',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    // ... 其他配置
  },
};

实战任务：

1. 修改 title 和 tagline。
2. 在 navbar 里把 GitHub 链接换成你真实的仓库地址。
3. 保存文件，浏览器会自动刷新，你会看到导航栏变

23.3.3. 第三步：推送到 GitHub

在部署之前，我们需要把这个文档项目托管到 GitHub 上。

1. 在 GitHub 上新建仓库

• 打开 GitHub 网页。
• 点击右上角 + -> New repository。
• 仓库名填：my-project-docs (或者 project-name-website)。
• 注意： 这是一个独立的仓库，专门放文档代码，不要和你的业务代码混在一起（除非你用 Monorepo，但新手不推荐）。

2. 关联并推送
回到你的终端（VS Code 里的 Terminal）：

1
2
3
4
5
6
7
8
9

# 如果刚才初始化没做 git init，先做这个
git init
git add .
git commit -m "feat: init docusaurus site"

# 关联远程仓库 (把下面的 URL 换成你刚才新建的仓库地址)
git remote add origin https://github.com/your-username/my-project-docs.git
git branch -M main
git push -u origin main

23.3.4. 第四步：使用 Vercel 一键部署

这是最激动人心的一步。我们将使用 Vercel（Next.js 的母公司，也是前端部署的神器）来发布你的网站。它免费、极速、且自动集成 GitHub。

1. 注册/登录 Vercel
打开 vercel.com，使用 Continue with GitHub 登录。这是必须的，因为我们要授权它访问你的仓库。

2. 导入项目

• 在 Vercel 控制台首页，点击 “Add New…” -> “Project”。
• 在左侧的 “Import Git Repository” 列表中，你应该能看到刚才推送的 my-project-docs。
• 点击该仓库旁边的 Import 按钮。

3. 配置构建 (Build)

• Framework Preset: Vercel 非常智能，通常会自动识别出这是 Docusaurus。如果没有，手动选一下。
• 点击大大的 “Deploy” 按钮。

4. 等待烟花 🎆
屏幕会显示构建日志。大约 30 秒后，你会看到满屏的撒花特效，屏幕上会显示一个链接，类似：
https://my-project-docs-xi8s.vercel.app

点击访问。你的文档站已经上线了！全球可访问！

进阶提示： 以后你只需要在本地修改 Markdown 文件，git commit 并 git push，Vercel 会自动感应到代码变更，自动触发重新部署。这就是 GitOps。

23.3.5. 第五步：闭环——将文档挂载到 GitHub 主页

你的文档站做好了，现在要让所有访问你 GitHub 仓库的人都知道它的存在。

1. 复制 Vercel 的域名
复制刚才 Vercel 生成的那个 https://....vercel.app 链接（如果你有自定义域名更好）。

2. 回到你的“核心代码仓库”
注意，是你的业务代码仓库（不是刚才建的文档仓库）。

3. 编辑 About 信息

• 在仓库首页右侧边栏，找到 About 字样。
• 点击那个小齿轮图标 ⚙️。
• 在 Website 输入框中，粘贴你的文档站链接。
• 勾选 “Use this description, topics, and website…”。
• 点击 Save changes。

效果：
现在，任何人进入你的 GitHub 仓库，第一眼就会在右上角看到一个蓝色的链接图标，指向你专业的 Docusaurus 文档站。这瞬间提升了项目的“正规感”。

25.4. DocOps 实战：给文档装上“自动纠错机”

软件开发中有 DevOps，文档开发中自然也有 DocOps。

你肯定遇到过这种情况：你在文档里写了一个超链接 [点击这里查看详情](./detail-v1)，结果三个月后你重构了目录，把 detail-v1 删了或改名了。用户点击这个链接时，直接跳出 404 错误。这会让用户瞬间对项目失去信任。

靠人眼去检查几百个文件是不可能的。我们需要在 GitHub Actions 里配置一个自动巡检机器人。

25.4.1. 认识死链杀手 Lychee

我们要使用的工具叫 Lychee。它是目前开源界最快、最流行的链接检查工具，支持 Markdown、HTML 等多种格式。它的工作原理是扫描你所有的文本，提取出 http://... 或 ./... 链接，然后挨个去 Ping 一下，如果不通，直接让 CI 报错。

25.4.2. 配置 GitHub Actions 工作流

我们需要创建一个新的工作流文件。请在你的文档仓库根目录下，创建目录和文件：.github/workflows/doc-check.yml。

请直接复制以下内容填入该文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

name: DocOps Quality Check

# 触发机制：任何 Push 或 Pull Request 都会触发
on: [push, pull_request]

jobs:
  # 任务一：链接健康检查
  link-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: 🔗 Lychee Link Checker
        uses: lycheeverse/lychee-action@v1.9.0
        with:
          # 参数解释：
          # --verbose: 输出详细日志
          # --no-progress: CI 环境下不需要进度条
          # './docs/**/*.md': 扫描 docs 下所有 markdown
          # './blog/**/*.md': 扫描 blog 下所有 markdown
          args: --verbose --no-progress './docs/**/*.md' './blog/* */*.md'
          # 如果发现死链，直接让 Action 失败（变红）
          fail: true
        env:
          # 需要 Token 来避免 GitHub API 速率限制
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # 任务二：Markdown 格式规范检查 (可选)
  lint-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
      
      - name: ✍️ Markdown Lint
        uses: DavidAnson/markdownlint-cli2-action@v16
        with:
          # 扫描 docs 目录下的所有文件
          globs: 'docs/**/*.md'

25.4.3. 提交并验证

保存文件后，在终端执行提交：

1
2
3

git add .
git commit -m "ci: add docops workflow"
git push

现在，打开你的 GitHub 仓库页面，点击上方的 Actions 标签。你应该能看到一个名为 DocOps Quality Check 的任务正在运行。

如果你的文档里现在有坏链接，这个任务会变成红色（Failure），点进去看日志，它会精确地告诉你：“在 docs/intro.md 第 15 行，链接 https://google.com/404 无法访问”。

这就是我们要的安全感。

25.5. 拒绝重复造轮子：API 文档自动化

如果你的开源项目是一个 Web 框架、SDK 或者 API 服务，你一定面临过这个痛点：代码里的接口改了，文档忘了改。

最优雅的解决方案是 Single Source of Truth（单一数据源）：代码即文档。我们通过代码注释或 Swagger/OpenAPI 文件，自动生成漂亮的文档页面。

我们将使用 Docusaurus 社区的神级插件：docusaurus-plugin-openapi-docs。

25.5.1. 准备工作：安装依赖

请注意，我们使用 pnpm。在 Docusaurus 项目根目录下运行：

1

pnpm add docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs

这会安装处理 OpenAPI 规范的插件和对应的 UI 主题。

25.5.2. 获取 OpenAPI 规范文件

你需要有一个 openapi.json 或 openapi.yaml 文件。通常你的后端项目（FastAPI, Spring Boot, NestJS）会自动生成这个文件。

为了演示，请在你的文档项目根目录新建一个文件 openapi.yaml，并填入以下最简单的测试内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

openapi: 3.0.0
info:
  title: My Project API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: 获取问候语
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Hello World"

25.5.3. 修改核心配置文件

这是最关键的一步。我们需要告诉 Docusaurus 去哪里找这个 yaml 文件，以及如何渲染它。

打开 docusaurus.config.ts (或 .js)，我们需要修改 presets 和 plugins 两个部分。请仔细对照修改：

第一处修改：Presets 配置
找到 presets 数组中的 classic 部分，修改 docs 下的配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// docusaurus.config.ts

presets: [
  [
    'classic',
    {
      docs: {
        sidebarPath: './sidebars.ts',
        // 添加下面这两行：
        docLayoutComponent: "@theme/DocPage",
        docItemComponent: "@theme/ApiItem", 
      },
      // ... 其他配置保持不变
    },
  ],
],

第二处修改：Plugins 配置
在 presets 之后，添加 plugins 和 themes 配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// docusaurus.config.ts

plugins: [
  [
    'docusaurus-plugin-openapi-docs',
    {
      id: "api", 
      docsPluginId: "classic", // 对应 presets 里的名字
      config: {
        myApi: { // 给你的 API 起个内部代号
          specPath: "openapi.yaml", // 指向刚才创建的文件
          outputDir: "docs/api",    // 自动生成的 Markdown 放哪里
          sidebarOptions: {
            groupPathsBy: "tag",    // 按标签分组显示
          }
        }
      }
    }
  ]
],

themes: ["docusaurus-theme-openapi-docs"], // 激活 OpenAPI 主题

25.5.4. 生成文档并预览

配置完成后，我们需要运行一个命令，让插件读取 YAML 并生成 Markdown 文件。

在终端运行：

1

pnpm docusaurus gen-api-docs all

运行完毕后，请看你的左侧文件树，docs/ 目录下会自动多出一个 api/ 文件夹，里面有一个 my-project-api.mdx 文件。

现在启动本地预览：

1

pnpm start

访问 http://localhost:3000/docs/api/my-project-api。你会看到一个非常专业的 API 调试页面，甚至有一个 “Execute” 按钮可以直接发送请求。

以后你的后端代码更新了，只需要覆盖 openapi.yaml，再次运行生成命令，文档就自动更新了。

25.6. 走向国际化与多版本 (i18n & Versioning)

当你的项目 Star 数超过 1000，或者开始被企业使用时，你会面临两个“幸福的烦恼”：

1. 我发布了 v2.0，API 全改了，但企业用户还在用 v1.0，他们需要看老文档。
2. 我有中文用户，也有英文用户，我需要中英双语文档。

25.6.1. 版本快照 (Versioning) 的魔力

Docusaurus 的版本管理机制非常符合直觉：它会把当前的文档“拍一张照片”存起来。

假设你现在处于 v1.0 开发阶段，准备发布 v2.0 了。你需要把 v1.0 的文档封存。

请在终端运行：

1

pnpm run docusaurus docs: version 1.0.0

运行后，你会发现项目根目录多了一个 versioned_docs 文件夹。

• docs/ 文件夹：这里永远存放**最新、正在开发中（Next）**的文档。
• versioned_docs/version-1.0.0/ 文件夹：这里存放刚才封存的 v1.0.0 文档。

重新运行 pnpm start。哪怕你什么都不改，你会发现网站导航栏的右上角，自动出现了一个 版本下拉菜单。用户可以自由在 Next 和 1.0.0 之间切换。

25.6.2. 国际化 (i18n) 配置实战

要让网站支持中文，我们需要做三件事：配置、提取、翻译。

第一步：修改配置
打开 docusaurus.config.ts，找到 i18n 字段，修改如下：

1
2
3
4
5
6
7
8
9
10
11
12

i18n: {
  defaultLocale: 'en', // 默认语言
  locales: ['en', 'zh-Hans'], // 支持的语言列表
  localeConfigs: {
    en: {
      label: 'English',
    },
    'zh-Hans': {
      label: '简体中文',
    },
  },
},

第二步：提取待翻译内容
Docusaurus 会自动把所有的按钮、导航栏文字、页脚提取出来供你翻译。运行：

1

pnpm run write-translations --locale zh-Hans

这会在 i18n/zh-Hans/ 目录下生成一系列 JSON 文件。

第三步：开始翻译
你需要处理两部分内容：

1. UI 界面翻译：
   打开 i18n/zh-Hans/docusaurus-theme-classic/navbar.json 等文件，把里面的 “Tutorial” 改成 “教程”，“Blog” 改成 “博客”。

2. 文档内容翻译：
   这部分需要你手动复制。将 docs/ 目录下的所有 Markdown 文件，复制到 i18n/zh-Hans/docusaurus-plugin-content-docs/current/ 目录下。然后打开复制过去的 Markdown 文件，把英文内容翻译成中文。

第四步：查看效果
本地预览中文版需要加参数：

1

pnpm start --locale zh-Hans

现在的网站就是全中文的了。

第五步：自动化部署的配合
当你把这些改动 Push 到 GitHub 后，Vercel 会自动识别出 i18n 配置。你不需要做任何额外设置，Vercel 会自动发布两个版本的网站：

• https://yoursite.com/ (英文)
• https://yoursite.com/zh-Hans/ (中文)

第 25 章总结

到此为止，我们已经构建了一套顶级的文档工程体系：

1. 门面： 我们有了规范的 README 和动态徽章。
2. 内核： 我们有了基于 Mermaid 的图表即代码。
3. 载体： 我们用 Docusaurus + Vercel 搭建了独立的商业级文档站。
4. 守卫： 我们用 DocOps (Lychee) 保证了链接永远有效。
5. 同步： 我们用 OpenAPI 插件实现了 API 文档的自动化。
6. 扩展： 我们实现了多版本和多语言支持。

现在，你的项目在“软实力”上已经做好了迎接成千上万用户的准备。

接下来，我们将进入 第二十六章：开源宪法。项目做大了，法律风险也就来了。我们将探讨如何选择开源协议（License），以及如何通过 CLA（贡献者许可协议）来保护你的知识产权。

你准备好进入法律的世界了吗？