版本控制

M-Doc 的核心特色是文档级版本管理，借鉴 Git 的设计理念，让文档像代码一样可追溯、可分支、可并行维护。

---

核心概念

文档版本

每本文档可以拥有多个版本，类似 Git 的分支：

文档：产品手册
├── master（默认版本）
├── v1.0.0
├── v2.0.0
└── feature-new-api（开发中）

• 默认版本：新创建文档时自动创建的 master 版本
• 发布版本：如 v1.0.0、v2.0.0，用于标记稳定的文档快照
• 开发版本：临时分支，用于并行开发新版本文档

文章版本

每篇文章独立维护版本历史：

• 每次发布都生成一个版本快照（类似 Git commit）
• 包含 commit_hash（SHA1）、提交说明、作者、时间戳
• 支持查看历史版本和回退

创建新版本

1. 进入文档页面
2. 点击版本选择器旁的「新建版本」
3. 输入版本名称（如 v2.0.0）
4. 选择基于哪个版本创建（Fork）
5. 点击「创建」

新版本会复制源版本的所有文章和目录结构。

Fork（派生）版本

Fork 操作基于已有版本创建新分支：

v1.0.0 ──fork──> v1.1.0（修复文档）
       ──fork──> v2.0.0（大版本更新）

Fork 后，两个版本的文章可以独立编辑，互不影响。

Diff（版本对比）

M-Doc 支持两个版本之间的差异对比：

1. 进入文档页面
2. 点击「版本对比」
3. 选择源版本和目标版本
4. 查看差异

对比结果以高亮方式展示：

• 🟢 新增的内容
• 🔴 删除的内容
• 🟡 修改的内容

多版本并行维护

M-Doc 支持同时维护多个版本的文档，这在以下场景特别有用：

• 产品多版本共存：v1.x 和 v2.x 同时提供服务
• 新版本开发：在不影响线上文档的情况下编写新版本
• 修复旧版文档：在旧版本中单独修复错误

最佳实践

1. 使用语义化版本号：v1.0.0、v1.1.0、v2.0.0
2. 保持 master 为最新开发版本
3. 发布稳定版本后，设置为默认版本
4. 旧版本仅修复错误，不添加新内容

设置默认版本

默认版本是用户访问文档时看到的版本：

1. 进入文档设置
2. 在「默认版本」中选择目标版本
3. 保存设置

访问 https://mdoc.cc/{org}/{doc} 时会自动展示默认版本的内容。