参考

Material for MkDocs 包含了许多很棒的特性，使技术写作成为一种快乐的活动。 文档的这一部分解释了如何设置页面，并展示了所有可以直接从 Markdown 文件中使用的可用样本。

配置

内置元插件

Sponsors only · insiders-4.21.0 · Plugin · Experimental

内置的元插件允许 设置每个文件夹的前面内容，这是特别方便的，以确保文件夹中的所有页面使用特定的模板或标签。 将以下代码行添加到 mkdocs.yml:

plugins:
  - meta

如果你需要使用Insiders和不使用内置插件构建文档，请参考内置插件一节，了解共享配置如何帮助实现这一目标。

有以下配置选项:

meta_file

默认: **/.meta.yml – 这个选项指定插件应该查找的元文件的名称。默认设置假设元文件名为.meta.yml:

plugins:
  - meta:
      meta_file: '**/.meta.yml' 

使用

设置页面标题

每个页面都有一个指定的标题，在导航侧栏中使用，用于社交卡片和其他地方。 MkDocs 尝试在四步过程中自动确定页面的标题，标题也可以显式地设置前置事项 title 属性:

---
title: Lorem ipsum dolor sit amet 
---
# Document title

设置页面描述

Markdown 文件可以包括添加到页面meta标签的描述，也可以用于社交卡片。 如果作者没有明确定义 Markdown 文件的描述，在mkdocs.yml中设置site_description 作为回退值是个好主意:

---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. 
---
# Document title

设置页面图标

Sponsors only · insiders-4.5.0 · Experimental

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 
---
# Document title

设置页面状态

Sponsors only · insiders-4.22.0 · Experimental

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

extra:
  status:
    <identifier>: <description> 

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:

---
status: new
---
# Document title

The following status identifiers are currently supported:

• – new
• – deprecated

设置页面副标题

Sponsors only · insiders-4.25.0 · Experimental

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:

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

设置页面模板

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:

---
template: custom.html
---
# Document title

How to set a page template for an entire folder?

With the help of the built-in meta plugin, you can set a custom template for an entire section and all nested pages, by creating a .meta.yml file in the corresponding folder with the following content:

template: custom.html

定制

在模板中使用元数据

在所有页面上

In order to add custom meta tags to your document, you can extend the theme and override the extrahead block, e.g. to add indexing policies for search engines via the robots property:

{% extends "base.html" %} {% block extrahead %}
<meta property="robots" content="noindex, nofollow" />
{% endblock %}

在一页纸上

If you want to set a meta tag on a single page, or want to set different values for different pages, you can use the page.meta object inside your template override, e.g.:

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

You can now use robots exactly like title and description to set values. Note that in this case, the template defines an else branch, which would set a default if none was given.