Material for MkDocs 升级完全指南从 3.x 到 9.x 的配置迁移与模板兼容【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material本篇指南以 docs/upgrade.md 为骨架系统梳理 Material for MkDocs 从 3.x 一路升级到 9.x 过程中所有需要关注的破坏性变更mkdocs.yml中的配置项重命名与结构调整、内置插件的行为变化、主题模板*.html的结构演进以及自定义 CSS 的兼容性问题。读完本文你将掌握当前版本中各项功能代码复制按钮、页面编辑/查看按钮、页脚导航、站点分析、搜索、内容标签等的正确配置方式并能在升级后快速定位因自定义覆盖overrides导致的功能失效问题。升级基础安装与版本确认升级到最新版本只需一行命令使用--force-reinstall确保覆盖本地可能存在的旧版本文件pip install --upgrade --force-reinstall mkdocs-material查看当前已安装的版本pip show mkdocs-material在执行任何大版本迁移之前建议先确认当前版本再对照下文相应小节逐项检查mkdocs.yml与自定义模板。如果你从未定义过某个配置项则对应小节可以安全跳过——文档明确说明只有你定义过的键才需要调整。从 8.x 升级到 9.x全新搜索与功能标志化9.x 是一次重要的大版本发布核心变化是引入了全新的搜索实现更快、支持富预览rich previews、高级分词advanced tokenization与更好的高亮效果。该实现此前长期仅在 Insiders 版本中提供随着资金目标达成进入社区版。新搜索的前端运行时位于 src/templates/assets/javascripts插件侧的配置解析与索引构建逻辑可在 src/plugins/search/plugin.py 中查看。content.code.copy复制按钮改为按需启用从 9.x 开始代码块的复制到剪贴板按钮默认不再显示且支持按块开启或关闭。若希望所有代码块都显示复制按钮在mkdocs.yml中加入theme: features: - content.code.copycontent.action.*编辑与查看按钮显式开启页面右上角紧邻编辑此页按钮的查看源码按钮现在两者都必须显式启用theme: features: - content.action.edit - content.action.view在源码层面这两个功能由 src/templates/partials/actions.html 实现模板先判断page.edit_url是否存在再分别检查content.action.edit与content.action.view是否出现在features中查看按钮还会自动将 URL 中的blob/edit段替换为raw以指向原始文件。当前仓库自身的 mkdocs.yml 即同时启用了这两个标志。navigation.footer页脚前后翻页改为可选页脚中的上一页 / 下一页导航按钮现在是可选项。若希望保留加入theme: features: - navigation.footertheme.language韩语与挪威语代码重命名两个不符合 ISO 标准的语言代码被重命名为标准形式kr→ko韩语no→nb挪威语在仓库中可以看到 src/templates/partials/languages 目录下存在ko.html与nb.html而不再有kr与no文件。feedback.ratings占位符必须使用命名形式旧的匿名占位符已废弃数月被移除。反馈链接必须改用新的命名占位符{title}与{url}https://github.com/.../issues/new/?title[Feedback]{title}-{url}在 src/templates/partials/feedback.html 中可以看到运行时会对rating.note执行replace({url}, url)与replace({title}, title)title取页面元数据标题或页面标题并做 URL 编码。模板变更与内置插件命名空间9.x 对主题模板做了一轮重构。若你通过主题扩展theme extension自定义过模板务必把最新改动同步进去。如果升级后发现某个内置插件搜索或标签没有任何报错却不再工作极有可能与自定义覆盖overrides有关MkDocs 1.4.1 及以上版本允许主题为内置插件添加命名空间Material for MkDocs 9 现在对内置插件统一使用material/前缀以允许作者使用与内置插件同名的第三方插件。具体做法在覆盖模板中搜索in config.plugins将涉及的插件名加上material/前缀。受影响的 partial 包括src/templates/partials/content.htmlsrc/templates/partials/header.html从源码可以印证这一命名空间机制例如 src/plugins/blog/plugin.py 中生成文件标记为material/blogsrc/plugins/blog/structure/init.py 通过config.plugins.get(material/meta)获取元数据插件src/plugins/projects/structure/init.py 中同时接受projects与material/projects两种写法src/plugins/tags/config.py 则把listings_directive的默认值设为material/tags。搜索覆盖内容时可将material/前缀视为插件名的一部分进行匹配。从 7.x 升级到 8.x注解、锚点与模板重构新增能力一览新增代码注解code annotations支持新增锚点追踪anchor tracking支持新增版本警告version warning支持新增独立的copyrightpartial便于覆盖移除废弃的内容标签content tabs旧实现移除废弃的seealso提示admonition类型移除废弃的site_keywords设置MkDocs 不支持移除废弃的预构建搜索索引支持移除废弃的 Web App Manifest改用自定义方案移除extracopyright变量改用新的copyrightpartial移除 Disqus 集成改用自定义方案简单选择器列表切换为:is()选择器autoprefixer 从last 4 years调整为last 2 yearsCSS 整体向现代标准看齐字体相关 CSS 变量语义改进通过重构 partials 提升可扩展性改进打印时details元素的处理改进脚注的键盘导航修复 #3214搜索高亮在站点为空时破坏页面pymdownx.tabbed必须启用新样式旧版 Tabbed 扩展的样式支持被移除必须切换到新的、在移动端视口表现更好的替代实现 8.x yaml markdown_extensions: - pymdownx.tabbed: alternate_style: true 7.x yaml markdown_extensions: - pymdownx.tabbed Tabbed 扩展的完整用法见 docs/setup/extensions/python-markdown-extensions.md。pymdownx.superfences移除*-experimental后缀自定义围栏custom fence类属性中的*-experimental后缀必须移除。该配置用于把代码块交给 Mermaid.js 渲染为图表详见 docs/reference/diagrams.md 8.x yaml markdown_extensions: - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format 7.x yaml markdown_extensions: - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid-experimental format: !!python/name:pymdownx.superfences.fence_code_format SuperFences 扩展的完整说明见 docs/setup/extensions/python-markdown-extensions.md。当前仓库 mkdocs.yml 使用的即是去掉后缀的class: mermaid写法。google_analytics迁移到extra.analyticsgoogle_analytics自 MkDocs 1.2.0 起被废弃因为基于 JavaScript 的分析集成实现属于主题职责。需要按如下方式迁移 8.x yaml extra: analytics: provider: google property: UA-XXXXXXXX-X 7.x yaml google_analytics: - UA-XXXXXXXX-X - auto 当前仓库的 mkdocs.yml 即采用extra.analytics.provider: google的新结构分析模板位于 src/templates/partials/integrations/analytics。模板变更8.x 对模板做了一轮面向未来的重构。如果你通过主题扩展覆盖过 block 或 template需要同步新结构若覆盖的是block检查 src/templates/base.html 是否有变化若覆盖的是template检查对应的*.html文件是否有变化base.html的核心变更包括移除keywords相关 meta 标签page.meta.keywords/config.site_keywords均被废弃字体 CSS 变量由--md-text-font-family/--md-code-font-family简化为--md-text-font/--md-code-font移除 Web App Manifest 链接块config.extra.manifestpartials/javascripts/base.html从body底部移动到head中公告栏announce类名由md-banner md-announce收敛为md-banner新增版本警告区块当config.extra.version存在时渲染data-md-componentoutdated横幅并引入 src/templates/partials/javascripts/outdated.html页面主体内容整合为单一{% include partials/content.html %}对应 src/templates/partials/content.html编辑按钮、h1 兜底、正文、源文件信息统一由该 partial 承载移除disqusblockpartials/footer.html的变更原内联的版权信息区块抽取为独立的 src/templates/partials/copyright.html同时渲染config.copyright高亮与Made with Material for MkDocs徽标除非config.extra.generator falseextracopyright变量被移除社交链接区块改为{% if config.extra.social %}条件包裹partials/social.html的变更外层md-footer-social重命名为md-social链接图标从字体图标改为内联 SVG{% include .icons/ ~ social.icon ~ .svg %}title由链接域名推导从 6.x 升级到 7.x响应式架构重写新增能力一览新增多版本部署支持新增语言选择器集成新增内联 admonition 渲染支持底层响应式架构重写弃用 Webpack改为响应式构建策略减少 480 个依赖修复内容标签切换后代码块键盘导航失效的问题extra.version.method→extra.version.provider版本化方法配置被重命名为extra.version.provider以便未来支持不同的版本化策略 7.x yaml extra: version: provider: mike 6.x yaml extra: version: method: mike 版本化功能的使用说明见 docs/setup/setting-up-versioning.md。模板变更base.html的核心变更字体引入方式由body,input{font-family:...}全局规则改为在:root上定义--md-text-font-family/--md-code-font-family变量侧边栏组件重命名主侧边栏data-md-componentnavigation、次侧边栏data-md-componenttoc统一为data-md-componentsidebar并以data-md-type区分导航/目录内容区新增data-md-componentcontent新增md-dialog对话框组件容器脚本引导方式重构新增configblock把base、features、translations、searchworker 路径、version聚合为app字典通过__configJSON 注入页面__lang内联脚本移除JavaScript bundle 由 vendor bundle 两个文件收敛为单个bundle.926459b3.min.js以当前构建产物为准partials/footer.htmlmd-footer-nav前缀类名全部重命名为md-footer__inner/md-footer__link/md-footer__button/md-footer__title/md-footer__direction。partials/header.htmlmd-header-nav前缀类名全部改为md-header__inner/md-header__button/md-header__title/md-header__topic新增md-header__options区块当配置了config.extra.alternate时渲染语言选择器md-select其图标默认取material/translatepartials/source.html仓库链接元素增加data-md-componentsource标记。partials/toc.html目录列表增加data-md-componenttoc。从 5.x 升级到 6.x功能标志统一前缀新增能力一览改进搜索结果的观感与输入时的稳定性改进搜索结果分组页面 标题改进搜索结果相关性与评分搜索结果中显示缺失的查询词供应商包体积减少 25%84kb → 67kb减小 Docker 镜像体积以提升 CI 构建性能移除 hero partial改为自定义实现移除废弃的 front matter 特性theme.features功能标志加组件前缀所有可从mkdocs.yml启用的功能标志如 tabs、instant loading现在都以所属组件或功能命名例如navigation.* 6.x yaml theme: features: - navigation.tabs - navigation.instant 5.x yaml theme: features: - tabs - instant 导航功能标志的完整清单见 docs/setup/setting-up-navigation.md其中 navigation.tabs 与 instant loading 是本次重命名的直接对象。模板变更base.html的核心变更顶部的palette/font变量定义移入各自使用处改为在块内{% set %}延迟求值移除基于page.meta.redirect的 JS 重定向与meta refresh逻辑改为仅保留 canonical 标签调色板相关逻辑重构palette.css的引入条件改为config.theme.palette是否存在theme-colormeta 标签移入该条件块内新增基于prefers-color-scheme的scheme: preference实验性脚本hero 区块移除自动渲染逻辑{% block hero %}{% endblock %}变为空占位同时删除 src/templates/partials/hero.html 与source-linkpartialtabs 判断由tabs in config.theme.features改为navigation.tabs in config.theme.features新增搜索翻译键search.result.more.one、search.result.more.other、search.result.term.missing新增跳过导航skip link与公告栏announce组件md-overlay移除data-md-component标记从 4.x 升级到 5.x响应式架构与图标体系重构新增能力一览响应式架构——在控制台执行#!js app.dialog$.next(Hi!)即可体验Instant loading——让 Material 表现得像单页应用SPA通过 CSS 变量改进定制能力见 docs/setup/changing-the-colors.md改进 CSS 健壮性例如自定义头部时侧边栏正确锁定改进图标集成与配置主题内置超过 5000 个图标见 docs/reference/icons-emojis.md任何图标都可用于 logo、仓库与社交链接搜索 UI 不再卡顿迁移至 Web Worker使用 instant loading 时搜索索引只构建一次改进可扩展的键盘处理支持预构建搜索索引见 docs/plugins/search.md支持显示 GitLab 仓库的 star 与 fork 数侧边栏与搜索结果支持滚动吸附scroll snapping因放弃 Internet Explorer 支持而减小 HTML 与 CSS 体积部分 UI 元素admonition、表格等观感微调theme.feature→theme.features布尔键改为标志列表可选功能如 tabs、instant loading现在实现为标志flag通过mkdocs.yml的theme.features列表启用 5.x yaml theme: features: - tabs - instant 4.x yaml theme: feature: tabs: true theme.logo.icon→theme.icon.logoLogo 图标配置集中到theme.icon.logo下可选用主题内置的任何图标 5.x yaml theme: icon: logo: material/cloud 4.x yaml theme: logo: icon: cloud extra.repo_icon→theme.icon.repo仓库图标配置集中到theme.icon.repo下 5.x yaml theme: icon: repo: fontawesome/brands/gitlab 4.x yaml extra: repo_icon: gitlab extra.search.*→ 搜索插件配置搜索现在作为插件选项进行配置见 docs/plugins/search.md。搜索语言必须写成字符串数组tokenizer重命名为separator 5.x yaml plugins: - search: separator: [\s\-\.] lang: - en - de - ru 4.x yaml extra: search: language: en, de, ru tokenizer: [\s\-\.] 对应地搜索插件的配置结构可以在 src/plugins/search/config.py 中看到支持lang、separator、pipeline、fields以及中文分词相关的jieba_dict/jieba_dict_user其中pipeline的可选值为stemmer、stopWordFilter、trimmer。字段权重在 src/plugins/search/plugin.py 中合并默认值标题boost: 1e3、正文1e0、标签1e6。extra.social.type→extra.social.icon社交链接位置不变但type键重命名为icon以匹配新的图标指定方式 5.x yaml extra: social: - icon: fontawesome/brands/github-alt link: https://github.com/squidfunk 4.x yaml extra: social: - type: github link: https://github.com/squidfunk 模板变更base.html的核心变更移除theme.feature布尔配置读取与lang:前缀的 meta 标签search.language、search.tokenizer等样式表文件名从application.*.css/application-palette.*.css改为main.*.min.css/palette.*.min.css移除modernizr脚本与material-icons.css字体链接移除内联的 SVG 符号md-svg__github/__gitlab/__bitbucket与md-overlay的组件标记新增跳过导航md-skip与公告栏md-announce组件direction改为config.theme.direction | default(lang.t(direction))编辑按钮由内联字符实体改为内联 SVGmaterial/pencil.svg源码日期渲染抽取为 src/templates/partials/source-date.html脚本区重构vendor bundle 双文件__langJSON 注入翻译initialize()引导改为接收base、features、search.worker参数其他 partial 变更partials/footer.html类名规范化并增加aria-label箭头图标改为内联 SVGmaterial/arrow-left.svg/material/arrow-right.svgpartials/header.htmllogo 区改为引入 src/templates/partials/logo.html优先config.theme.logo图片否则回退到config.theme.icon.logo默认material/library菜单/搜索图标改为内联 SVGpartials/nav-item.html/partials/nav.html折叠箭头、返回箭头、目录图标全部改为内联 SVG导航区增加aria-labelpartials/search.html组件标记改为search-query/search-reset/search-result放大镜、返回、关闭图标改为内联 SVGpartials/social.html移除 font-awesome 字体社交图标改为内联 SVGpartials/tabs.html/tabs-item.html增加aria-label首页判断兼容nav_item.url index.htmlpartials/toc.html/toc-item.html增加aria-label移除源文件与 Disqus 的目录锚点partials/language.htmlt()宏简化为lang.t(key) | default(fallback.t(key))移除对extra.search的读取从 3.x 升级到 4.x中文系统布局修复与rem基准变化Material for MkDocs 4 修复了中文系统下的错误布局。修复包含一项强制性变更基础字号从10px改为20px因此所有rem值都需要更新。主题内部把px到rem的计算封装为 SASS 代码库中的新函数px2rem。如果你使用基于rem值的自定义 CSS请注意这些值现在必须除以 21.0rem不再对应10px而是20px。该问题在 #911 中被发现并修复4.x 的mkdocs.yml与*.html文件均无强制变更。升级检查清单将上述各版本变更汇总为一份可操作的清单确认版本pip show mkdocs-material锁定当前起点逐版本比对mkdocs.yml按 4.x → 5.x → 6.x → 7.x → 8.x → 9.x 顺序检查功能标志前缀、插件化迁移搜索、分析、语言代码、版本化配置与扩展配置tabbed、superfences检查自定义模板若通过 theme extension 覆盖了 block 或 template重点比对 src/templates/base.html、src/templates/partials/content.html、src/templates/partials/actions.html 等文件与旧结构的差异排查内置插件失效若 search 或 tags 静默失效在覆盖模板中搜索in config.plugins并加上material/命名空间验证自定义 CSS检查是否依赖旧的rem基准10px或已改名的字体 CSS 变量--md-text-font-family等构建验证运行mkdocs build或mkdocs serve确认页面渲染、搜索、导航与页脚功能正常。升级本身是渐进式的只要你的配置遵循只调整已定义项的原则多数场景只需修改mkdocs.yml中的少量键名即可平滑完成迁移。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Material for MkDocs 升级完全指南：从 3.x 到 9.x 的配置迁移与模板兼容
Material for MkDocs 升级完全指南从 3.x 到 9.x 的配置迁移与模板兼容【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material本篇指南以 docs/upgrade.md 为骨架系统梳理 Material for MkDocs 从 3.x 一路升级到 9.x 过程中所有需要关注的破坏性变更mkdocs.yml中的配置项重命名与结构调整、内置插件的行为变化、主题模板*.html的结构演进以及自定义 CSS 的兼容性问题。读完本文你将掌握当前版本中各项功能代码复制按钮、页面编辑/查看按钮、页脚导航、站点分析、搜索、内容标签等的正确配置方式并能在升级后快速定位因自定义覆盖overrides导致的功能失效问题。升级基础安装与版本确认升级到最新版本只需一行命令使用--force-reinstall确保覆盖本地可能存在的旧版本文件pip install --upgrade --force-reinstall mkdocs-material查看当前已安装的版本pip show mkdocs-material在执行任何大版本迁移之前建议先确认当前版本再对照下文相应小节逐项检查mkdocs.yml与自定义模板。如果你从未定义过某个配置项则对应小节可以安全跳过——文档明确说明只有你定义过的键才需要调整。从 8.x 升级到 9.x全新搜索与功能标志化9.x 是一次重要的大版本发布核心变化是引入了全新的搜索实现更快、支持富预览rich previews、高级分词advanced tokenization与更好的高亮效果。该实现此前长期仅在 Insiders 版本中提供随着资金目标达成进入社区版。新搜索的前端运行时位于 src/templates/assets/javascripts插件侧的配置解析与索引构建逻辑可在 src/plugins/search/plugin.py 中查看。content.code.copy复制按钮改为按需启用从 9.x 开始代码块的复制到剪贴板按钮默认不再显示且支持按块开启或关闭。若希望所有代码块都显示复制按钮在mkdocs.yml中加入theme: features: - content.code.copycontent.action.*编辑与查看按钮显式开启页面右上角紧邻编辑此页按钮的查看源码按钮现在两者都必须显式启用theme: features: - content.action.edit - content.action.view在源码层面这两个功能由 src/templates/partials/actions.html 实现模板先判断page.edit_url是否存在再分别检查content.action.edit与content.action.view是否出现在features中查看按钮还会自动将 URL 中的blob/edit段替换为raw以指向原始文件。当前仓库自身的 mkdocs.yml 即同时启用了这两个标志。navigation.footer页脚前后翻页改为可选页脚中的上一页 / 下一页导航按钮现在是可选项。若希望保留加入theme: features: - navigation.footertheme.language韩语与挪威语代码重命名两个不符合 ISO 标准的语言代码被重命名为标准形式kr→ko韩语no→nb挪威语在仓库中可以看到 src/templates/partials/languages 目录下存在ko.html与nb.html而不再有kr与no文件。feedback.ratings占位符必须使用命名形式旧的匿名占位符已废弃数月被移除。反馈链接必须改用新的命名占位符{title}与{url}https://github.com/.../issues/new/?title[Feedback]{title}-{url}在 src/templates/partials/feedback.html 中可以看到运行时会对rating.note执行replace({url}, url)与replace({title}, title)title取页面元数据标题或页面标题并做 URL 编码。模板变更与内置插件命名空间9.x 对主题模板做了一轮重构。若你通过主题扩展theme extension自定义过模板务必把最新改动同步进去。如果升级后发现某个内置插件搜索或标签没有任何报错却不再工作极有可能与自定义覆盖overrides有关MkDocs 1.4.1 及以上版本允许主题为内置插件添加命名空间Material for MkDocs 9 现在对内置插件统一使用material/前缀以允许作者使用与内置插件同名的第三方插件。具体做法在覆盖模板中搜索in config.plugins将涉及的插件名加上material/前缀。受影响的 partial 包括src/templates/partials/content.htmlsrc/templates/partials/header.html从源码可以印证这一命名空间机制例如 src/plugins/blog/plugin.py 中生成文件标记为material/blogsrc/plugins/blog/structure/init.py 通过config.plugins.get(material/meta)获取元数据插件src/plugins/projects/structure/init.py 中同时接受projects与material/projects两种写法src/plugins/tags/config.py 则把listings_directive的默认值设为material/tags。搜索覆盖内容时可将material/前缀视为插件名的一部分进行匹配。从 7.x 升级到 8.x注解、锚点与模板重构新增能力一览新增代码注解code annotations支持新增锚点追踪anchor tracking支持新增版本警告version warning支持新增独立的copyrightpartial便于覆盖移除废弃的内容标签content tabs旧实现移除废弃的seealso提示admonition类型移除废弃的site_keywords设置MkDocs 不支持移除废弃的预构建搜索索引支持移除废弃的 Web App Manifest改用自定义方案移除extracopyright变量改用新的copyrightpartial移除 Disqus 集成改用自定义方案简单选择器列表切换为:is()选择器autoprefixer 从last 4 years调整为last 2 yearsCSS 整体向现代标准看齐字体相关 CSS 变量语义改进通过重构 partials 提升可扩展性改进打印时details元素的处理改进脚注的键盘导航修复 #3214搜索高亮在站点为空时破坏页面pymdownx.tabbed必须启用新样式旧版 Tabbed 扩展的样式支持被移除必须切换到新的、在移动端视口表现更好的替代实现 8.x yaml markdown_extensions: - pymdownx.tabbed: alternate_style: true 7.x yaml markdown_extensions: - pymdownx.tabbed Tabbed 扩展的完整用法见 docs/setup/extensions/python-markdown-extensions.md。pymdownx.superfences移除*-experimental后缀自定义围栏custom fence类属性中的*-experimental后缀必须移除。该配置用于把代码块交给 Mermaid.js 渲染为图表详见 docs/reference/diagrams.md 8.x yaml markdown_extensions: - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format 7.x yaml markdown_extensions: - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid-experimental format: !!python/name:pymdownx.superfences.fence_code_format SuperFences 扩展的完整说明见 docs/setup/extensions/python-markdown-extensions.md。当前仓库 mkdocs.yml 使用的即是去掉后缀的class: mermaid写法。google_analytics迁移到extra.analyticsgoogle_analytics自 MkDocs 1.2.0 起被废弃因为基于 JavaScript 的分析集成实现属于主题职责。需要按如下方式迁移 8.x yaml extra: analytics: provider: google property: UA-XXXXXXXX-X 7.x yaml google_analytics: - UA-XXXXXXXX-X - auto 当前仓库的 mkdocs.yml 即采用extra.analytics.provider: google的新结构分析模板位于 src/templates/partials/integrations/analytics。模板变更8.x 对模板做了一轮面向未来的重构。如果你通过主题扩展覆盖过 block 或 template需要同步新结构若覆盖的是block检查 src/templates/base.html 是否有变化若覆盖的是template检查对应的*.html文件是否有变化base.html的核心变更包括移除keywords相关 meta 标签page.meta.keywords/config.site_keywords均被废弃字体 CSS 变量由--md-text-font-family/--md-code-font-family简化为--md-text-font/--md-code-font移除 Web App Manifest 链接块config.extra.manifestpartials/javascripts/base.html从body底部移动到head中公告栏announce类名由md-banner md-announce收敛为md-banner新增版本警告区块当config.extra.version存在时渲染data-md-componentoutdated横幅并引入 src/templates/partials/javascripts/outdated.html页面主体内容整合为单一{% include partials/content.html %}对应 src/templates/partials/content.html编辑按钮、h1 兜底、正文、源文件信息统一由该 partial 承载移除disqusblockpartials/footer.html的变更原内联的版权信息区块抽取为独立的 src/templates/partials/copyright.html同时渲染config.copyright高亮与Made with Material for MkDocs徽标除非config.extra.generator falseextracopyright变量被移除社交链接区块改为{% if config.extra.social %}条件包裹partials/social.html的变更外层md-footer-social重命名为md-social链接图标从字体图标改为内联 SVG{% include .icons/ ~ social.icon ~ .svg %}title由链接域名推导从 6.x 升级到 7.x响应式架构重写新增能力一览新增多版本部署支持新增语言选择器集成新增内联 admonition 渲染支持底层响应式架构重写弃用 Webpack改为响应式构建策略减少 480 个依赖修复内容标签切换后代码块键盘导航失效的问题extra.version.method→extra.version.provider版本化方法配置被重命名为extra.version.provider以便未来支持不同的版本化策略 7.x yaml extra: version: provider: mike 6.x yaml extra: version: method: mike 版本化功能的使用说明见 docs/setup/setting-up-versioning.md。模板变更base.html的核心变更字体引入方式由body,input{font-family:...}全局规则改为在:root上定义--md-text-font-family/--md-code-font-family变量侧边栏组件重命名主侧边栏data-md-componentnavigation、次侧边栏data-md-componenttoc统一为data-md-componentsidebar并以data-md-type区分导航/目录内容区新增data-md-componentcontent新增md-dialog对话框组件容器脚本引导方式重构新增configblock把base、features、translations、searchworker 路径、version聚合为app字典通过__configJSON 注入页面__lang内联脚本移除JavaScript bundle 由 vendor bundle 两个文件收敛为单个bundle.926459b3.min.js以当前构建产物为准partials/footer.htmlmd-footer-nav前缀类名全部重命名为md-footer__inner/md-footer__link/md-footer__button/md-footer__title/md-footer__direction。partials/header.htmlmd-header-nav前缀类名全部改为md-header__inner/md-header__button/md-header__title/md-header__topic新增md-header__options区块当配置了config.extra.alternate时渲染语言选择器md-select其图标默认取material/translatepartials/source.html仓库链接元素增加data-md-componentsource标记。partials/toc.html目录列表增加data-md-componenttoc。从 5.x 升级到 6.x功能标志统一前缀新增能力一览改进搜索结果的观感与输入时的稳定性改进搜索结果分组页面 标题改进搜索结果相关性与评分搜索结果中显示缺失的查询词供应商包体积减少 25%84kb → 67kb减小 Docker 镜像体积以提升 CI 构建性能移除 hero partial改为自定义实现移除废弃的 front matter 特性theme.features功能标志加组件前缀所有可从mkdocs.yml启用的功能标志如 tabs、instant loading现在都以所属组件或功能命名例如navigation.* 6.x yaml theme: features: - navigation.tabs - navigation.instant 5.x yaml theme: features: - tabs - instant 导航功能标志的完整清单见 docs/setup/setting-up-navigation.md其中 navigation.tabs 与 instant loading 是本次重命名的直接对象。模板变更base.html的核心变更顶部的palette/font变量定义移入各自使用处改为在块内{% set %}延迟求值移除基于page.meta.redirect的 JS 重定向与meta refresh逻辑改为仅保留 canonical 标签调色板相关逻辑重构palette.css的引入条件改为config.theme.palette是否存在theme-colormeta 标签移入该条件块内新增基于prefers-color-scheme的scheme: preference实验性脚本hero 区块移除自动渲染逻辑{% block hero %}{% endblock %}变为空占位同时删除 src/templates/partials/hero.html 与source-linkpartialtabs 判断由tabs in config.theme.features改为navigation.tabs in config.theme.features新增搜索翻译键search.result.more.one、search.result.more.other、search.result.term.missing新增跳过导航skip link与公告栏announce组件md-overlay移除data-md-component标记从 4.x 升级到 5.x响应式架构与图标体系重构新增能力一览响应式架构——在控制台执行#!js app.dialog$.next(Hi!)即可体验Instant loading——让 Material 表现得像单页应用SPA通过 CSS 变量改进定制能力见 docs/setup/changing-the-colors.md改进 CSS 健壮性例如自定义头部时侧边栏正确锁定改进图标集成与配置主题内置超过 5000 个图标见 docs/reference/icons-emojis.md任何图标都可用于 logo、仓库与社交链接搜索 UI 不再卡顿迁移至 Web Worker使用 instant loading 时搜索索引只构建一次改进可扩展的键盘处理支持预构建搜索索引见 docs/plugins/search.md支持显示 GitLab 仓库的 star 与 fork 数侧边栏与搜索结果支持滚动吸附scroll snapping因放弃 Internet Explorer 支持而减小 HTML 与 CSS 体积部分 UI 元素admonition、表格等观感微调theme.feature→theme.features布尔键改为标志列表可选功能如 tabs、instant loading现在实现为标志flag通过mkdocs.yml的theme.features列表启用 5.x yaml theme: features: - tabs - instant 4.x yaml theme: feature: tabs: true theme.logo.icon→theme.icon.logoLogo 图标配置集中到theme.icon.logo下可选用主题内置的任何图标 5.x yaml theme: icon: logo: material/cloud 4.x yaml theme: logo: icon: cloud extra.repo_icon→theme.icon.repo仓库图标配置集中到theme.icon.repo下 5.x yaml theme: icon: repo: fontawesome/brands/gitlab 4.x yaml extra: repo_icon: gitlab extra.search.*→ 搜索插件配置搜索现在作为插件选项进行配置见 docs/plugins/search.md。搜索语言必须写成字符串数组tokenizer重命名为separator 5.x yaml plugins: - search: separator: [\s\-\.] lang: - en - de - ru 4.x yaml extra: search: language: en, de, ru tokenizer: [\s\-\.] 对应地搜索插件的配置结构可以在 src/plugins/search/config.py 中看到支持lang、separator、pipeline、fields以及中文分词相关的jieba_dict/jieba_dict_user其中pipeline的可选值为stemmer、stopWordFilter、trimmer。字段权重在 src/plugins/search/plugin.py 中合并默认值标题boost: 1e3、正文1e0、标签1e6。extra.social.type→extra.social.icon社交链接位置不变但type键重命名为icon以匹配新的图标指定方式 5.x yaml extra: social: - icon: fontawesome/brands/github-alt link: https://github.com/squidfunk 4.x yaml extra: social: - type: github link: https://github.com/squidfunk 模板变更base.html的核心变更移除theme.feature布尔配置读取与lang:前缀的 meta 标签search.language、search.tokenizer等样式表文件名从application.*.css/application-palette.*.css改为main.*.min.css/palette.*.min.css移除modernizr脚本与material-icons.css字体链接移除内联的 SVG 符号md-svg__github/__gitlab/__bitbucket与md-overlay的组件标记新增跳过导航md-skip与公告栏md-announce组件direction改为config.theme.direction | default(lang.t(direction))编辑按钮由内联字符实体改为内联 SVGmaterial/pencil.svg源码日期渲染抽取为 src/templates/partials/source-date.html脚本区重构vendor bundle 双文件__langJSON 注入翻译initialize()引导改为接收base、features、search.worker参数其他 partial 变更partials/footer.html类名规范化并增加aria-label箭头图标改为内联 SVGmaterial/arrow-left.svg/material/arrow-right.svgpartials/header.htmllogo 区改为引入 src/templates/partials/logo.html优先config.theme.logo图片否则回退到config.theme.icon.logo默认material/library菜单/搜索图标改为内联 SVGpartials/nav-item.html/partials/nav.html折叠箭头、返回箭头、目录图标全部改为内联 SVG导航区增加aria-labelpartials/search.html组件标记改为search-query/search-reset/search-result放大镜、返回、关闭图标改为内联 SVGpartials/social.html移除 font-awesome 字体社交图标改为内联 SVGpartials/tabs.html/tabs-item.html增加aria-label首页判断兼容nav_item.url index.htmlpartials/toc.html/toc-item.html增加aria-label移除源文件与 Disqus 的目录锚点partials/language.htmlt()宏简化为lang.t(key) | default(fallback.t(key))移除对extra.search的读取从 3.x 升级到 4.x中文系统布局修复与rem基准变化Material for MkDocs 4 修复了中文系统下的错误布局。修复包含一项强制性变更基础字号从10px改为20px因此所有rem值都需要更新。主题内部把px到rem的计算封装为 SASS 代码库中的新函数px2rem。如果你使用基于rem值的自定义 CSS请注意这些值现在必须除以 21.0rem不再对应10px而是20px。该问题在 #911 中被发现并修复4.x 的mkdocs.yml与*.html文件均无强制变更。升级检查清单将上述各版本变更汇总为一份可操作的清单确认版本pip show mkdocs-material锁定当前起点逐版本比对mkdocs.yml按 4.x → 5.x → 6.x → 7.x → 8.x → 9.x 顺序检查功能标志前缀、插件化迁移搜索、分析、语言代码、版本化配置与扩展配置tabbed、superfences检查自定义模板若通过 theme extension 覆盖了 block 或 template重点比对 src/templates/base.html、src/templates/partials/content.html、src/templates/partials/actions.html 等文件与旧结构的差异排查内置插件失效若 search 或 tags 静默失效在覆盖模板中搜索in config.plugins并加上material/命名空间验证自定义 CSS检查是否依赖旧的rem基准10px或已改名的字体 CSS 变量--md-text-font-family等构建验证运行mkdocs build或mkdocs serve确认页面渲染、搜索、导航与页脚功能正常。升级本身是渐进式的只要你的配置遵循只调整已定义项的原则多数场景只需修改mkdocs.yml中的少量键名即可平滑完成迁移。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 降到 O(1))
