如何升级¶

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

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/ 命名空间。受影响的部分：

从 7.x 升级到 8.x¶

新增功能¶

添加对代码注释的支持
添加对锚点跟踪的支持
添加对版本警告的支持
添加 copyright 部分以便于覆盖
移除已弃用的内容标签遗留实现
移除已弃用的 seealso 劝告类型
移除已弃用的 site_keywords 设置（MkDocs 不支持）
移除已弃用的预构建搜索索引支持
移除已弃用的 Web 应用程序清单 – 使用自定义
移除 extracopyright 变量 – 使用新的 copyright 部分
移除 Disqus 集成 – 使用自定义
将自动前缀器从 last 4 years 切换到 last 2 years
改进 CSS 以符合现代标准
改进字体的 CSS 变量语义
通过重构部分提高可扩展性
改进打印时对 details 的处理
改进脚注的键盘导航
修复 #3214：当搜索高亮为空时，搜索会破坏网站

对 `mkdocs.yml` 的更改¶

`pymdownx.tabbed`¶

对 Tabbed 扩展的遗留样式的支持已被放弃，转而支持新的替代实现，该实现在移动视口上表现更好：

8.x7.x

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

markdown_extensions:
  - pymdownx.tabbed

`pymdownx.superfences`¶

必须从 custom fence 类属性中移除 *-experimental 后缀，该属性用于将代码块呈现为 diagrams，使用 Mermaid.js：

8.x7.x

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

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 的分析集成的实现是主题的责任。以下行必须更改：

8.x7.x

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

google_analytics:
  - UA-XXXXXXXX-X
  - auto

对 `*.html` 文件的更改¶

模板经历了一系列更改，以使其未来可用。如果您使用主题扩展覆盖了某个块或模板，请确保它符合新结构：

如果您覆盖了 block，请检查 base.html 以查找潜在更改
如果您覆盖了 template，请检查相应的 *.html 文件以查找潜在更改

base.html partials/copyright.html partials/footer.html partials/social.html

@@ -13,11 +13,6 @@
       {% elif config.site_description %}
         <meta name="description" content="{{ config.site_description }}">
       {% endif %}
-      {% if page and page.meta and page.meta.keywords %}
-        <meta name="keywords" content="{{ page.meta.keywords }}">
-      {% elif config.site_keywords %}
-        <meta name="keywords" content="{{ config.site_keywords }}">
-      {% endif %}
       {% if page and page.meta and page.meta.author %}
         <meta name="author" content="{{ page.meta.author }}">
       {% elif config.site_author %}
@@ -61,15 +56,13 @@
             font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
             font.code | replace(' ', '+')
           }}&display=fallback">
-        <style>:root{--md-text-font-family:"{{ font.text }}";--md-code-font-family:"{{ font.code }}"}</style>
+        <style>:root{--md-text-font:"{{ font.text }}";--md-code-font:"{{ font.code }}"}</style>
       {% endif %}
     {% endblock %}
-    {% if config.extra.manifest %}
-      <link rel="manifest" href="{{ config.extra.manifest | url }}" crossorigin="use-credentials">
-    {% endif %}
     {% for path in config["extra_css"] %}
       <link rel="stylesheet" href="{{ path | url }}">
     {% endfor %}
+    {% include "partials/javascripts/base.html" %}
     {% block analytics %}
       {% include "partials/integrations/analytics.html" %}
     {% endblock %}
@@ -89,7 +82,6 @@
     <body dir="{{ direction }}">
   {% endif %}
     {% set features = config.theme.features or [] %}
-    {% include "partials/javascripts/base.html" %}
     {% if not config.theme.palette is mapping %}
       {% include "partials/javascripts/palette.html" %}
     {% endif %}
@@ -106,13 +98,25 @@
     </div>
     <div data-md-component="announce">
       {% if self.announce() %}
-        <aside class="md-banner md-announce">
-          <div class="md-banner__inner md-announce__inner md-grid md-typeset">
+        <aside class="md-banner">
+          <div class="md-banner__inner md-grid md-typeset">
             {% block announce %}{% endblock %}
           </div>
         </aside>
       {% endif %}
     </div>
+    {% if config.extra.version %}
+      <div data-md-component="outdated" hidden>
+        <aside class="md-banner md-banner--warning">
+          {% if self.outdated() %}
+            <div class="md-banner__inner md-grid md-typeset">
+              {% block outdated %}{% endblock %}
+            </div>
+            {% include "partials/javascripts/outdated.html" %}
+          {% endif %}
+        </aside>
+      </div>
+    {% endif %}
     {% block header %}
       {% include "partials/header.html" %}
     {% endblock %}
@@ -156,25 +160,7 @@
           <div class="md-content" data-md-component="content">
             <article class="md-content__inner md-typeset">
               {% block content %}
-                {% if page.edit_url %}
-                  <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-content__button md-icon">
-                    {% include ".icons/material/pencil.svg" %}
-                  </a>
-                {% endif %}
-                {% if not "\x3ch1" in page.content %}
-                  <h1>{{ page.title | d(config.site_name, true)}}</h1>
-                {% endif %}
-                {{ page.content }}
-                {% if page and page.meta %}
-                  {% if page.meta.git_revision_date_localized or
-                        page.meta.revision_date
-                  %}
-                    {% include "partials/source-file.html" %}
-                  {% endif %}
-                {% endif %}
-              {% endblock %}
-              {% block disqus %}
-                {% include "partials/integrations/disqus.html" %}
+                {% include "partials/content.html" %}
               {% endblock %}
             </article>
           </div>

@@ -38,13 +38,6 @@
         <meta name="description" content="{{ config.site_description }}" />
       {% endif %}

-      <!-- Page keywords -->
-      {% if page and page.meta and page.meta.keywords %}
-        <meta name="keywords" content="{{ page.meta.keywords }}" />
-      {% elif config.site_keywords %}
-        <meta name="keywords" content="{{ config.site_keywords }}" />
-      {% endif %}
-
       <!-- Page author -->
       {% if page and page.meta and page.meta.author %}
         <meta name="author" content="{{ page.meta.author }}" />
@@ -120,27 +113,21 @@
         />
         <style>
           :root {
-            --md-text-font-family: "{{ font.text }}";
-            --md-code-font-family: "{{ font.code }}";
+            --md-text-font: "{{ font.text }}";
+            --md-code-font: "{{ font.code }}";
           }
         </style>
       {% endif %}
     {% endblock %}

-    <!-- Progressive Web App Manifest -->
-    {% if config.extra.manifest %}
-      <link
-        rel="manifest"
-        href="{{ config.extra.manifest | url }}"
-        crossorigin="use-credentials"
-      />
-    {% endif %}
-
     <!-- Custom style sheets -->
     {% for path in config["extra_css"] %}
       <link rel="stylesheet" href="{{ path | url }}" />
     {% endfor %}

+    <!-- Helper functions for inline scripts -->
+    {% include "partials/javascripts/base.html" %}
+
     <!-- Analytics -->
     {% block analytics %}
       {% include "partials/integrations/analytics.html" %}
@@ -172,7 +159,6 @@

     <!-- Retrieve features from configuration -->
     {% set features = config.theme.features or [] %}
-    {% include "partials/javascripts/base.html" %}

     <!-- User preference: color palette -->
     {% if not config.theme.palette is mapping %}
@@ -214,14 +200,28 @@
     <!-- Announcement bar -->
     <div data-md-component="announce">
       {% if self.announce() %}
-        <aside class="md-banner md-announce">
-          <div class="md-banner__inner md-announce__inner md-grid md-typeset">
+        <aside class="md-banner">
+          <div class="md-banner__inner md-grid md-typeset">
             {% block announce %}{% endblock %}
           </div>
         </aside>
       {% endif %}
     </div>

+    <!-- Version warning -->
+    {% if config.extra.version %}
+      <div data-md-component="outdated" hidden>
+        <aside class="md-banner md-banner--warning">
+          {% if self.outdated() %}
+            <div class="md-banner__inner md-grid md-typeset">
+              {% block outdated %}{% endblock %}
+            </div>
+            {% include "partials/javascripts/outdated.html" %}
+          {% endif %}
+        </aside>
+      </div>
+    {% endif %}
+
     <!-- Header -->
     {% block header %}
       {% include "partials/header.html" %}
@@ -295,49 +295,11 @@
               {% block content %}
-
-                <!-- Edit button -->
-                {% if page.edit_url %}
-                  <a
-                    href="{{ page.edit_url }}"
-                    title="{{ lang.t('edit.link.title') }}"
-                    class="md-content__button md-icon"
-                  >
-                    {% include ".icons/material/pencil.svg" %}
-                  </a>
-                {% endif %}
-
-                <!--
-                  Hack: check whether the content contains a h1 headline. If it
-                  doesn't, the page title (or respectively site name) is used
-                  as the main headline.
-                -->
-                {% if not "\x3ch1" in page.content %}
-                  <h1>{{ page.title | d(config.site_name, true)}}</h1>
-                {% endif %}
-
-                <!-- Markdown content -->
-                {{ page.content }}
-
-                <!-- Last update of source file -->
-                {% if page and page.meta %}
-                  {% if page.meta.git_revision_date_localized or
-                        page.meta.revision_date
-                  %}
-                    {% include "partials/source-file.html" %}
-                  {% endif %}
-                {% endif %}
-              {% endblock %}
-
-              <!-- Disqus integration -->
-              {% block disqus %}
-                {% include "partials/integrations/disqus.html" %}
+                {% include "partials/content.html" %}
               {% endblock %}
             </article>
           </div>

@@ -0,0 +1,16 @@
+{#-
+  This file was automatically generated - do not edit
+-#}
+<div class="md-copyright">
+  {% if config.copyright %}
+    <div class="md-copyright__highlight">
+      {{ config.copyright }}
+    </div>
+  {% endif %}
+  {% if not config.extra.generator == false %}
+    Made with
+    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+      Material for MkDocs
+    </a>
+  {% endif %}
+</div>

@@ -41,21 +40,10 @@
   {% endif %}
   <div class="md-footer-meta md-typeset">
     <div class="md-footer-meta__inner md-grid">
-      <div class="md-footer-copyright">
-        {% if config.copyright %}
-          <div class="md-footer-copyright__highlight">
-            {{ config.copyright }}
-          </div>
-        {% endif %}
-        {% if not config.extra.generator == false %}
-          Made with
-          <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
-            Material for MkDocs
-          </a>
-        {% endif %}
-        {{ extracopyright }}
-      </div>
-      {% include "partials/social.html" %}
+      {% include "partials/copyright.html" %}
+      {% if config.extra.social %}
+        {% include "partials/social.html" %}
+      {% endif %}
     </div>
   </div>
 </footer>

@@ -4,17 +4,15 @@
-{% if config.extra.social %}
-  <div class="md-footer-social">
-    {% for social in config.extra.social %}
-      {% set title = social.name %}
-      {% if not title and "//" in social.link %}
-        {% set _,url = social.link.split("//") %}
-        {% set title = url.split("/")[0] %}
-      {% endif %}
-      <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ title | e }}" class="md-footer-social__link">
-        {% include ".icons/" ~ social.icon ~ ".svg" %}
-      </a>
-    {% endfor %}
-  </div>
-{% endif %}
+<div class="md-social">
+  {% for social in config.extra.social %}
+    {% set title = social.name %}
+    {% if not title and "//" in social.link %}
+      {% set _, url = social.link.split("//") %}
+      {% set title  = url.split("/")[0] %}
+    {% endif %}
+    <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ title | e }}" class="md-social__link">
+      {% include ".icons/" ~ social.icon ~ ".svg" %}
+    </a>
+  {% endfor %}
+</div>

从 6.x 升级到 7.x¶

新增功能¶

添加对部署多个版本的支持
添加对集成语言选择器的支持
添加对将劝告呈现为内联块的支持
重写底层响应式架构
移除 Webpack，转而使用响应式构建策略（–480 个依赖项）
修复内容标签切换后代码块的键盘导航

对 `mkdocs.yml` 的更改¶

`extra.version.method`¶

版本方法配置已重命名为 extra.version.provider，以便将来允许不同的版本策略：

7.x6.x

extra:
  version:
    provider: mike

extra:
  version:
    method: mike

对 `*.html` 文件的更改¶

模板经历了一系列更改，以使其未来可用。如果您使用主题扩展覆盖了某个块或模板，请确保它符合新结构：

如果您覆盖了 block，请检查 base.html 以查找潜在更改
如果您覆盖了 template，请检查相应的 *.html 文件以查找潜在更改

base.html partials/footer.html partials/header.html partials/source.html partials/toc.html

@@ -61,7 +61,7 @@
             font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
             font.code | replace(' ', '+')
           }}&display=fallback">
-        <style>body,input{font-family:"{{ font.text }}",-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"{{ font.code }}",SFMono-Regular,Consolas,Menlo,monospace}</style>
+        <style>:root{--md-text-font-family:"{{ font.text }}";--md-code-font-family:"{{ font.code }}"}</style>
       {% endif %}
     {% endblock %}
     {% if config.extra.manifest %}
@@ -131,7 +131,7 @@
               {% if page and page.meta and page.meta.hide %}
                 {% set hidden = "hidden" if "navigation" in page.meta.hide %}
               {% endif %}
-              <div class="md-sidebar md-sidebar--primary" data-md-component="navigation" {{ hidden }}>
+              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" {{ hidden }}>
                 <div class="md-sidebar__scrollwrap">
                   <div class="md-sidebar__inner">
                     {% include "partials/nav.html" %}
@@ -143,7 +143,7 @@
               {% if page and page.meta and page.meta.hide %}
                 {% set hidden = "hidden" if "toc" in page.meta.hide %}
               {% endif %}
-              <div class="md-sidebar md-sidebar--secondary" data-md-component="toc" {{ hidden }}>
+              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" {{ hidden }}>
                 <div class="md-sidebar__scrollwrap">
                   <div class="md-sidebar__inner">
                     {% include "partials/toc.html" %}
@@ -152,7 +152,7 @@
               </div>
             {% endif %}
           {% endblock %}
-          <div class="md-content">
+          <div class="md-content" data-md-component="content">
             <article class="md-content__inner md-typeset">
               {% block content %}
                 {% if page.edit_url %}
@@ -183,10 +183,18 @@
         {% include "partials/footer.html" %}
       {% endblock %}
     </div>
-    {% block scripts %}
-      <script src="{{ 'assets/javascripts/vendor.18f0862e.min.js' | url }}"></script>
-      <script src="{{ 'assets/javascripts/bundle.994580cf.min.js' | url }}"></script>
-      {%- set translations = {} -%}
+    <div class="md-dialog" data-md-component="dialog">
+      <div class="md-dialog__inner md-typeset"></div>
+    </div>
+    {% block config %}
+      {%- set app = {
+        "base": base_url,
+        "features": features,
+        "translations": {},
+        "search": "assets/javascripts/workers/search.217ffd95.min.js" | url,
+        "version": config.extra.version or None
+      } -%}
+      {%- set translations = app.translations -%}
       {%- for key in [
         "clipboard.copy",
         "clipboard.copied",
@@ -204,19 +212,12 @@
       ] -%}
         {%- set _ = translations.update({ key: lang.t(key) }) -%}
       {%- endfor -%}
-      <script id="__lang" type="application/json">
-        {{- translations | tojson -}}
-      </script>
-      {% block config %}{% endblock %}
-      <script>
-        app = initialize({
-          base: "{{ base_url }}",
-          features: {{ features or [] | tojson }},
-          search: Object.assign({
-            worker: "{{ 'assets/javascripts/worker/search.9c0e82ba.min.js' | url }}"
-          }, typeof search !== "undefined" && search)
-        })
+      <script id="__config" type="application/json">
+        {{- app | tojson -}}
       </script>
+    {% endblock %}
+    {% block scripts %}
+      <script src="{{ 'assets/javascripts/bundle.926459b3.min.js' | url }}"></script>
       {% for path in config["extra_javascript"] %}
         <script src="{{ path | url }}"></script>
       {% endfor %}

-    <div class="md-footer-nav">
-      <nav class="md-footer-nav__inner md-grid" aria-label="{{ lang.t('footer.title') }}">
-        {% if page.previous_page %}
-          <a href="{{ page.previous_page.url | url }}" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
-            <div class="md-footer-nav__button md-icon">
-              {% include ".icons/material/arrow-left.svg" %}
-            </div>
-            <div class="md-footer-nav__title">
-              <div class="md-ellipsis">
-                <span class="md-footer-nav__direction">
-                  {{ lang.t("footer.previous") }}
-                </span>
-                {{ page.previous_page.title }}
-              </div>
-            </div>
-          </a>
-        {% endif %}
-        {% if page.next_page %}
-          <a href="{{ page.next_page.url | url }}" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
-            <div class="md-footer-nav__title">
-              <div class="md-ellipsis">
-                <span class="md-footer-nav__direction">
-                  {{ lang.t("footer.next") }}
-                </span>
-                {{ page.next_page.title }}
-              </div>
+    <nav class="md-footer__inner md-grid" aria-label="{{ lang.t('footer.title') }}">
+      {% if page.previous_page %}
+        <a href="{{ page.previous_page.url | url }}" class="md-footer__link md-footer__link--prev" rel="prev">
+          <div class="md-footer__button md-icon">
+            {% include ".icons/material/arrow-left.svg" %}
+          </div>
+          <div class="md-footer__title">
+            <div class="md-ellipsis">
+              <span class="md-footer__direction">
+                {{ lang.t("footer.previous") }}
+              </span>
+              {{ page.previous_page.title }}
             </div>
-            <div class="md-footer-nav__button md-icon">
-              {% include ".icons/material/arrow-right.svg" %}
+          </div>
+        </a>
+      {% endif %}
+      {% if page.next_page %}
+        <a href="{{ page.next_page.url | url }}" class="md-footer__link md-footer__link--next" rel="next">
+          <div class="md-footer__title">
+            <div class="md-ellipsis">
+              <span class="md-footer__direction">
+                {{ lang.t("footer.next") }}
+              </span>
+              {{ page.next_page.title }}
             </div>
-          </a>
-        {% endif %}
-      </nav>
-    </div>
+          </div>
+          <div class="md-footer__button md-icon">
+            {% include ".icons/material/arrow-right.svg" %}
+          </div>
+        </a>
+      {% endif %}
+    </nav>
   {% endif %}
   <div class="md-footer-meta md-typeset">
     <div class="md-footer-meta__inner md-grid">

@@ -6,21 +6,21 @@
   {% set site_url = site_url ~ "/index.html" %}
 {% endif %}
 <header class="md-header" data-md-component="header">
-  <nav class="md-header-nav md-grid" aria-label="{{ lang.t('header.title') }}">
-    <a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header-nav__button md-logo" aria-label="{{ config.site_name }}">
+  <nav class="md-header__inner md-grid" aria-label="{{ lang.t('header.title') }}">
+    <a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}">
       {% include "partials/logo.html" %}
     </a>
-    <label class="md-header-nav__button md-icon" for="__drawer">
+    <label class="md-header__button md-icon" for="__drawer">
       {% include ".icons/material/menu" ~ ".svg" %}
     </label>
-    <div class="md-header-nav__title" data-md-component="header-title">
-      <div class="md-header-nav__ellipsis">
-        <div class="md-header-nav__topic">
+    <div class="md-header__title" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        <div class="md-header__topic">
           <span class="md-ellipsis">
             {{ config.site_name }}
           </span>
         </div>
-        <div class="md-header-nav__topic">
+        <div class="md-header__topic" data-md-component="header-topic">
           <span class="md-ellipsis">
             {% if page and page.meta and page.meta.title %}
               {{ page.meta.title }}
@@ -31,14 +31,35 @@
         </div>
       </div>
     </div>
+    <div class="md-header__options">
+      {% if config.extra.alternate %}
+        <div class="md-select">
+          {% set icon = config.theme.icon.alternate or "material/translate" %}
+          <span class="md-header__button md-icon">
+            {% include ".icons/" ~ icon ~ ".svg" %}
+          </span>
+          <div class="md-select__inner">
+            <ul class="md-select__list">
+              {% for alt in config.extra.alternate %}
+                <li class="md-select__item">
+                  <a href="{{ alt.link | url }}" class="md-select__link">
+                    {{ alt.name }}
+                  </a>
+                </li>
+                {% endfor %}
+            </ul>
+          </div>
+        </div>
+      {% endif %}
+    </div>
     {% if "search" in config["plugins"] %}
-      <label class="md-header-nav__button md-icon" for="__search">
+      <label class="md-header__button md-icon" for="__search">
         {% include ".icons/material/magnify.svg" %}
       </label>
       {% include "partials/search.html" %}
     {% endif %}
     {% if config.repo_url %}
-      <div class="md-header-nav__source">
+      <div class="md-header__source">
         {% include "partials/source.html" %}
       </div>
     {% endif %}

@@ -4,5 +4,5 @@
 {% import "partials/language.html" as lang with context %}
-<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source">
+<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}"  class="md-source" data-md-component="source">
   <div class="md-source__icon md-icon">
     {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
     {% include ".icons/" ~ icon ~ ".svg" %}

@@ -12,7 +12,7 @@
       <span class="md-nav__icon md-icon"></span>
       {{ lang.t("toc.title") }}
     </label>
-    <ul class="md-nav__list" data-md-scrollfix>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       {% for toc_item in toc %}
         {% include "partials/toc-item.html" %}
       {% endfor %}

从 5.x 升级到 6.x¶

新增功能¶

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

对 `mkdocs.yml` 的更改¶

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

`theme.features`¶

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

6.x5.x

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

theme:
  features:
    - tabs
    - instant

对 `*.html` 文件的更改¶

模板经历了一系列更改，以使其未来可用。如果您使用主题扩展覆盖了某个块或模板，请确保它符合新结构：

如果您覆盖了 block，请检查 base.html 以查找潜在更改
如果您覆盖了 template，请检查相应的 *.html 文件以查找潜在更改

base.html partials/hero.html partials/source-link

@@ -22,13 +22,6 @@

 {% import "partials/language.html" as lang with context %}

-<!-- Theme options -->
-{% set palette = config.theme.palette %}
-{% if not palette is mapping %}
-  {% set palette = palette | first %}
-{% endif %}
-{% set font = config.theme.font %}
-
 <!doctype html>
 <html lang="{{ lang.t('language') }}" class="no-js">
   <head>
@@ -45,21 +38,8 @@
         <meta name="description" content="{{ config.site_description }}" />
       {% endif %}

-      <!-- Redirect -->
-      {% if page and page.meta and page.meta.redirect %}
-        <script>
-          var anchor = window.location.hash.substr(1)
-          location.href = '{{ page.meta.redirect }}' +
-            (anchor ? '#' + anchor : '')
-        </script>
-
-        <!-- Fallback in case JavaScript is not available -->
-        <meta http-equiv="refresh" content="0; url={{ page.meta.redirect }}" />
-        <meta name="robots" content="noindex" />
-        <link rel="canonical" href="{{ page.meta.redirect }}" />
-
       <!-- Canonical -->
-      {% elif page.canonical_url %}
+      {% if page.canonical_url %}
         <link rel="canonical" href="{{ page.canonical_url }}" />
       {% endif %}

@@ -96,20 +76,21 @@
       <link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />

       <!-- Extra color palette -->
-      {% if palette.scheme or palette.primary or palette.accent %}
+      {% if config.theme.palette %}
+        {% set palette = config.theme.palette %}
         <link
           rel="stylesheet"
           href="{{ 'assets/stylesheets/palette.css' | url }}"
         />
-      {% endif %}

-      <!-- Theme-color meta tag for Android -->
-      {% if palette.primary %}
-        {% import "partials/palette.html" as map %}
-        {% set primary = map.primary(
-          palette.primary | replace(" ", "-") | lower
-        ) %}
-        <meta name="theme-color" content="{{ primary }}" />
+        <!-- Theme-color meta tag for Android -->
+        {% if palette.primary %}
+          {% import "partials/palette.html" as map %}
+          {% set primary = map.primary(
+            palette.primary | replace(" ", "-") | lower
+          ) %}
+          <meta name="theme-color" content="{{ primary }}" />
+        {% endif %}
       {% endif %}
     {% endblock %}

@@ -120,7 +101,8 @@
     {% block fonts %}

       <!-- Load fonts from Google -->
-      {% if font != false %}
+      {% if config.theme.font != false %}
+        {% set font = config.theme.font %}
         <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin />
         <link
          rel="stylesheet"
@@ -169,8 +151,12 @@

   <!-- Text direction and color palette, if defined -->
   {% set direction = config.theme.direction or lang.t('direction') %}
-  {% if palette.scheme or palette.primary or palette.accent %}
-    {% set scheme  = palette.scheme | lower %}
+  {% if config.theme.palette %}
+    {% set palette = config.theme.palette %}
+    {% if not palette is mapping %}
+      {% set palette = palette | first %}
+    {% endif %}
+    {% set scheme  = palette.scheme  | replace(" ", "-") | lower %}
     {% set primary = palette.primary | replace(" ", "-") | lower %}
     {% set accent  = palette.accent  | replace(" ", "-") | lower %}
     <body
@@ -179,18 +165,19 @@
       data-md-color-primary="{{ primary }}"
       data-md-color-accent="{{ accent }}"
     >
+
+      <!-- Experimental: set color scheme based on preference -->
+      {% if "preference" == scheme %}
+        <script>
+          if (matchMedia("(prefers-color-scheme: dark)").matches)
+            document.body.setAttribute("data-md-color-scheme", "slate")
+        </script>
+      {% endif %}
+
   {% else %}
     <body dir="{{ direction }}">
   {% endif %}

-    <!-- Experimental: set color scheme based on preference -->
-    {% if "preference" == palette.scheme %}
-      <script>
-        if (matchMedia("(prefers-color-scheme: dark)").matches)
-          document.body.setAttribute("data-md-color-scheme", "slate")
-      </script>
-    {% endif %}
-
     <!--
       State toggles - we need to set autocomplete="off" in order to reset the
       drawer on back button invocation in some browsers
@@ -243,15 +230,11 @@
     <div class="md-container" data-md-component="container">

       <!-- Hero teaser -->
-      {% block hero %}
-        {% if page and page.meta and page.meta.hero %}
-          {% include "partials/hero.html" with context %}
-        {% endif %}
-      {% endblock %}
+      {% block hero %}{% endblock %}

       <!-- Tabs navigation -->
       {% block tabs %}
-        {% if "tabs" in config.theme.features %}
+        {% if "navigation.tabs" in config.theme.features %}
           {% include "partials/tabs.html" %}
         {% endif %}
       {% endblock %}
@@ -310,13 +293,6 @@
                   </a>
                 {% endif %}

-                <!-- Link to source file -->
-                {% block source %}
-                  {% if page and page.meta and page.meta.source %}
-                    {% include "partials/source-link.html" %}
-                  {% endif %}
-                {% endblock %}
-
                 <!--
                   Hack: check whether the content contains a h1 headline. If it
                   doesn't, the page title (or respectively site name) is used
@@ -370,7 +346,10 @@
         "search.result.placeholder",
         "search.result.none",
         "search.result.one",
-        "search.result.other"
+        "search.result.other",
+        "search.result.more.one",
+        "search.result.more.other",
+        "search.result.term.missing"
       ] -%}
         {%- set _ = translations.update({ key: lang.t(key) }) -%}
       {%- endfor -%}

@@ -1,12 +0,0 @@
-{#-
-  This file was automatically generated - do not edit
--#}
-{% set class = "md-hero" %}
-{% if "tabs" not in config.theme.features %}
-  {% set class = "md-hero md-hero--expand" %}
-{% endif %}
-<div class="{{ class }}" data-md-component="hero">
-  <div class="md-hero__inner md-grid">
-    {{ page.meta.hero }}
-  </div>
-</div>

@@ -1,14 +0,0 @@
-{#-
-  This file was automatically generated - do not edit
--#}
-{% import "partials/language.html" as lang with context %}
-{% set repo = config.repo_url %}
-{% if repo | last == "/" %}
-  {% set repo = repo[:-1] %}
-{% endif %}
-{% set path = page.meta.path | default("") %}
-<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ page.meta.source }}" class="md-content__button md-icon">
-  {{ lang.t("meta.source") }}
-  {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
-  {% include ".icons/" ~ icon ~ ".svg" %}
-</a>

从 4.x 升级到 5.x¶

新增功能¶

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

对 `mkdocs.yml` 的更改¶

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

`theme.feature`¶

可选功能，如 tabs 和 instant loading 现在作为标志实现，可以通过在 mkdocs.yml 中列出它们来启用：

5.x4.x

theme:
  features:
    - tabs
    - instant

theme:
  feature:
    tabs: true

`theme.logo.icon`¶

徽标图标配置已集中在 theme.icon.logo 下，现在可以设置为主题中捆绑的任何图标：

5.x4.x

theme:
  icon:
    logo: material/cloud

theme:
  logo:
    icon: cloud

`extra.repo_icon`¶

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

5.x4.x

theme:
  icon:
    repo: fontawesome/brands/gitlab

extra:
  repo_icon: gitlab

`extra.search.*`¶

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

5.x4.x

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

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

`extra.social.*`¶

社交链接保持在同一位置，但 type 键已重命名为 icon 以匹配新的指定要使用哪个图标的方式：

5.x4.x

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

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

对 `*.html` 文件的更改¶

模板经历了一系列更改，以使其未来可用。如果您使用主题扩展覆盖了某个块或模板，请确保它符合新结构：

如果您覆盖了 block，请检查 base.html 以查找潜在更改
如果您覆盖了 template，请检查相应的 *.html 文件以查找潜在更改

base.html partials/footer.html partials/header.html partials/hero.html partials/language.html partials/logo.html partials/nav-item.html partials/nav.html

@@ -4,7 +4,6 @@
 {% import "partials/language.html" as lang with context %}
-{% set feature = config.theme.feature %}
 {% set palette = config.theme.palette %}
 {% set font = config.theme.font %}
 <!doctype html>
@@ -30,19 +29,6 @@
       {% elif config.site_author %}
         <meta name="author" content="{{ config.site_author }}">
       {% endif %}
-      {% for key in [
-        "clipboard.copy",
-        "clipboard.copied",
-        "search.language",
-        "search.pipeline.stopwords",
-        "search.pipeline.trimmer",
-        "search.result.none",
-        "search.result.one",
-        "search.result.other",
-        "search.tokenizer"
-      ] %}
-        <meta name="lang:{{ key }}" content="{{ lang.t(key) }}">
-      {% endfor %}
       <link rel="shortcut icon" href="{{ config.theme.favicon | url }}">
       <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.0.0">
     {% endblock %}
@@ -56,9 +42,9 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/application.********.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.********.min.css' | url }}">
       {% if palette.primary or palette.accent %}
-        <link rel="stylesheet" href="{{ 'assets/stylesheets/application-palette.********.css' | url }}">
+        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.********.min.css' | url }}">
       {% endif %}
       {% if palette.primary %}
         {% import "partials/palette.html" as map %}
@@ -69,20 +55,17 @@
       {% endif %}
     {% endblock %}
     {% block libs %}
-      <script src="{{ 'assets/javascripts/modernizr.********.js' | url }}"></script>
     {% endblock %}
     {% block fonts %}
       {% if font != false %}
         <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
         <link rel="stylesheet" href="https://fonts.googleapis.com/css?family={{
             font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
             font.code | replace(' ', '+')
           }}&display=fallback">
         <style>body,input{font-family:"{{ font.text }}","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"{{ font.code }}","Courier New",Courier,monospace}</style>
       {% endif %}
     {% endblock %}
-    <link rel="stylesheet" href="{{ 'assets/fonts/material-icons.css' | url }}">
     {% if config.extra.manifest %}
       <link rel="manifest" href="{{ config.extra.manifest | url }}" crossorigin="use-credentials">
     {% endif %}
@@ -95,47 +77,50 @@
     {% endblock %}
     {% block extrahead %}{% endblock %}
   </head>
+  {% set direction = config.theme.direction | default(lang.t('direction')) %}
   {% if palette.primary or palette.accent %}
     {% set primary = palette.primary | replace(" ", "-") | lower %}
     {% set accent  = palette.accent  | replace(" ", "-") | lower %}
-    <body dir="{{ lang.t('direction') }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
+    <body dir="{{ direction }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
   {% else %}
-    <body dir="{{ lang.t('direction') }}">
+    <body dir="{{ direction }}">
   {% endif %}
-    <svg class="md-svg">
-      <defs>
-        {% set platform = config.extra.repo_icon or config.repo_url %}
-        {% if "github" in platform %}
-          {% include "assets/images/icons/github.f0b8504a.svg" %}
-        {% elif "gitlab" in platform %}
-          {% include "assets/images/icons/gitlab.6dd19c00.svg" %}
-        {% elif "bitbucket" in platform %}
-          {% include "assets/images/icons/bitbucket.1b09e088.svg" %}
-        {% endif %}
-      </defs>
-    </svg>
     <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
     <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
-    <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
+    <label class="md-overlay" for="__drawer"></label>
+    <div data-md-component="skip">
+      {% if page.toc | first is defined %}
+        {% set skip = page.toc | first %}
+        <a href="{{ skip.url | url }}" class="md-skip">
+          {{ lang.t('skip.link.title') }}
+        </a>
+      {% endif %}
+    </div>
+    <div data-md-component="announce">
+      {% if self.announce() %}
+        <aside class="md-announce">
+          <div class="md-announce__inner md-grid md-typeset">
+            {% block announce %}{% endblock %}
+          </div>
+        </aside>
+      {% endif %}
     {% block header %}
       {% include "partials/header.html" %}
     {% endblock %}
-    <div class="md-container">
+    <div class="md-container" data-md-component="container">
       {% block hero %}
         {% if page and page.meta and page.meta.hero %}
           {% include "partials/hero.html" with context %}
         {% endif %}
       {% endblock %}
-      {% if feature.tabs %}
-        {% include "partials/tabs.html" %}
-      {% endif %}
+      {% block tabs %}
+        {% if "tabs" in config.theme.features %}
+          {% include "partials/tabs.html" %}
+        {% endif %}
+      {% endblock %}
-      <main class="md-main" role="main">
-        <div class="md-main__inner md-grid" data-md-component="container">
+      <main class="md-main" data-md-component="main">
+        <div class="md-main__inner md-grid">
           {% block site_nav %}
             {% if nav %}
               <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
@@ -160,41 +141,25 @@
             <article class="md-content__inner md-typeset">
               {% block content %}
                 {% if page.edit_url %}
-                  <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-icon md-content__icon">&#xE3C9;</a>
+                  <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-content__button md-icon">
+                    {% include ".icons/material/pencil.svg" %}
+                  </a>
                 {% endif %}
+                {% block source %}
+                  {% if page and page.meta and page.meta.source %}
+                    {% include "partials/source-link.html" %}
+                  {% endif %}
+                {% endblock %}
                 {% if not "\x3ch1" in page.content %}
                   <h1>{{ page.title | default(config.site_name, true)}}</h1>
                 {% endif %}
                 {{ page.content }}
-                {% block source %}
-                  {% if page and page.meta and page.meta.source %}
-                    <h2 id="__source">{{ lang.t("meta.source") }}</h2>
-                    {% set repo = config.repo_url %}
-                    {% if repo | last == "/" %}
-                      {% set repo = repo[:-1] %}
-                    {% endif %}
-                    {% set path = page.meta.path | default([""]) %}
-                    {% set file = page.meta.source %}
-                    <a href="{{ [repo, path, file] | join('/') }}" title="{{ file }}" class="md-source-file">
-                      {{ file }}
-                    </a>
-                  {% endif %}
-                {% endblock %}
-                {% if page and page.meta and (
-                      page.meta.git_revision_date_localized or
-                      page.meta.revision_date
-                ) %}
-                  {% set label = lang.t("source.revision.date") %}
-                  <hr>
-                  <div class="md-source-date">
-                    <small>
-                      {% if page.meta.git_revision_date_localized %}
-                        {{ label }}: {{ page.meta.git_revision_date_localized }}
-                      {% elif page.meta.revision_date %}
-                        {{ label }}: {{ page.meta.revision_date }}
-                      {% endif %}
-                    </small>
-                  </div>
                 {% endif %}
               {% endblock %}
               {% block disqus %}
@@ -208,29 +174,35 @@
         {% include "partials/footer.html" %}
       {% endblock %}
     </div>
     {% block scripts %}
-      <script src="{{ 'assets/javascripts/application.********.js' | url }}"></script>
-      {% if lang.t("search.language") != "en" %}
-        {% set languages = lang.t("search.language").split(",") %}
-        {% if languages | length and languages[0] != "" %}
-          {% set path = "assets/javascripts/lunr/" %}
-          <script src="{{ (path ~ 'lunr.stemmer.support.js') | url }}"></script>
-          {% for language in languages | map("trim") %}
-            {% if language != "en" %}
-              {% if language == "ja" %}
-                <script src="{{ (path ~ 'tinyseg.js') | url }}"></script>
-              {% endif %}
-              {% if language in ("ar", "da", "de", "es", "fi", "fr", "hu", "it", "ja", "nl", "no", "pt", "ro", "ru", "sv", "th", "tr", "vi") %}
-                <script src="{{ (path ~ 'lunr.' ~ language ~ '.js') | url }}"></script>
-              {% endif %}
-            {% endif %}
-          {% endfor %}
-          {% if languages | length > 1 %}
-            <script src="{{ (path ~ 'lunr.multi.js') | url }}"></script>
-          {% endif %}
-        {% endif %}
-      {% endif %}
-      <script>app.initialize({version:"{{ mkdocs_version }}",url:{base:"{{ base_url }}"}})</script>
+      <script src="{{ 'assets/javascripts/vendor.********.min.js' | url }}"></script>
+      <script src="{{ 'assets/javascripts/bundle.********.min.js' | url }}"></script>
+      {%- set translations = {} -%}
+      {%- for key in [
+        "clipboard.copy",
+        "clipboard.copied",
+        "search.config.lang",
+        "search.config.pipeline",
+        "search.config.separator",
+        "search.result.placeholder",
+        "search.result.none",
+        "search.result.one",
+        "search.result.other"
+      ] -%}
+        {%- set _ = translations.update({ key: lang.t(key) }) -%}
+      {%- endfor -%}
+      <script id="__lang" type="application/json">
+        {{- translations | tojson -}}
+      </script>
+      {% block config %}{% endblock %}
+      <script>
+        app = initialize({
+          base: "{{ base_url }}",
+          features: {{ config.theme.features | tojson }},
+          search: Object.assign({
+            worker: "{{ 'assets/javascripts/worker/search.********.min.js' | url }}"
+          }, typeof search !== "undefined" && search)
+        })
       {% for path in config["extra_javascript"] %}
         <script src="{{ path | url }}"></script>
       {% endfor %}

@@ -5,34 +5,34 @@
     <div class="md-footer-nav">
-      <nav class="md-footer-nav__inner md-grid">
+      <nav class="md-footer-nav__inner md-grid" aria-label="{{ lang.t('footer.title') }}">
         {% if page.previous_page %}
-          <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
-            <div class="md-flex__cell md-flex__cell--shrink">
-              <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
+          <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
+            <div class="md-footer-nav__button md-icon">
+              {% include ".icons/material/arrow-left.svg" %}
             </div>
-            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
-              <span class="md-flex__ellipsis">
+            <div class="md-footer-nav__title">
+              <div class="md-ellipsis">
                 <span class="md-footer-nav__direction">
                   {{ lang.t("footer.previous") }}
                 </span>
                 {{ page.previous_page.title }}
-              </span>
+              </div>
             </div>
           </a>
         {% endif %}
         {% if page.next_page %}
-          <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
-            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
-              <span class="md-flex__ellipsis">
+          <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
+            <div class="md-footer-nav__title">
+              <div class="md-ellipsis">
                 <span class="md-footer-nav__direction">
                   {{ lang.t("footer.next") }}
                 </span>
                 {{ page.next_page.title }}
-              </span>
+              </div>
             </div>
-            <div class="md-flex__cell md-flex__cell--shrink">
-              <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
+            <div class="md-footer-nav__button md-icon">
+              {% include ".icons/material/arrow-right.svg" %}
             </div>
           </a>
         {% endif %}

@@ -4,51 +4,43 @@
 <header class="md-header" data-md-component="header">
-  <nav class="md-header-nav md-grid">
-    <div class="md-flex">
-      <div class="md-flex__cell md-flex__cell--shrink">
-        <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-header-nav__button md-logo">
-          {% if config.theme.logo.icon %}
-            <i class="md-icon">{{ config.theme.logo.icon }}</i>
-          {% else %}
-            <img alt="logo" src="{{ config.theme.logo | url }}" width="24" height="24">
-          {% endif %}
-        </a>
-      </div>
-      <div class="md-flex__cell md-flex__cell--shrink">
-        <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
-      </div>
-      <div class="md-flex__cell md-flex__cell--stretch">
-        <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
-          {% if config.site_name == page.title %}
-            {{ config.site_name }}
-          {% else %}
-            <span class="md-header-nav__topic">
-              {{ config.site_name }}
-            </span>
-            <span class="md-header-nav__topic">
-              {% if page and page.meta and page.meta.title %}
-                {{ page.meta.title }}
-              {% else %}
-                {{ page.title }}
-              {% endif %}
-            </span>
-          {% endif %}
+  <nav class="md-header-nav md-grid" aria-label="{{ lang.t('header.title') }}">
+    <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-header-nav__button md-logo" aria-label="{{ config.site_name }}">
+      {% include "partials/logo.html" %}
+    </a>
+    <label class="md-header-nav__button md-icon" for="__drawer">
+      {% include ".icons/material/menu" ~ ".svg" %}
+    </label>
+    <div class="md-header-nav__title" data-md-component="header-title">
+      {% if config.site_name == page.title %}
+        <div class="md-header-nav__ellipsis md-ellipsis">
+          {{ config.site_name }}
         </div>
-      </div>
-      <div class="md-flex__cell md-flex__cell--shrink">
-        {% if "search" in config["plugins"] %}
-          <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
-          {% include "partials/search.html" %}
-        {% endif %}
-      </div>
-      {% if config.repo_url %}
-        <div class="md-flex__cell md-flex__cell--shrink">
-          <div class="md-header-nav__source">
-            {% include "partials/source.html" %}
-          </div>
+      {% else %}
+        <div class="md-header-nav__ellipsis">
+          <span class="md-header-nav__topic md-ellipsis">
+            {{ config.site_name }}
+          </span>
+          <span class="md-header-nav__topic md-ellipsis">
+            {% if page and page.meta and page.meta.title %}
+              {{ page.meta.title }}
+            {% else %}
+              {{ page.title }}
+            {% endif %}
+          </span>
         </div>
       {% endif %}
     </div>
+    {% if "search" in config["plugins"] %}
+      <label class="md-header-nav__button md-icon" for="__search">
+        {% include ".icons/material/magnify.svg" %}
+      </label>
+      {% include "partials/search.html" %}
+    {% endif %}
+    {% if config.repo_url %}
+      <div class="md-header-nav__source">
+        {% include "partials/source.html" %}
+      </div>
+    {% endif %}
   </nav>
 </header>

@@ -4,9 +4,8 @@
-{% set feature = config.theme.feature %}
+{% if "tabs" not in config.theme.features %}
   {% set class = "md-hero md-hero--expand" %}
 {% endif %}
 <div class="{{ class }}" data-md-component="hero">

@@ -4,12 +4,4 @@
 {% import "partials/language/" + config.theme.language + ".html" as lang %}
 {% import "partials/language/en.html" as fallback %}
-{% macro t(key) %}{{ {
-  "direction": config.theme.direction,
-  "search.language": (
-    config.extra.search | default({})
-  ).language,
-  "search.tokenizer": (
-    config.extra.search | default({})
-  ).tokenizer | default("", true),
-}[key] or lang.t(key) or fallback.t(key) }}{% endmacro %}
+{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %}

@@ -0,0 +1,9 @@
+{#-
+  This file was automatically generated - do not edit
+-#}
+{% if config.theme.logo %}
+  <img src="{{ config.theme.logo | url }}" alt="logo">
+{% else %}
+  {% set icon = config.theme.icon.logo or "material/library" %}
+  {% include ".icons/" ~ icon ~ ".svg" %}
+{% endif %}

@@ -14,9 +14,15 @@
     {% endif %}
     <label class="md-nav__link" for="{{ path }}">
       {{ nav_item.title }}
+      <span class="md-nav__icon md-icon">
+        {% include ".icons/material/chevron-right.svg" %}
+      </span>
     </label>
-    <nav class="md-nav" data-md-component="collapsible" data-md-level="{{ level }}">
+    <nav class="md-nav" aria-label="{{ nav_item.title }}" data-md-level="{{ level }}">
       <label class="md-nav__title" for="{{ path }}">
+        <span class="md-nav__icon md-icon">
+          {% include ".icons/material/arrow-left.svg" %}
+        </span>
         {{ nav_item.title }}
       </label>
       <ul class="md-nav__list" data-md-scrollfix>
@@ -39,6 +45,9 @@
     {% if toc | first is defined %}
       <label class="md-nav__link md-nav__link--active" for="__toc">
         {{ nav_item.title }}
+        <span class="md-nav__icon md-icon">
+          {% include ".icons/material/table-of-contents.svg" %}
+        </span>
       </label>
     {% endif %}
     <a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active">

``` diff @@ -4,14 +4,10 @@ -

如何升级¶

从 8.x 升级到 9.x¶

对 mkdocs.yml 的更改¶

content.code.copy¶

content.action.*¶

navigation.footer¶

theme.language¶

feedback.ratings¶

对 *.html 文件的更改¶

从 7.x 升级到 8.x¶

新增功能¶

对 mkdocs.yml 的更改¶

pymdownx.tabbed¶

pymdownx.superfences¶

google_analytics¶

对 *.html 文件的更改¶

从 6.x 升级到 7.x¶

新增功能¶

对 mkdocs.yml 的更改¶

extra.version.method¶

对 *.html 文件的更改¶

从 5.x 升级到 6.x¶

新增功能¶

对 mkdocs.yml 的更改¶

theme.features¶

对 *.html 文件的更改¶

从 4.x 升级到 5.x¶

新增功能¶

对 mkdocs.yml 的更改¶

theme.feature¶

theme.logo.icon¶

extra.repo_icon¶

extra.search.*¶

extra.social.*¶

对 *.html 文件的更改¶

对 `mkdocs.yml` 的更改¶

`content.code.copy`¶

`content.action.*`¶

`navigation.footer`¶

`theme.language`¶

`feedback.ratings`¶

对 `*.html` 文件的更改¶

对 `mkdocs.yml` 的更改¶

`pymdownx.tabbed`¶

`pymdownx.superfences`¶

`google_analytics`¶

对 `*.html` 文件的更改¶

对 `mkdocs.yml` 的更改¶

`extra.version.method`¶

对 `*.html` 文件的更改¶

对 `mkdocs.yml` 的更改¶

`theme.features`¶

对 `*.html` 文件的更改¶

对 `mkdocs.yml` 的更改¶

`theme.feature`¶

`theme.logo.icon`¶

`extra.repo_icon`¶

`extra.search.*`¶

`extra.social.*`¶

对 `*.html` 文件的更改¶