参考¶

¥Reference¶

MkDocs 的 Material 功能丰富，让技术写作变得轻松愉悦。本文档将讲解如何设置页面，并展示所有可在 Markdown 文件中直接使用的范例。

¥Material for MkDocs is packed with many great features that make technical writing a joyful activity. This section of the documentation explains how to set up a page, and showcases all available specimen that can be used directly from within Markdown files.

配置¶

¥Configuration¶

用法¶

¥Usage¶

设置页面`title`¶

¥Setting the page title¶

每个页面都有一个指定的标题，用于导航侧边栏、社交卡片和其他地方。虽然 MkDocs 尝试通过四个步骤自动确定页面标题，但也可以使用前置title属性明确设置标题：

¥Each page has a designated title, which is used in the navigation sidebar, for social cards and in other places. While MkDocs attempts to automatically determine the title of a page in a four step process, the title can also be explicitly set with the front matter title property:

---
title: Lorem ipsum dolor sit amet # (1)!
---

# Page title
...

这行代码将生成页面的 HTML 文档head中的标题设置为给定值。注意，通过site_name设置的站点标题后面加了一个短划线。
¥This line sets the title inside the HTML document's head for the generated page to the given value. Note that the site title, which is set via site_name, is appended with a dash.

设置页面`description`¶

¥Setting the page description¶

Markdown 文件可以包含添加到页面meta标记的描述，也可用于社交卡片。如果作者没有明确定义 Markdown 文件的描述，最好在mkdocs.yml中设置site_description作为后备值：

¥A Markdown file can include a description that is added to the meta tags of a page, and is also used for social cards. It's a good idea to set a site_description in mkdocs.yml as a fallback value if the author does not explicitly define a description for a Markdown file:

---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
---

# Page title
...

此行将包含当前页面文档head内的描述的meta标记设置为提供的值。
¥This line sets the meta tag containing the description inside the document head for the current page to the provided value.

设置页面`icon`¶

¥Setting the page icon¶

9.2.0

¥9.2.0

您可以为每个页面分配一个图标，该图标随后会呈现为导航侧边栏的一部分，如果启用，还会呈现为导航选项卡的一部分。使用 front matter 的icon属性来引用图标，并在 Markdown 文件顶部添加以下几行：

¥An icon can be assigned to each page, which is then rendered as part of the navigation sidebar, as well as navigation tabs, if enabled. Use the front matter icon property to reference an icon, adding the following lines at the top of a Markdown file:

---
icon: material/emoticon-happy # (1)!
---

# Page title
...

输入几个关键字，使用我们的图标搜索找到完美的图标，然后单击短代码将其复制到剪贴板：

设置页面`status`¶

¥Setting the page status¶

9.2.0 。拉链

¥Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

可以为每个页面分配一个状态，然后将其显示为导航侧边栏的一部分。首先，通过在mkdocs.yml中添加以下内容，将状态标识符与描述关联起来：

extra:
  status:
    <identifier>: <description> # (1)!

标识符只能包含字母数字字符以及短划线和下划线。例如，如果您的状态Recently added ，则可以将new设置为标识符：
```
extra:
  status:
    new: Recently added
```
```
extra:
  status:
    new: Recently added
```
extra: status: new: Recently added额外：状态：新：最近添加

现在可以使用 front matter status属性设置页面状态。例如，你可以在 Markdown 文件顶部使用以下几行将页面标记为new页面：

---
status: new
---

# Page title
...

以下状态标识符已经定义：

¥9.2.0 .zip

- new
¥ – new
– deprecated
¥ – deprecated

您可以通过这种方式定义自定义页面状态，但如果您希望它拥有默认图标以外的其他图标，则还需要在extra.css中进行配置。我们提供了一个自定义页面状态的示例，可帮助您入门。

¥A status can be assigned to each page, which is then displayed as part of the navigation sidebar. First, associate a status identifier with a description by adding the following to mkdocs.yml:

设置页面`subtitle`¶

¥Setting the page subtitle¶

9.6.0

¥The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a status Recently added, you can set new as an identifier:

每个页面都可以定义一个副标题，然后通过使用前置subtitle属性，并添加以下几行，将其作为导航侧边栏的一部分呈现在标题下方：

¥The page status can now be set with the front matter status property. For example, you can mark a page as new with the following lines at the top of a Markdown file:

---
subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
---

# Page title
...

设置页面`template`¶

¥Setting the page template¶

如果您正在使用主题扩展并在overrides目录中创建了新的页面模板，则可以为特定页面启用它。在 Markdown 文件的顶部添加以下几行：

¥The following status identifiers are already defined:

---
template: custom.html
---

# Page title
...

How to set a page template for an entire folder?

借助内置元插件，您可以为整个部分和所有嵌套页面设置自定义模板，方法是在相应文件夹中创建包含以下内容的.meta.yml文件：

¥You can define a custom page status this way but if you want it to have an icon other than the default one you need to also configure that in your extra.css. We have an example for a custom page status to get you started.

template: custom.html

定制¶

¥Customization¶

在模板中使用元数据¶

¥Using metadata in templates¶

在所有页面上¶

¥ on all pages¶

为了向您的文档添加自定义meta标记，您可以扩展主题并覆盖 extrahead 块，例如通过robots属性为搜索引擎添加索引策略：

¥9.6.0

{% extends "base.html" %}

{% block extrahead %}
  <meta name="robots" content="noindex, nofollow" />
{% endblock %}

在单个页面上¶

¥ on a single page¶

如果您想在单个页面上设置meta标记，或者想要为不同的页面设置不同的值，您可以在模板覆盖中使用page.meta对象，例如：

¥Each page can define a subtitle, which is then rendered below the title as part of the navigation sidebar by using the front matter subtitle property, and adding the following lines:

{% extends "base.html" %}

{% block extrahead %}
  {% if page and page.meta and page.meta.robots %}
    <meta name="robots" content="{{ page.meta.robots }}" />
  {% else %}
    <meta name="robots" content="index, follow" />
  {% endif %}
{% endblock %}

现在，您可以像使用标题和描述一样使用robots来设置值。请注意，在本例中，模板定义了一个else分支，如果未指定，则会设置默认值。

¥If you're using theme extension and created a new page template in the overrides directory, you can enable it for a specific page. Add the following lines at the top of a Markdown file:

参考¶

配置¶

用法¶

设置页面title¶

设置页面description¶

设置页面icon¶

设置页面status¶

设置页面subtitle¶

设置页面template¶

定制¶