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 %} Youre not viewing the latest version. a href{{ ../ ~ base_url }} !-- (1)! -- strongClick here to go to latest./strong /a {% endblock %}链接的href指向站点根目录再由根目录重定向到最新版本。这样设计是为了让旧版本页面不依赖某个具体别名如latest从而允许日后更改别名而不破坏历史版本上的链接。覆盖后警告横幅会渲染在页头之上模板层面src/templates/base.html 在config.extra.version存在时输出一个data-md-componentoutdated的容器其中嵌入了可覆盖的{% 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)!也可以将多个别名定义为默认版本例如stable和developmentextra: 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 classmd-version__item条目当config.version?.alias为真且该版本存在别名时会额外输出一个span classmd-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的用户会被自动带到当前默认版本的文档而无需记忆具体的版本号路径。主题自定义入口速查与版本化相关的自定义点总结如下自定义点说明参考位置extra.version.provider启用 mike 版本化设置版本化extra.version.default指定默认版本别名支持多个指定默认版本extra.version.alias在版本号旁显示别名版本别名outdated块覆盖版本警告横幅内容docs/customization.mdmike 插件version_selector控制主题是否注入版本选择器配置src/templates/base.html版本选择器 / 警告渲染前端渲染与跳转逻辑version/index.ts、version/index.tsx其中「覆盖块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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考