用 Markdown 管理报告和技术文档版本

如果报告和技术文档仍然靠“最终版”“最终版-2”“客户确认版”这样的文件名管理，版本很快就会失去边界。更稳妥的做法是：用 Markdown 保存可读的源文件，用 Git 记录每次修改，用标签或分支标记可交付版本，再把图片、附件和生成结果一起纳入发布检查。

先分清三个不同的“版本”

很多混乱来自把三件事混成一个编号：文档内容的修改历史、文档所对应的产品版本，以及已经交付给读者的文件快照。它们应该分别处理。

Git 的基本价值是记录文件内容如何变化，并支持比较和恢复历史状态。它不只适用于源代码，也适用于纯文本报告和 Markdown 文档。Pro Git 关于版本控制对此有清晰说明。

根据文档类型选择版本模型

不要一开始就复制一份“v1”“v2”目录。先看读者需要的是持续更新的内容，还是一份不可改变的交付物。

GitHub Docs 的做法值得参考：用 YAML front matter 指明版本范围，并在同一份 Markdown 中使用条件内容，减少重复维护。这里的方式适合版本差异有限、需要共用大部分正文的技术文档。查看 GitHub Docs 的版本管理说明。

一个能长期维护的目录结构

报告和技术文档最好与代码、示例和图片保持稳定的相对关系。下面的结构足够简单，也能支持版本标签和发布归档：

docs-project/
├── docs/
│   ├── index.md
│   ├── api/
│   │   ├── overview.md
│   │   └── authentication.md
│   └── reports/
│       └── 2026-q3.md
├── assets/
│   ├── api-auth-flow.png
│   └── report-chart-2026-q3.png
├── CHANGELOG.md
└── README.md

图片引用使用相对于 Markdown 文件的路径，例如 ../assets/api-auth-flow.png。不要把电脑本地的绝对路径写进文档，也不要在重命名图片后忘记同步修改引用。站内的Markdown 图片转 Word 后不显示排查指南也覆盖了路径、大小写和打包层级问题。

在 Markdown 文件头部写清适用范围

front matter 不是版本控制系统本身，但它能把“这篇文档适用于什么”放在内容旁边。字段名称可以按你的构建工具调整，重点是保持一致：

---
title: API Authentication
product: DocuCraftBox API
versions:
  api: [v2, v3]
status: maintained
last_reviewed: 2026-09-23
---

This page explains the shared authentication flow.

如果某一段只适用于 v3，不要把整篇文档复制成两份。可以拆成独立的小节、共享变量，或使用构建系统提供的条件语法。只在版本差异真的影响读者操作时才分叉，否则版本目录会比问题本身更难维护。

用分支、提交和标签形成发布流程

一套小团队也能执行的流程如下。关键不是命令数量，而是每一步都留下可以检查的边界：

1. 从当前主线创建文档分支，例如 docs/api-v3-auth。
2. 只在这个分支修改正文、示例、图片和 front matter。
3. 用 git diff 检查命令、参数、链接和版本号。
4. 让熟悉产品的人审阅事实，让熟悉读者的人审阅表达和步骤。
5. 合并后运行文档构建或导出，确认页面、图片、代码示例和附件都能打开。
6. 批准交付后创建不可变标签，例如 docs-2026-q3 或 api-v3.2-docs。

git switch main
git pull
git switch -c docs/api-v3-auth
# edit Markdown, examples, and assets
git diff --check
git add docs/ assets/ CHANGELOG.md
git commit -m "docs: update API authentication for v3"
git push -u origin docs/api-v3-auth

GitHub Docs 的 Git 工作流同样要求检查分支状态、暂存变更、提交、推送，再通过拉取请求合并。

报告和技术文档的发布方式不一样

报告：保留批准时的快照

报告中的数字、结论和图表通常对应一个明确的截止时间。批准后，应把源 Markdown、图片、数据说明和导出文件绑定到同一个 tag 或归档目录。后续如果发现错误，创建新的修订版本，并写清旧版本是否仍然有效。

技术文档：标记支持范围

技术文档更关注“读者现在应该执行哪一步”。当前版本可以持续更新，但旧 API 或旧产品版本仍需要一个清楚的入口。对于只改文字的修订，保留同一个页面通常更合适；对于参数、行为或接口发生不兼容变化的版本，应该明确分流。

CHANGELOG 应该记录影响，不是复制提交日志

提交记录面向维护者，CHANGELOG 面向需要判断“我是否要更新”的读者。每条记录至少回答：哪个版本发生了变化、变化会影响谁、读者需要做什么。

# Changelog

## 3.2.0 - 2026-09-23

### Changed
- API authentication examples now use the v3 header names.

### Fixed
- Corrected the relative path for the authentication flow image.

Common Changelog建议按版本倒序组织内容，按 Added、Changed、Removed、Fixed 等影响分类，并把每项变化链接到更详细的信息。

图片、附件和导出文件也要进入版本边界

Markdown 文本可以直接比较，但二进制附件通常不能像文本那样审阅。图表、截图、CSV、DOCX 和 PDF 应该与引用它们的 Markdown 版本一起保存。至少检查四件事：

• 文件名是否稳定，避免使用“final-new”这类含义不清的命名。
• 相对路径在本地预览、构建环境和归档包中是否一致。
• 图表中的数字是否与报告对应的时间范围一致。
• 导出 DOCX 或 PDF 是否来自当前 tag，而不是作者电脑上的未提交文件。

如果需要把报告截图或图表整理成可分享的 PDF，可以另外查看 Images to PDF 工具。它适合作为已完成版本的输出环节，不应替代 Markdown 源文件和 Git 历史。

合并前的 10 分钟检查

1. 打开 diff，确认没有把草稿备注、临时路径或本地密钥提交进去。
2. 检查标题层级是否跳级，代码块是否仍能复制。
3. 逐个打开外部链接和内部链接，确认锚文本说明了目标。
4. 检查图片是否存在、尺寸是否适合页面，并为有信息的图片写 ALT。
5. 确认版本号、发布日期、API 参数和示例输出来自同一个范围。
6. 构建一次网站或导出一次文档，再查看最终结果。
7. 确认 CHANGELOG 说明了读者可感知的影响。
8. 批准后创建 tag，并记录生成文件对应的 commit。

常见问题排查

FAQ

Markdown 文件需要单独写版本号吗？

不一定。Git commit 和 tag 已经能记录修改与发布边界，但页面还需要告诉读者适用的产品或 API 版本。把两个问题分别处理，通常比只在文件头写一个数字更清楚。

报告应该用分支还是 tag？

分支适合准备和审阅阶段，tag 适合批准后的固定快照。可以先在分支中修改和讨论，确认交付后再创建 tag。

什么时候应该复制一份新文档？

当旧版本仍需要独立访问，且新旧版本的操作结果不同，才值得保留独立版本入口。纯粹的错别字、链接修正和表达改进，通常直接更新当前页面即可。

Git 能代替文档审阅吗？

不能。Git 能告诉你发生了什么变化，但不能判断参数是否正确、截图是否过时，也不能替你验证读者能否完成操作。事实审阅、链接检查和最终渲染仍然需要明确的检查步骤。

下一步

先选一份最近仍在修改的报告或 API 文档，把源文件、图片和导出文件放入同一个目录。然后创建文档分支，补上适用版本字段，完成一次 diff 审阅，最后用 tag 固定第一个可交付版本。这个流程跑通后，再决定是否需要版本选择器、自动构建或条件内容。

参考资料

• Pro Git：关于版本控制。
• GitHub Docs：在 GitHub Docs 上使用 Git。
• GitHub Docs：Versioning documentation。
• Common Changelog。