Skip to content

参考

MkDocs的材料中包含许多出色的功能，使得技术写作成为一种愉快的活动。本文档的这一部分将解释如何设置页面，并展示可以直接从Markdown文件中使用的所有可用示例。

配置

内置的typeset插件

仅限赞助商 · insiders-4.27.0 · 插件 · 实验性

内置的typeset插件在导航和目录中__保留HTML格式__。这意味着现在，代码块、图标、表情符号和其他内联格式将被保留，从而实现更丰富的编辑体验。将以下行添加到mkdocs.yml文件中：

plugins:
  - typeset

要查看演示，请看一下本页面的目录：代码块和图标都保留在章节标题中；甚至支持内联代码块的高亮显示 🎉

内置的meta插件

仅限赞助商 · insiders-4.21.0 · 插件 · 实验性

内置的meta插件允许__为每个文件夹设置前置元数据__，这对于确保文件夹中的所有页面使用特定模板或标签非常方便。将以下行添加到mkdocs.yml文件中：

plugins:
  - meta

如果您需要能够使用和不使用内部人员构建文档，请参考内置插件部分，了解共享配置如何帮助实现此目的。

以下配置选项可用：

meta_file

默认值：**/.meta.yml – 此选项指定插件应查找的元数据文件的名称。默认设置假定元数据文件名为.meta.yml：

plugins:
  - meta:
      meta_file: '**/.meta.yml' # (1)!
  1. 请注意，强烈建议在元数据文件前加上.，否则它们将包含在构建输出中。

用法

设置页面的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.0b0 · 实验性

可以为每个页面分配一个图标，该图标将作为导航侧边栏的一部分进行呈现，以及导航选项卡（如果启用）。使用前置元数据icon属性引用一个图标，将以下行添加到Markdown文件的顶部：

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

# 文档标题
...

  1. 输入一些关键字，使用我们的图标搜索找到完美的图标，并单击简码将其复制到剪贴板：

    设置页面的status

    9.2.0b0 · 实验性

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

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

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

      extra:
  status:
    new: Recently added

    现在可以使用前置元数据status属性设置页面状态。例如，可以使用以下行将页面标记为new，添加到Markdown文件的顶部：

    ---
status: new
---

# 文档标题
...

    当前支持以下状态标识符：

    • – new
    • – deprecated

    设置页面的subtitle

    仅限赞助商 · insiders-4.25.0 · 实验性

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

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

# 文档标题
...

    设置页面的template

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

    ---
template: custom.html
---

# 文档标题
...
    如何为整个文件夹设置页面模板?

    使用内置的meta插件的帮助，您可以通过在相应文件夹中创建一个.meta.yml文件，并使用以下内容为整个部分和所有嵌套页面设置自定义模板：

    template: custom.html

    自定义

    在模板中使用元数据

    在所有页面上

    为了向文档添加自定义的meta标签，您可以扩展主题并覆盖extrahead块，例如通过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分支，如果没有给出默认值，则会设置默认值。