参考¶

MkDocs 的 Material 包含许多出色的功能，使技术写作变得愉快。本节文档解释了如何设置页面，并展示了可以直接在 Markdown 文件中使用的所有可用示例。

配置¶

使用¶

设置页面 title¶

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

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

# 页面标题
...

1. 这一行将生成页面的 HTML 文档 head 中的 title 设置为给定值。请注意，通过 site_name 设置的网站标题会附加一个破折号。

设置页面 description¶

Markdown 文件可以包含一个描述，该描述会添加到页面的 meta 标签中，并且也用于 社交卡片。如果作者没有显式定义 Markdown 文件的描述，建议在 mkdocs.yml 中设置 site_description 作为后备值：

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

# 页面标题
...

1. 这一行将当前页面的文档 head 中包含描述的 meta 标签设置为提供的值。

设置页面 icon¶

9.2.0

可以为每个页面分配一个图标，该图标将作为导航侧边栏的一部分呈现，如果启用的话，也会出现在 导航标签 中。使用前置数据 icon 属性引用图标，在 Markdown 文件顶部添加以下行：

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

# 页面标题
...

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

设置页面 status¶

9.2.0 .zip

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

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

1. 标识符只能包含字母数字字符、破折号和下划线。例如，如果您有一个状态 Recently added，可以将 new 设置为标识符：

   extra:
     status:
       new: Recently added
   

现在可以通过前置数据 status 属性设置页面状态。例如，您可以在 Markdown 文件顶部的以下行中将页面标记为 new：

---
status: new
---

# 页面标题
...

以下状态标识符已定义：

• – new
• – deprecated

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

设置页面 subtitle¶

9.6.0

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

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

# 页面标题
...

设置页面 template¶

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

---
template: custom.html
---

# 页面标题
...

template: custom.html

自定义¶

在模板中使用元数据¶

在所有页面上¶

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

{% extends "base.html" %}

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

在单个页面上¶

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

{% 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 %}

现在您可以像使用 title 和 description 一样使用 robots 来设置值。请注意，在这种情况下，模板定义了一个 else 分支，如果没有提供值，则会设置默认值。