企业官网建设流程全解析

Material for MkDocs 多版本文档部署指南：基于 mike 的版本选择器、默认版本与版本警告配置

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material

本篇指南围绕 Material for MkDocs 的版本化部署能力展开，讲解如何通过外部工具 mike 在同一站点下维护多个版本的文档快照，在页头渲染版本选择器，并完成「默认版本」「版本别名」「过期版本警告」等配套配置。读完本文后，你将掌握从mkdocs.yml配置到mike命令行发布、再到基于主题扩展定制版本警告的完整实战链路。

本文以仓库文档 setting-up-versioning.md 为主体，并结合主题源码（src/templates/下的模板与 TypeScript 实现）对配置项的底层行为作补充说明。

为什么选择 mike：一次构建、永不回改

Material for MkDocs 本身并不提供多版本渲染能力，而是通过与外部工具集成来完成。官方推荐的方案是 mike。它的核心设计理念是：文档针对某一特定版本构建完成后，就再也不会被改动。这意味着你完全不用担心旧版文档因为 MkDocs 自身的破坏性升级而失效——旧版文档早已用当时的 MkDocs 构建好，静静地存放在你的gh-pages分支里。

mike 的目录策略也很有讲究：它围绕<major>.<minor>形式的主版本目录组织文档，并允许通过别名（alias）（例如latest或dev）指向某些值得特别标记的版本。这样一来，你可以轻松构造指向任意版本文档的永久链接（permalinks），把用户稳定地导向他们该看的版本。

配置版本化部署

基础配置：开启版本选择器

在mkdocs.yml中为extra.version指定provider: mike即可启用版本化功能：

extra: version: provider: mike

启用后，页头会渲染一个版本选择器下拉框，用于在已发布的各版本文档之间切换：

从主题源码看，版本化功能是主题与 mike 插件的协作产物。src/templates/base.html 中有一段关键逻辑：主题读取config.extra.version后，会检查 mike 插件是否已加载以及其version_selector配置；只有在「未安装 mike 插件」或「mike 插件允许显示版本选择器」时，版本配置才会被注入到页面内联配置__config中（见 src/templates/base.html）。换言之，如果你同时配置了 mike 插件并显式关闭其选择器，主题的版本选择器也会随之隐藏。

切换版本时停留在当前页面

用户在版本选择器中选择某个版本后，通常会期望跳转到与当前浏览页面相对应的那一页（例如正在读「安装指南」，切到旧版本后仍停留在「安装指南」）。Material for MkDocs 默认实现了这一行为，但有两个前提条件需要注意：

• mkdocs.yml中的site_url必须正确设置，详见下文 发布新版本 小节中的示例；
• 跳转通过 JavaScript 在客户端完成，无法提前得知重定向目标页。

其底层实现位于 src/templates/assets/javascripts/integrations/version/index.ts：主题首先请求当前站点根目录下的versions.json获取全部版本列表，再借助 sitemap/index.ts 中fetchSitemap拉取目标版本的sitemap.xml，最后通过 findurl/index.ts 中selectedVersionCorrespondingURL函数，将「当前页面相对路径 + 目标版本基地址」与目标版本的 sitemap 做最长公共前缀匹配，确认对应页面在目标版本中确实存在后才执行跳转，同时保留当前的 hash 与 query 参数。若目标版本中不存在对应页面，则回退到该版本的首页。

版本警告：提示用户当前不是最新版

如果你开启了版本化，往往希望用户访问非最新版本时看到一条警告提示。借助主题扩展，你可以通过覆盖outdated块来自定义警告内容，例如：

{% extends "base.html" %} {% block outdated %} You're not viewing the latest version. <a href="{{ '../' ~ base_url }}"> <!-- (1)! --> <strong>Click here to go to latest.</strong> </a> {% endblock %}

1. 链接的href指向站点根目录，再由根目录重定向到最新版本。这样设计是为了让旧版本页面不依赖某个具体别名（如latest），从而允许日后更改别名而不破坏历史版本上的链接。

覆盖后，警告横幅会渲染在页头之上：

模板层面，src/templates/base.html 在config.extra.version存在时输出一个data-md-component="outdated"的容器，其中嵌入了可覆盖的{% block outdated %}，并引入partials/javascripts/outdated.html来控制横幅的显示。JavaScript 层面，src/templates/assets/javascripts/integrations/version/index.ts 会判断当前版本是否属于「默认版本」集合，并将判定结果持久化到sessionStorage的__outdated键中；只有判定为过期版本时，横幅才会被取消隐藏。同时，该状态与 instant navigation 集成，页面切换时横幅行为保持一致。

指定默认版本

默认情况下，主题通过latest别名来识别默认（最新）版本。如果你想改用其他别名（例如stable）作为默认版本，在mkdocs.yml中追加：

extra: version: default: stable # (1)!

1. 也可以将多个别名定义为默认版本，例如stable和development：

   extra: version: default: - stable - development

   此时，凡是同时带有stable与development别名的版本都不会再显示版本警告。

对应到源码：src/templates/assets/javascripts/integrations/version/index.ts 中，config.version?.default默认取"latest"，支持标量或数组两种写法；随后会用正则（new RegExp(ignore, "i")，即大小写不敏感的部分匹配）逐一比对该版本的别名与版本号，只要命中任一默认别名即判定为「非过期版本」。

务必确保至少有一个别名匹配默认版本，因为这是用户被重定向到的目标版本。

版本别名：在版本号旁显示别名

当使用别名管理版本时，你可以在版本号旁边同时展示该版本对应的别名，只需开启alias选项：

extra: version: alias: true

该选项的默认值为false。渲染逻辑位于 src/templates/assets/javascripts/templates/version/index.tsx：主题为每个版本生成一个<li class="md-version__item">条目，当config.version?.alias为真且该版本存在别名时，会额外输出一个<span class="md-version__alias">来展示第一个别名；当前激活版本的下拉按钮同样会附加别名徽标（见同文件 renderVersionSelector）。此外，模板还会过滤掉带有hidden属性的版本，使其不出现在选择器列表中。

日常使用：用 mike 发布与管理版本

以下内容概述发布新版本的基本工作流。mike 本身功能灵活，更完整的机制说明建议查阅 mike 的官方文档。

发布新版本（Publishing a new version）

要为项目文档发布新版本，请选定一个版本标识，并同步更新默认版本指向的别名，执行：

mike deploy --push --update-aliases 0.1 latest

需要注意：每个版本都会作为site_url下的一个子目录部署，因此site_url应被显式设置。例如mkdocs.yml中包含：

site_url: 'https://docs.example.com/' # 推荐使用结尾斜杠

则文档会被发布到形如以下 URL 的位置：

• docs.example.com/0.1/
• docs.example.com/0.2/
• ...

--push会把部署结果推送到远程分支（通常是gh-pages），--update-aliases则让新版本继承并更新所指定的别名，从而保证latest始终指向最新的发布。

设置默认版本（Setting a default version）

刚开始使用 mike 时，建议设置一个别名（例如latest）作为默认版本，并在每次发布新版本时更新该别名，使其始终指向最新版本：

mike set-default --push latest

发布新版本后，mike 会在项目文档的根目录创建一条重定向，指向该别名关联的版本：

docs.example.com:octicons-arrow-right-24:docs.example.com/0.1

这样，访问根域名（例如docs.example.com）的用户会被自动带到当前默认版本的文档，而无需记忆具体的版本号路径。

主题自定义入口速查

与版本化相关的自定义点总结如下：

其中「覆盖块（Overriding blocks）」是 Material for MkDocs 主题扩展（extending the theme）的核心机制，outdated正是系统预定义的若干可覆盖块之一，详见 docs/customization.md 中的块清单。

【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material