设置标签¶

MkDocs 的 Material 主题为使用标签对页面进行分类提供了优质支持，这使得将相关页面分组并通过搜索和专用的标签索引进行发现成为可能。如果您的文档很庞大，标签可以帮助更快地发现相关信息。

配置¶

内置标签插件¶

8.2.0

内置标签插件增加了将任何页面与标签分类的能力，作为页面前置信息的一部分。为了添加对标签的支持，请在 mkdocs.yml 中添加以下行：

plugins:
  - tags

有关所有设置的列表，请参阅插件文档。

标签图标和标识符¶

8.5.0 .zip

每个标签可以与一个图标关联，该图标将被渲染在标签内。在为标签分配图标之前，请通过在 mkdocs.yml 中添加以下内容将每个标签与唯一标识符关联：

extra:
  tags:
    <tag>: <identifier> # (1)!

标识符只能包含字母数字字符，以及短横线和下划线。例如，如果您有一个标签 Compatibility，您可以将 compat 设置为标识符：
```
extra:
  tags:
    Compatibility: compat
```
标识符可以在标签之间重复使用。未明确关联的标签将使用默认标签图标，即

接下来，每个标识符可以与一个图标关联，甚至是一个自定义图标，通过在 mkdocs.yml 的 theme.icon 配置设置下添加以下行：

标签图标标签默认图标

theme:
  icon:
    tag:
      <identifier>: <icon> # (1)!

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

theme:
  icon:
    tag:
      default: <icon>

展开以检查示例

theme:
  icon:
    tag:
      html: fontawesome/brands/html5
      js: fontawesome/brands/js
      css:  fontawesome/brands/css3
extra:
  tags:
    HTML5: html
    JavaScript: js
    CSS: css

使用¶

添加标签¶

8.2.0 .zip

当内置标签插件启用时，可以通过文档的前置信息 tags 属性添加标签。在 Markdown 文件的顶部添加以下行：

---
tags:
  - HTML5
  - JavaScript
  - CSS
---

...

页面现在将在主标题上方和搜索预览中渲染这些标签，这样就可以通过标签 查找页面。

如何为整个文件夹设置标签？

借助内置元数据插件，您可以确保为整个部分及所有嵌套页面设置标签，通过在相应文件夹中创建一个 .meta.yml 文件，内容如下：

tags:
  - HTML5
  - JavaScript
  - CSS

在 .meta.yml 中设置的标签与为页面定义的标签合并并去重，这意味着您可以在 .meta.yml 中定义公共标签，然后为每个页面添加特定标签。.meta.yml 中的标签将被附加。

添加标签索引¶

8.2.0 .zip

内置标签插件允许定义一个文件来渲染标签索引，该文件可以是 nav 部分的一部分的任何页面。要添加标签索引，请创建一个页面，例如 tags.md：

# 标签

以下是相关标签的列表：

<!-- material/tags -->

标签标记指定标签索引的位置，即在页面渲染时将其替换为实际的标签索引。您可以在标记前后包含任意内容：

高级功能¶

可配置的列表¶

9.6.0

列表可以在 mkdocs.yml 中配置，或直接在您在 Markdown 文档中放置标记的位置配置。一些示例：

使用 [范围列表]: 将标签索引限制为位于文档子部分同一层级的页面：
```

```
仅列出特定标签: 将标签索引限制为单个或多个选定标签，例如 Foo 和 Bar，排除所有其他标签：
```

```
排除具有特定标签的页面: 不包括标记为特定标签的页面，例如 Internal。这可以是任何标签，包括阴影标签：
```

```
在目录中启用或禁用标签: 指定目录是否在最近的标题下列出所有标签：
```

```

有关所有选项，请参见列表配置。

范围列表¶

9.7.0

如果您的文档很庞大，您可能希望考虑使用范围列表，这将仅包括与包含列表的页面在同一层级或以下的页面。只需使用：

<!-- material/tags { scope: true } -->

如果您计划使用多个范围索引，最好在 mkdocs.yml 中定义一个列表配置，然后通过其 ID 引用它：

plugins:
  - tags:
      listings_map:
        scoped:
          scope: true

您现在可以使用：

<!-- material/tags scoped -->

阴影标签¶

9.7.0

阴影标签是仅用于组织的标签，可以通过简单的标志包含或排除它们的渲染。它们可以在 shadow_tags 设置中列出：

plugins:
  - tags:
      shadow_tags:
        - Draft
        - Internal

如果文档标记为 Draft，则仅在启用 shadow 设置时渲染该标签，禁用时则排除。这是使用标签进行结构化的绝佳机会。

嵌套标签¶

9.7.0

tags_hierarchy_separator 允许创建标签层次结构，例如 Foo/Bar。嵌套标签将被渲染为父标签的子标签：

plugins:
  - tags:
      tags_hierarchy: true

隐藏页面上的标签¶

虽然标签在主标题上方渲染，但有时可能希望在特定页面上隐藏它们，这可以通过前置信息 hide 属性实现：

---
hide:
  - tags
---

# 页面标题
...