问题

当产品引入重大版本变更时，某些 API、功能或配置不可避免地会被弃用或删除。浏览最新文档的用户必须清楚地知道他们是否正在使用过时的模式，但为了避免混淆，文档本身应集中于现代实现。

为什么重要

未能明确提示重大变更会导致开发者浪费数小时调试引擎不再支持的代码。上下文警告和清晰的迁移路径对于维护用户信任、减少支持请求以及确保顺利过渡到软件的最新版本至关重要。

方法

将 docmd 的 版本控制引擎 与 标注容器 (Callout Containers) 相结合，在旧版内容和现代内容之间建立清晰的区别。策略是将完整的旧版文档移至归档版本，同时在当前版本中提供链接回归档内容的“迁移锚点”。

实施

1. 归档旧版内容

发布新的大版本（例如 v2.0）时，将现有文档移至归档目录（例如 docs-v1/）。这可确保为尚未迁移的用户保留前一版本的完整上下文。

2. 上下文迁移标注

在最新文档中，在发生重大变更的页面顶部使用 warning（警告）或 important（重要）标注。这为试图使用旧模式的用户提供了即时价值。

# 配置 API

::: callout warning "迁移：v2.0 中的重大变更"
`siteTitle` 属性已被移除。它已被全局 `title` 属性取代。

* **从 v1.x 迁移？** 请更新您的 `docmd.config.js`。
* **需要 v1.x 文档？** 请参阅 [旧版配置指南](/v1/configuration/general)。
:::

3. 保持 AI 准确性

通过严格将已弃用的内容与当前版本分开，您可以显著提高 AI 工具的准确性。docmd 的 LLMs 插件 会根据活动版本生成上下文文件。归档旧内容可以防止 AI 模型“产生幻觉”，并向寻找现代解决方案的用户推荐过时的 API。

权衡

主动管理迁移标注会增加维护开销。如果无限期保留，页面可能会充斥着旧的警告。我们建议建立一种策略，即在旧版本达到其生命周期终点 (EOL) 或在一个完整的大版本发布周期后移除迁移标注，以保持文档精简和专注。