如何升级

使用以下命令升级到最新版本：

pip install --upgrade --force-reinstall mkdocs-material

使用以下命令查看当前安装的版本：

pip show mkdocs-material

从 8.x 升级到 9.x

这个主要版本包括一个全新的搜索实现，它更快，允许丰富的预览，高级的分词和更好的高亮显示。它已经作为 Insiders 的一部分超过一年，现在资金目标已经达到，它将进入社区版。

对mkdocs.yml的更改

content.code.copy

复制到剪贴板的按钮现在需要选择启用，并且可以针对每个块启用或禁用。如果你希望为所有代码块启用它们，将以下行添加到mkdocs.yml：

theme:
  features:
    - content.code.copy

content.action.*

"查看源代码"按钮可以显示在"编辑此页面"按钮旁边，这两个按钮现在都必须明确启用。将以下行添加到mkdocs.yml：

theme:
  features:
    - content.action.edit
    - content.action.view

navigation.footer

页脚中的前一个和下一个按钮现在需要选择启用。如果你希望为你的文档保留它们，将以下行添加到mkdocs.yml：

theme:
  features:
    - navigation.footer

theme.language

韩语和挪威语的语言代码已经被重命名，因为它们是非标准的：

• kr 更改为 ko
• no 更改为 nb

feedback.ratings

旧的、无名的占位符已被移除（在几个月前已被弃用）。确保切换到新的命名占位符{title}和{url}：

https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}

对*.html文件的更改

模板经历了一系列的更改。如果你已经定制了 Material for MkDocs 的主题扩展，请确保将最新的更改合并到你的模板中。一个好的起点是检查差异。

升级后内置插件不工作？

如果内置插件（搜索或标签）在没有任何明显错误或原因的情况下不再工作，那么它很可能与自定义覆盖有关。MkDocs 1.4.1及以上版本允许主题为内置插件设置命名空间，这是Material for MkDocs 9现在做的，以便作者使用与内置插件同名的第三方插件。在你的覆盖中搜索"in config.plugins"并添加material/命名空间。受影响的部分包括：

• content.html
• header.html

从 7.x 升级到 8.x

新增了什么？

• 增加了对代码注释的支持
• 增加了对锚点跟踪的支持
• 增加了对版本警告的支持
• 增加了copyright部分以便于覆盖
• 删除了已弃用的内容标签页的旧实现
• 删除了已弃用的seealso警告类型
• 删除了已弃用的site_keywords设置（MkDocs 不支持）
• 删除了已弃用的预构建搜索索引支持
• 删除了已弃用的 web 应用程序清单 - 使用定制
• 删除了extracopyright变量 - 使用新的copyright部分
• 删除了 Disqus 集成 - 使用定制
• 切换到:is()选择器以简化选择器列表
• 从last 4 years切换到last 2 years的 autoprefixer
• 改进了 CSS 以符合现代标准
• 改进了字体的 CSS 变量语义
• 通过重构部分来改进扩展性
• 改进了打印时details的处理
• 改进了脚注的键盘导航
• 修复了#3214：搜索高亮在为空时破坏站点

对mkdocs.yml的更改

pymdownx.tabbed

支持Tabbed扩展的旧式样式已被弃用，转而支持新的、有在移动视口上更好的行为的替代实现：

8.x

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

7.x

markdown_extensions:
  - pymdownx.tabbed

pymdownx.superfences

必须从自定义围栏类属性中删除*-experimental后缀，该属性用于目标代码块以使用Mermaid.js渲染为图表：

8.x

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

7.x

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid-experimental
          format: !!python/name:pymdownx.superfences.fence_code_format

google_analytics

这个选项在[MkDocs 1.2.0 中被弃用]，因为 JavaScript-based analytics integration 是一个主题的责任。以下行必须被更改：

8.x

extra:
  analytics:
    provider: google
    property: UA-XXXXXXXX-X

7.x

google_analytics:
  - UA-XXXXXXXX-X
  - auto

对*.html文件的更改

模板经历了一系列的更改以使它们具有未来的兼容性。如果你使用了主题扩展来覆盖一个块或模板，确保它匹配新的结构：

• 如果你覆盖了一个块，检查base.html以寻找可能的更改
• 如果你覆盖了一个模板，检查相应的*.html文件以寻找可能的更改

从 6.x 升级到 7.x

新增了什么？

• 增加了部署多个版本的支持
• 增加了集成语言选择器的支持
• 增加了将警告渲染为内联块的支持
• 对底层反应式架构进行了重写
• 移除了 Webpack，改为反应式构建策略（减少了 480 个依赖项）
• 修复了内容标签切换后代码块的键盘导航问题

对mkdocs.yml的更改

extra.version.method

版本方法的配置已经被重命名为extra.version.provider，以便于将来支持不同的版本策略：

7.x

extra:
  version:
    provider: mike

6.x

extra:
  version:
    method: mike

对*.html文件的更改

模板经历了一系列的更改以使它们具有未来的兼容性。如果你使用了主题扩展来覆盖一个块或模板，确保它匹配新的结构：

• 如果你覆盖了一个块，检查base.html以寻找可能的更改
• 如果你覆盖了一个模板，检查相应的*.html文件以寻找可能的更改

从 5.x 升级到 6.x

有什么新功能？

• 改进了搜索结果的外观和感觉
• 在输入时改进了搜索结果的稳定性
• 改进了搜索结果的分组（页面+标题）
• 改进了搜索结果的相关性和评分
• 在搜索结果中添加了显示缺失查询词的功能
• 将供应商捆绑包的大小减小了 25％（84kb → 67kb）
• 减小了 Docker 镜像的大小，以提高 CI 构建性能
• 删除了英雄部分，采用了自定义实现
• 删除了已弃用的前置内容功能

mkdocs.yml的更改

以下是需要对mkdocs.yml进行的更改列表。请注意，只有在您定义了值的情况下才需要进行调整，因此如果您的配置中不包含该键，则可以跳过它。

theme.features

现在，可以从mkdocs.yml中设置的所有功能标志，如tabs和instant loading，都以组件或函数的名称为前缀，例如navigation.*：

6.x

theme:
  features:
    - navigation.tabs
    - navigation.instant

5.x

theme:
  features:
    - tabs
    - instant

*.html文件的更改

模板已经经历了一系列的更改，以使其具备未来的兼容性。如果您使用了主题扩展来覆盖块或模板，请确保它与新的结构匹配：

• 如果您覆盖了块，请检查base.html以查看可能的更改
• 如果您覆盖了模板，请检查相应的*.html文件以查看可能的更改

从 4.x 升级到 5.x

有什么新功能？

• 响应式架构 - 在控制台中尝试 app.dialog$.next("Hi!")
• [即时加载] - 使 Material 行为类似单页应用程序
• 使用[CSS 变量]进行改进的 CSS 自定义 - 设置您品牌的颜色
• 改进的 CSS 弹性，例如为自定义标题提供适当的侧边栏锁定
• 改进的图标集成和配置 - 现在包括超过 5000 个图标
• 可以使用任何图标作为标志、存储库和社交链接
• 搜索界面不再冻结（已移至 Web Worker）
• 使用即时加载时仅构建一次搜索索引
• 改进的可扩展键盘处理
• 支持预构建搜索索引
• 支持显示 GitLab 存储库的星星和分叉
• 支持侧边栏和搜索结果的滚动捕捉
• 由于停用了对 Internet Explorer 的支持，减小了 HTML 和 CSS 的占用空间
• 对某些 UI 元素进行轻微改进（警告、表格等）

mkdocs.yml的更改

以下是需要对mkdocs.yml进行的更改列表。请注意，只有在您定义了值的情况下才需要进行调整，因此如果您的配置中不包含该键，则可以跳过它。

theme.feature

现在，可选功能（如tabs和instant loading）被实现为标志，并且可以通过在mkdocs.yml的theme.features下列出它们来启用：

5.x

theme:
  features:
    - tabs
    - instant

4.x

theme:
  feature:
    tabs: true

theme.logo.icon

标志图标配置已集中在theme.icon.logo下，并且现在可以设置为主题捆绑的图标之一：

5.x

theme:
  icon:
    logo: material/cloud

4.x

theme:
  logo:
    icon: cloud

extra.repo_icon

存储库图标配置已集中在theme.icon.repo下，并且现在可以设置为主题捆绑的图标之一：

5.x

theme:
  icon:
    repo: fontawesome/brands/gitlab

4.x

extra:
  repo_icon: gitlab

extra.search.*

现在，搜索作为插件选项的一部分进行配置。请注意，搜索语言现在必须作为字符串数组列出，并且tokenizer已更名为separator：

5.x

plugins:
  - search:
      separator: '[\s\-\.]+'
      lang:
        - en
        - de
        - ru

4.x

extra:
  search:
    language: en, de, ru
    tokenizer: '[\s\-\.]+'

extra.social.*

社交链接仍位于相同位置，但type键已重命名为icon，以匹配指定要使用的新方式：

5.x

extra:
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/squidfunk

4.x

extra:
  social:
    - type: github
      link: https://github.com/squidfunk

*.html文件的更改

模板已经经历了一系列的更改，以使其具备未来的兼容性。如果您使用了主题扩展来覆盖块或模板，请确保它与新的结构匹配：

• 如果您覆盖了块，请检查base.html以查看可能的更改
• 如果您覆盖了模板，请检查相应的*.html文件以查看可能的更改

从 3.x 升级到 4.x

有什么新功能？

Material for MkDocs 4 修复了在中文系统上的布局错误。修复包括将基本字体大小从10px更改为20px，这意味着所有的rem值都需要更新。在主题中，px到rem的计算现在封装在一个名为px2rem的新函数中，该函数是 SASS 代码库的一部分。

如果您使用基于rem值的自定义 CSS 的 Material for MkDocs，请注意这些值现在必须除以 2。现在，1.0rem不再对应10px，而是对应20px。要了解更多有关问题和影响的信息，请参考问题#911，其中发现并修复了该问题。

mkdocs.yml的更改

无。

*.html文件的更改

无。