技能介绍

要解决的问题

MkDocs 默认会把当前文档树构建成一组静态站点。当库升级、API 变化或文档按版本拆分时，直接覆盖 gh-pages 会让旧版说明消失，读者只能看到“当前”文档。对需要保留历史版本、迁移说明或版本化 API 参考的项目来说，部署目标需要版本寻址能力，而不只是“最新构建”。

技能如何工作

将 MkDocs 产物发布到 Git-backed 部署目标，例如 gh-pages，让每个版本有独立入口，而不是反复覆盖同一目录。
当 agent 判断需要多版本文档时，使用 mike 把某个文档快照发布到明确版本键下，例如 1.8.0。
维护版本列表与入口；新版本可以新增，旧版本可以保留或按需下架。
设置默认版本或稳定别名，让根路径指向希望读者首先看到的版本；必要时再调整稳定版本。
发布前确认 MkDocs 配置、主题和依赖仍能构建目标快照，避免把构建错误带进版本目录。

适用边界与注意点

适合：有明确版本号、需要长期保留旧文档、使用 GitHub Pages 等 Git-backed 托管的 MkDocs 项目。

不适用：文档只有一个 canonical 版本，或团队不愿维护多套版本目录与别名。

注意：上游流程依赖 Python、MkDocs、Git-backed 部署目标和 mike。由于 mike 是 Python 项目，它依赖 setuptools，其 mike.themes entry point 指向 Python 子模块；目标环境需要能正确加载 mike 及其主题机制。