设置版本控制¶
Material for MkDocs 通过与外部工具的集成，使得部署多个版本的项目文档变得简单，这些工具为 MkDocs 添加了这些功能，例如 mike。在部署新版本时，旧版本的文档保持不变。
配置¶
版本控制¶
mike 使得部署多个版本的项目文档变得简单。它与 Material for MkDocs 原生集成，并可以通过 mkdocs.yml 启用：
这将在页眉中渲染一个版本选择器：
查看版本控制示例以了解其工作原理 – mkdocs-material.github.io/example-versioning
mike 的构建理念是，一旦你为特定版本生成了文档，你就不应该再需要触碰该版本。这意味着你不必担心 MkDocs 中的破坏性更改，因为你的旧文档（使用旧版本的 MkDocs 构建）已经生成并保存在你的 gh-pages 分支中。
虽然 mike 是灵活的，但它的优化是将文档放在 <major>.<minor> 目录中，并为特别显著的版本提供可选别名（例如 latest 或 dev）。这使得为你希望引导用户访问的文档版本创建永久链接变得简单。
切换版本时保持在同一页面¶
当用户在版本选择器中选择一个版本时，他们通常希望转到与之前查看的页面相对应的页面。Material for MkDocs 默认实现了这一行为，但有几个注意事项：
版本警告¶
如果你正在使用版本控制，你可能希望在用户访问任何非最新版本时显示警告。使用 主题扩展，你可以 覆盖 outdated 块：
{% extends "base.html" %}
{% block outdated %}
你正在查看的不是最新版本。
<a href="{{ '../' ~ base_url }}"> <!-- (1)! -->
<strong>点击这里查看最新版本。</strong>
</a>
{% endblock %}
- 给定这个
href属性的值，链接将始终重定向到你网站的根目录，然后再重定向到最新版本。这确保了你网站的旧版本不依赖于特定别名，例如latest，以便后续更改别名时不会破坏早期版本。
这将在页眉上方渲染一个版本警告：
默认版本由 latest 别名标识。如果你希望将另一个别名设置为最新版本，例如 stable，请在 mkdocs.yml 中添加以下行：
-
你还可以将多个别名定义为默认版本，例如
stable和development。现在每个具有
stable和development别名的版本将不会显示版本警告。
确保一个别名与 默认版本 匹配，因为这是用户被重定向到的地方。
版本别名¶
9.5.23 false
如果你正在使用版本别名，并希望在版本号旁边显示版本别名，可以通过将 alias 选项设置为 true 来启用此功能：
使用¶
虽然本节概述了发布新版本的基本工作流程，但最好查看 mike 的文档 以熟悉其机制。
发布新版本¶
如果你想发布项目文档的新版本，请选择一个版本标识符，并使用以下命令更新设置为默认版本的别名：
请注意，每个版本将作为你 site_url 的子目录进行部署，应该明确设置。例如，如果你的 mkdocs.yml 包含：
文档将发布到如下 URL：
- docs.example.com/0.1/
- docs.example.com/0.2/
- ...
设置默认版本¶
在开始使用 mike 时，设置一个别名作为默认版本（例如 latest）是个好主意，并且在发布新版本时，总是更新别名以指向最新版本：
在发布新版本时，mike 将在你的项目文档的根目录创建一个重定向到与别名关联的版本：
docs.example.com docs.example.com/0.1