如何升级¶
¥How to upgrade¶
使用以下方法升级到最新版本：
¥Upgrade to the latest version with:
显示当前安装的版本：
¥Show the currently installed version with:
从 8.x 升级到 9.x¶
¥Upgrading from 8.x to 9.x¶
此主要版本包含一个全新的搜索实现，速度更快，并支持丰富的预览、高级标记化和更出色的高亮显示。它作为 Insiders 版本的一部分已发布一年多，如今已达到众筹目标，现已加入社区版本。
¥This major release includes a brand new search implementation that is faster and allows for rich previews, advanced tokenization and better highlighting. It was available as part of Insiders for over a year, and now that the funding goal was hit, makes its way into the community edition.
mkdocs.yml的变更¶
¥Changes to mkdocs.yml¶
content.code.copy¶
¥content.code.copy¶
“复制到剪贴板”按钮现在是可选的，可以针对每个代码块启用或禁用。如果您希望为所有代码块启用它们，请在mkdocs.yml中添加以下几行：
¥The copy-to-clipboard buttons are now opt-in and can be enabled or disabled per block. If you wish to enable them for all code blocks, add the following lines to mkdocs.yml:
content.action.*¶
¥content.action.*¶
“查看源代码”按钮可以显示在“编辑此页面”按钮旁边，现在必须显式启用这两个按钮。将以下几行添加到mkdocs.yml中：
¥A "view source" button can be shown next to the "edit this page" button, both of which must now be explicitly enabled. Add the following lines to mkdocs.yml:
navigation.footer¶
¥navigation.footer¶
页脚中的“上一个”和“下一个”按钮现在是可选的。如果您希望在文档中保留它们，请将以下几行添加到mkdocs.yml中：
¥The previous and next buttons in the footer are now opt-in. If you wish to keep them for your documentation, add the following lines to mkdocs.yml:
theme.language¶
¥theme.language¶
韩语和挪威语语言代码已被重新命名，因为它们是非标准的：
¥The Korean and Norwegian language codes were renamed, as they were non-standard:
kr到ko¥
krtokono接受nb¥
notonb
feedback.ratings¶
¥feedback.ratings¶
旧的无名占位符已被移除（弃用了几个月之后）。请确保切换到新的命名占位符{title}和{url} ：
¥The old, nameless placeholders were removed (after being deprecated for several months). Make sure to switch to the new named placeholders {title} and {url}:
对*.html文件的更改¶
¥Changes to *.html files¶
模板已经历一系列变更。如果您已使用主题扩展定制了 Material for MkDocs，请务必将最新的变更整合到您的模板中。您可以先检查 diff 。
¥The templates have undergone a series of changes. If you have customized Material for MkDocs with theme extension, be sure to incorporate the latest changes into your templates. A good starting point is to inspect the diff.
升级后内置插件无法使用？
¥Built-in plugins not working after upgrade?
如果某个内置插件（搜索或标签）在没有任何明显错误或原因的情况下无法正常工作，则很可能与自定义覆盖有关。MkDocs 1.4.1及更高版本允许主题使用命名空间内置插件，Material for MkDocs 9 现在也支持此功能，以便作者可以使用与内置插件同名的第三方插件。请在您的覆盖中搜索“in config.plugins” ，并添加material/命名空间。受影响的部分：
¥If one of the built-in plugins (search or tags) doesn't work anymore without any apparent error or cause, it is very likely related to custom overrides. MkDocs 1.4.1 and above allow themes to namespace built-in plugins, which Material for MkDocs 9 now does in order to allow authors to use third-party plugins with the same name as built-in plugins. Search your overrides for "in config.plugins" and add the material/ namespace. Affected partials:
从 7.x 升级到 8.x¶
¥Upgrading from 7.x to 8.x¶
什么是新的？¶
¥What's new?¶
增加了对代码注释的支持
¥Added support for code annotations
增加了对锚点跟踪的支持
¥Added support for anchor tracking
增加了对版本警告的支持
¥Added support for version warning
添加了部分
copyright以便于覆盖¥Added
copyrightpartial for easier override删除了已弃用的内容标签旧版实现
¥Removed deprecated content tabs legacy implementation
删除了已弃用的
seealso警告类型¥Removed deprecated
seealsoadmonition type删除了已弃用的
site_keywords设置（MkDocs 不支持）¥Removed deprecated
site_keywordssetting (unsupported by MkDocs)删除了已弃用的预建搜索索引支持
¥Removed deprecated prebuilt search index support
删除了已弃用的 Web 应用清单 - 使用自定义
¥Removed deprecated web app manifest – use customization
删除了
extracopyright变量 – 使用新的copyright部分¥Removed
extracopyrightvariable – use newcopyrightpartial删除 Disqus 集成 – 使用自定义
¥Removed Disqus integration – use customization
切换到
:is()选择器以获取简单的选择器列表¥Switched to
:is()selectors for simple selector lists将自动前缀从
last 4 years更改为last 2 years¥Switched autoprefixer from
last 4 yearstolast 2 years全面改进 CSS，以符合现代标准
¥Improved CSS overall to match modern standards
改进了字体的 CSS 变量语义
¥Improved CSS variable semantics for fonts
通过重组部分结构来提高可扩展性
¥Improved extensibility by restructuring partials
改进了打印时的
details处理¥Improved handling of
detailswhen printing改进了脚注的键盘导航
¥Improved keyboard navigation for footnotes
已修复#3214 ：搜索突出显示在空白处中断网站
¥Fixed #3214: Search highlighting breaks site when empty
mkdocs.yml的变更¶
¥Changes to mkdocs.yml¶
pymdownx.tabbed¶
¥pymdownx.tabbed¶
我们不再支持Tabbed扩展的旧式风格，转而采用在移动视口上具有更好行为的新替代实现：
¥Support for the legacy style of the Tabbed extension was dropped in favor of the new, alternate implementation which has better behavior on mobile viewports:
pymdownx.superfences¶
¥pymdownx.superfences¶
必须从自定义栅栏类属性中删除*-experimental后缀，该属性用于定位要使用Mermaid.js呈现为图表的代码块：
¥The *-experimental suffix must be removed from the custom fence class property, which is used to target code blocks to be rendered as diagrams using Mermaid.js:
google_analytics¶
¥google_analytics¶
此选项在 MkDocs 1.2.0 中已弃用，因为基于 JavaScript 的分析集成的实现是主题的责任。必须更改以下几行：
¥This option was deprecated in MkDocs 1.2.0, as the implementation of a JavaScript-based analytics integration is the responsibility of a theme. The following lines must be changed:
对*.html文件的更改¶
¥Changes to *.html files¶
模板已进行一系列更改，以确保其面向未来。如果您使用主题扩展覆盖了某个块或模板，请确保其与新结构匹配：
¥The templates have undergone a set of changes to make them future-proof. If you've used theme extension to override a block or template, make sure that it matches the new structure:
如果您覆盖了某个块，请检查
base.html以了解潜在的更改¥If you've overridden a block, check
base.htmlfor potential changes如果您覆盖了模板，请检查相应的
*.html文件是否存在潜在的更改¥If you've overridden a template, check the respective
*.htmlfile for potential changes
@@ -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¶
¥Upgrading from 6.x to 7.x¶
什么是新的？¶
¥What's new?¶
增加了对部署多个版本的支持
¥Added support for deploying multiple versions
增加了对集成语言选择器的支持
¥Added support for integrating a language selector
增加了将警告渲染为内联块的支持
¥Added support for rendering admonitions as inline blocks
重写底层反应式架构
¥Rewrite of the underlying reactive architecture
删除了 Webpack，转而采用响应式构建策略（-480 个依赖项）
¥Removed Webpack in favor of reactive build strategy (–480 dependencies)
修复了内容选项卡切换后代码块的键盘导航
¥Fixed keyboard navigation for code blocks after content tabs switch
mkdocs.yml的变更¶
¥Changes to mkdocs.yml¶
extra.version.method¶
¥extra.version.method¶
版本控制方法配置已重命名为extra.version.provider ，以允许将来采用不同的版本控制策略：
¥The versioning method configuration was renamed to extra.version.provider to allow for different versioning strategies in the future:
对*.html文件的更改¶
¥Changes to *.html files¶
模板已进行一系列更改，以确保其面向未来。如果您使用主题扩展覆盖了某个块或模板，请确保其与新结构匹配：
¥The templates have undergone a set of changes to make them future-proof. If you've used theme extension to override a block or template, make sure that it matches the new structure:
如果您覆盖了某个块，请检查
base.html以了解潜在的更改¥If you've overridden a block, check
base.htmlfor potential changes如果您覆盖了模板，请检查相应的
*.html文件是否存在潜在的更改¥If you've overridden a template, check the respective
*.htmlfile for potential changes
@@ -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" %}
从 5.x 升级到 6.x¶
¥Upgrading from 5.x to 6.x¶
什么是新的？¶
¥What's new?¶
改进的搜索结果外观和感觉
¥Improved search result look and feel
提高了输入时搜索结果的稳定性
¥Improved search result stability while typing
改进的搜索结果分组（页面+标题）
¥Improved search result grouping (pages + headings)
提高搜索结果的相关性和评分
¥Improved search result relevance and scoring
添加了在搜索结果中显示缺失的查询词
¥Added display of missing query terms to search results
供应商软件包大小减少了 25% (84kb → 67kb)
¥Reduced size of vendor bundle by 25% (84kb → 67kb)
减小 Docker 镜像的大小以提高 CI 构建性能
¥Reduced size of the Docker image to improve CI build performance
删除英雄部分，支持自定义实现
¥Removed hero partial in favor of custom implementation
删除了已弃用的前置功能
¥Removed deprecated front matter features
mkdocs.yml的变更¶
¥Changes to mkdocs.yml¶
以下是需要对mkdocs.yml进行的更改列表。请注意，只有定义了该值时才需要调整它，因此，如果您的配置不包含该键，则可以跳过此操作。
¥Following is a list of changes that need to be made to mkdocs.yml. Note that you only have to adjust the value if you defined it, so if your configuration does not contain the key, you can skip it.
theme.features¶
¥theme.features¶
所有可从mkdocs.yml设置的功能标志（如选项卡和即时加载）现在都以其适用的组件或功能的名称为前缀，例如navigation.* ：
¥All feature flags that can be set from mkdocs.yml, like tabs and instant loading, are now prefixed with the name of the component or function they apply to, e.g. navigation.*:
对*.html文件的更改¶
¥Changes to *.html files¶
模板已进行一系列更改，以确保其面向未来。如果您使用主题扩展覆盖了某个块或模板，请确保其与新结构匹配：
¥The templates have undergone a set of changes to make them future-proof. If you've used theme extension to override a block or template, make sure that it matches the new structure:
如果您覆盖了某个块，请检查
base.html以了解潜在的更改¥If you've overridden a block, check
base.htmlfor potential changes如果您覆盖了模板，请检查相应的
*.html文件是否存在潜在的更改¥If you've overridden a template, check the respective
*.htmlfile for potential changes
@@ -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¶
¥Upgrading from 4.x to 5.x¶
什么是新的？¶
¥What's new?¶
响应式架构 – 在控制台中尝试
app.dialog$.next("Hi!")app . dialog$ . next ( "Hi!" )¥Reactive architecture – try
app.dialog$.next("Hi!")in the console即时加载——使 Material 的行为像单页应用程序一样
¥Instant loading – make Material behave like a Single Page Application
使用 CSS变量改进 CSS自定义 - 设置您的品牌颜色
¥Improved CSS customization with CSS variables – set your brand's colors
改进了 CSS 弹性，例如，自定义标题的正确侧边栏锁定
¥Improved CSS resilience, e.g. proper sidebar locking for customized headers
改进的图标集成和配置 - 现在包括超过 5000 个图标
¥Improved icon integration and configuration – now including over 5k icons
增加了使用任何图标作为徽标、存储库和社交链接的可能性
¥Added possibility to use any icon for logo, repository and social links
搜索 UI 不再冻结（移至 Web Worker）
¥Search UI does not freeze anymore (moved to web worker)
使用即时加载时仅构建一次搜索索引
¥Search index built only once when using instant loading
改进的可扩展键盘处理
¥Improved extensible keyboard handling
支持预建搜索索引
¥Support for prebuilt search indexes
支持显示 GitLab 存储库的星标和分支
¥Support for displaying stars and forks for GitLab repositories
支持侧边栏和搜索结果的滚动捕捉
¥Support for scroll snapping of sidebars and search results
由于不再支持 Internet Explorer，HTML 和 CSS 占用空间减少
¥Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
对一些 UI 元素（警告、表格等）进行了轻微的改进
¥Slight facelifting of some UI elements (admonitions, tables, ...)
mkdocs.yml的变更¶
¥Changes to mkdocs.yml¶
以下是需要对mkdocs.yml进行的更改列表。请注意，只有定义了该值时才需要调整它，因此，如果您的配置不包含该键，则可以跳过此操作。
¥Following is a list of changes that need to be made to mkdocs.yml. Note that you only have to adjust the value if you defined it, so if your configuration does not contain the key, you can skip it.
theme.feature¶
¥theme.feature¶
选项卡和即时加载等可选功能现在已作为标志实现，可以通过在theme.features下的mkdocs.yml中列出它们来启用它们：
¥Optional features like tabs and instant loading are now implemented as flags and can be enabled by listing them in mkdocs.yml under theme.features:
theme.logo.icon¶
¥theme.logo.icon¶
徽标图标配置集中在theme.icon.logo下，现在可以设置为与主题捆绑在一起的任何图标：
¥The logo icon configuration was centralized under theme.icon.logo and can now be set to any of the icons bundled with the theme:
extra.repo_icon¶
¥extra.repo_icon¶
repo 图标配置集中在theme.icon.repo下，现在可以设置为与主题捆绑在一起的任何图标：
¥The repo icon configuration was centralized under theme.icon.repo and can now be set to any of the icons bundled with the theme:
extra.search.*¶
¥extra.search.*¶
搜索现在已配置为插件选项的一部分。请注意，搜索语言现在必须列为字符串数组，并且tokenizer已重命名为separator ：
¥Search is now configured as part of the plugin options. Note that the search languages must now be listed as an array of strings and the tokenizer was renamed to separator:
extra.social.*¶
¥extra.social.*¶
社交链接保留在相同的位置，但type键被重命名为icon ，以匹配指定要使用哪个图标的新方式：
¥Social links stayed in the same place, but the type key was renamed to icon in order to match the new way of specifying which icon to be used:
对*.html文件的更改¶
¥Changes to *.html files¶
模板已进行一系列更改，以确保其面向未来。如果您使用主题扩展覆盖了某个块或模板，请确保其与新结构匹配：
¥The templates have undergone a set of changes to make them future-proof. If you've used theme extension to override a block or template, make sure that it matches the new structure:
如果您覆盖了某个块，请检查
base.html以了解潜在的更改¥If you've overridden a block, check
base.htmlfor potential changes如果您覆盖了模板，请检查相应的
*.html文件是否存在潜在的更改¥If you've overridden a template, check the respective
*.htmlfile for potential changes
@@ -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 %}
+ </div>
{% 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"></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 %}
+ {% if page.meta.git_revision_date_localized or
+ page.meta.revision_date
+ %}
+ {% include "partials/source-date.html" %}
- {% 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)
+ })
+ </script>
{% 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,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 %}
@@ -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">
@@ -4,14 +4,10 @@
-<nav class="md-nav md-nav--primary" data-md-level="0">
- <label class="md-nav__title md-nav__title--site" for="__drawer">
- <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-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="48" height="48">
- {% endif %}
+<nav class="md-nav md-nav--primary" aria-label="{{ lang.t('nav.title') }}" data-md-level="0">
+ <label class="md-nav__title" for="__drawer">
+ <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-nav__button md-logo" aria-label="{{ config.site_name }}">
+ {% include "partials/logo.html" %}
</a>
{{ config.site_name }}
</label>
@@ -6,15 +6,18 @@
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
- <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
+ <input type="text" class="md-search__input" name="query" aria-label="{{ lang.t('search.placeholder') }}" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active">
<label class="md-search__icon md-icon" for="__search">
+ {% include ".icons/material/magnify.svg" %}
+ {% include ".icons/material/arrow-left.svg" %}
</label>
- <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
- 
+ <button type="reset" class="md-search__icon md-icon" aria-label="{{ lang.t('search.reset') }}" data-md-component="search-reset" tabindex="-1">
+ {% include ".icons/material/close.svg" %}
</button>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" data-md-scrollfix>
- <div class="md-search-result" data-md-component="result">
+ <div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
{{ lang.t("search.result.placeholder") }}
</div>
@@ -4,9 +4,12 @@
{% if config.extra.social %}
<div class="md-footer-social">
- <link rel="stylesheet" href="{{ 'assets/fonts/font-awesome.css' | url }}">
{% for social in config.extra.social %}
- <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ social.type }}" class="md-footer-social__link fa fa-{{ social.type }}"></a>
+ {% set _,rest = social.link.split("//") %}
+ {% set domain = rest.split("/")[0] %}
+ <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ domain }}" class="md-footer-social__link">
+ {% include ".icons/" ~ social.icon ~ ".svg" %}
+ </a>
{% endfor %}
</div>
{% endif %}
@@ -0,0 +1,15 @@
+{#-
+ This file was automatically generated - do not edit
+-#}
+{% import "partials/language.html" as lang with context %}
+{% 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>
@@ -0,0 +1,13 @@
+{#-
+ 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="{{ file }}" class="md-content__button md-icon">
+ {{ lang.t("meta.source") }}
+ {% include ".icons/" ~ config.theme.icon.repo ~ ".svg" %}
+</a>
@@ -4,24 +4,11 @@
{% import "partials/language.html" as lang with context %}
-{% set platform = config.extra.repo_icon or config.repo_url %}
-{% if "github" in platform %}
- {% set repo_type = "github" %}
-{% elif "gitlab" in platform %}
- {% set repo_type = "gitlab" %}
-{% elif "bitbucket" in platform %}
- {% set repo_type = "bitbucket" %}
-{% else %}
- {% set repo_type = "" %}
-{% endif %}
-<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source" data-md-source="{{ repo_type }}">
- {% if repo_type %}
- <div class="md-source__icon">
- <svg viewBox="0 0 24 24" width="24" height="24">
- <use xlink:href="#__{{ repo_type }}" width="24" height="24"></use>
- </svg>
- </div>
- {% endif %}
+<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source">
+ <div class="md-source__icon md-icon">
+ {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
+ {% include ".icons/" ~ icon ~ ".svg" %}
+ </div>
<div class="md-source__repository">
{{ config.repo_name }}
</div>
@@ -5,7 +5,7 @@
{% if page.ancestors | length > 0 %}
{% set class = "md-tabs md-tabs--active" %}
{% endif %}
-<nav class="{{ class }}" data-md-component="tabs">
+<nav class="{{ class }}" aria-label="{{ lang.t('tabs.title') }}" data-md-component="tabs">
<div class="md-tabs__inner md-grid">
<ul class="md-tabs__list">
{% for nav_item in nav %}
@@ -4,35 +4,22 @@
{% import "partials/language.html" as lang with context %}
-<nav class="md-nav md-nav--secondary">
+<nav class="md-nav md-nav--secondary" aria-label="{{ lang.t('toc.title') }}">
{% endif %}
{% if toc | first is defined %}
<label class="md-nav__title" for="__toc">
+ <span class="md-nav__icon md-icon">
+ {% include ".icons/material/arrow-left.svg" %}
+ </span>
{{ lang.t("toc.title") }}
</label>
<ul class="md-nav__list" data-md-scrollfix>
{% for toc_item in toc %}
{% include "partials/toc-item.html" %}
{% endfor %}
- {% if page.meta.source and page.meta.source | length > 0 %}
- <li class="md-nav__item">
- <a href="#__source" class="md-nav__link md-nav__link--active">
- {{ lang.t("meta.source") }}
- </a>
- </li>
- {% endif %}
- {% set disqus = config.extra.disqus %}
- {% if page and page.meta and page.meta.disqus is string %}
- {% set disqus = page.meta.disqus %}
- {% endif %}
- {% if not page.is_homepage and disqus %}
- <li class="md-nav__item">
- <a href="#__comments" class="md-nav__link md-nav__link--active">
- {{ lang.t("meta.comments") }}
- </a>
- </li>
- {% endif %}
</ul>
{% endif %}
</nav>
从 3.x 升级到 4.x¶
¥Upgrading from 3.x to 4.x¶
什么是新的？¶
¥What's new?¶
MkDocs 4 的 Material 修复了中文系统上的布局错误。该修复包括强制将基础字体大小从10px更改为20px ，这意味着所有rem值都需要更新。在主题中， px到rem的计算现在封装在一个名为px2rem的新函数中，该函数是 SASS 代码库的一部分。
¥Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix includes a mandatory change of the base font-size from 10px to 20px which means all rem values needed to be updated. Within the theme, px to rem calculation is now encapsulated in a new function called px2rem which is part of the SASS code base.
如果您将 Material for MkDocs 与基于rem值的自定义 CSS 结合使用，请注意，这些值现在必须除以 2。现在， 1.0rem不再映射到10px ，而是20px 。要了解有关该问题及其影响的更多信息，请参阅#911，其中发现并修复了该问题。
¥If you use Material for MkDocs with custom CSS that is based on rem values, note that those values must now be divided by 2. Now, 1.0rem doesn't map to 10px, but 20px. To learn more about the problem and implications, please refer to #911 in which the problem was discovered and fixed.
mkdocs.yml的变更¶
¥Changes to mkdocs.yml¶
没有任何。
¥None.
对*.html文件的更改¶
¥Changes to *.html files¶
没有任何。
¥None.