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.copy

content.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.footer

theme.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.html
• src/templates/partials/header.html

从源码可以印证这一命名空间机制：例如 src/plugins/blog/plugin.py 中生成文件标记为"material/blog"，src/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 years
• CSS 整体向现代标准看齐，字体相关 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.analytics

google_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.manifest）
• partials/javascripts/base.html从<body>底部移动到<head>中
• 公告栏（announce）类名由md-banner md-announce收敛为md-banner
• 新增版本警告区块：当config.extra.version存在时渲染data-md-component="outdated"横幅并引入 src/templates/partials/javascripts/outdated.html
• 页面主体内容整合为单一{% include "partials/content.html" %}（对应 src/templates/partials/content.html），编辑按钮、h1 兜底、正文、源文件信息统一由该 partial 承载
• 移除disqusblock

partials/footer.html的变更：

• 原内联的版权信息区块抽取为独立的 src/templates/partials/copyright.html，同时渲染config.copyright高亮与"Made with Material for MkDocs"徽标（除非config.extra.generator == false）
• extracopyright变量被移除
• 社交链接区块改为{% 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-component="navigation"、次侧边栏data-md-component="toc"统一为data-md-component="sidebar"，并以data-md-type区分导航/目录
• 内容区新增data-md-component="content"
• 新增md-dialog对话框组件容器
• 脚本引导方式重构：新增configblock，把base、features、translations、searchworker 路径、version聚合为app字典，通过__configJSON 注入页面；__lang内联脚本移除
• JavaScript bundle 由 vendor + bundle 两个文件收敛为单个bundle.926459b3.min.js（以当前构建产物为准）

partials/footer.html：md-footer-nav前缀类名全部重命名为md-footer__inner/md-footer__link/md-footer__button/md-footer__title/md-footer__direction。

partials/header.html：

• md-header-nav前缀类名全部改为md-header__inner/md-header__button/md-header__title/md-header__topic
• 新增md-header__options区块：当配置了config.extra.alternate时渲染语言选择器（md-select），其图标默认取material/translate

partials/source.html：仓库链接元素增加data-md-component="source"标记。partials/toc.html：目录列表增加data-md-component="toc"。

从 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-linkpartial
• tabs 判断由"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.logo

Logo 图标配置集中到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'))
• 编辑按钮由内联字符实体改为内联 SVG（material/pencil.svg）
• 源码日期渲染抽取为 src/templates/partials/source-date.html
• 脚本区重构：vendor + bundle 双文件，__langJSON 注入翻译，initialize()引导改为接收base、features、search.worker参数

其他 partial 变更：

• partials/footer.html：类名规范化并增加aria-label，箭头图标改为内联 SVG（material/arrow-left.svg/material/arrow-right.svg）
• partials/header.html：logo 区改为引入 src/templates/partials/logo.html（优先config.theme.logo图片，否则回退到config.theme.icon.logo，默认material/library），菜单/搜索图标改为内联 SVG
• partials/nav-item.html/partials/nav.html：折叠箭头、返回箭头、目录图标全部改为内联 SVG，导航区增加aria-label
• partials/search.html：组件标记改为search-query/search-reset/search-result，放大镜、返回、关闭图标改为内联 SVG
• partials/social.html：移除 font-awesome 字体，社交图标改为内联 SVG
• partials/tabs.html/tabs-item.html：增加aria-label，首页判断兼容nav_item.url == "index.html"
• partials/toc.html/toc-item.html：增加aria-label，移除源文件与 Disqus 的目录锚点
• partials/language.html：t()宏简化为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，请注意这些值现在必须除以 2：1.0rem不再对应10px，而是20px。该问题在 #911 中被发现并修复，4.x 的mkdocs.yml与*.html文件均无强制变更。

升级检查清单

将上述各版本变更汇总为一份可操作的清单：

1. 确认版本：pip show mkdocs-material，锁定当前起点；
2. 逐版本比对mkdocs.yml：按 4.x → 5.x → 6.x → 7.x → 8.x → 9.x 顺序检查功能标志前缀、插件化迁移（搜索、分析）、语言代码、版本化配置与扩展配置（tabbed、superfences）；
3. 检查自定义模板：若通过 theme extension 覆盖了 block 或 template，重点比对 src/templates/base.html、src/templates/partials/content.html、src/templates/partials/actions.html 等文件与旧结构的差异；
4. 排查内置插件失效：若 search 或 tags 静默失效，在覆盖模板中搜索"in config.plugins"并加上material/命名空间；
5. 验证自定义 CSS：检查是否依赖旧的rem基准（10px）或已改名的字体 CSS 变量（--md-text-font-family等）；
6. 构建验证：运行mkdocs build或mkdocs serve，确认页面渲染、搜索、导航与页脚功能正常。

升级本身是渐进式的：只要你的配置遵循"只调整已定义项"的原则，多数场景只需修改mkdocs.yml中的少量键名即可平滑完成迁移。

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