Skip to content

Setting up tags

Material for MkDocs adds first-class support for categorizing pages with tags, which adds the possibility to group related pages and make them discoverable via search and a dedicated tags index. If your documentation is large, tags can help to discover relevant information faster.

Configuration

Built-in tags

Source · Plugin · Experimental · Insiders only

The built-in tags plugin adds the ability to categorize any page with tags as part of the front matter of the page. In order to add support for tags, add the following lines to mkdocs.yml:

plugins:
  - tags

Note that no third-party plugin1 needs to be installed, as Material for MkDocs provides its own implementation to allow for a meaningful integration. The following options are available:

tags_file

Default: none – This option specifies which file should be used to render the tags index. See the section on adding a tags index for more information. If this option is specified, tags will become clickable, pointing to the corresponding section in the tags index:

plugins:
  - tags:
      tags_file: tags.md

The page holding the tags index can be linked anywhere in the nav section of mkdocs.yml. Note, however, that this options is not required. If this option is not specified, tags are still rendered and searchable, but without a tags index.

Usage

Adding tags

Source · Metadata

If both, the built-in tags plugin and Metadata extension are enabled, tags can be added for any page as part of the front matter, e.g. to add the tags insiders and brand new to this page, add:

---
tags:
  - insiders
  - brand new
---

...

The page will now render with those tags above the main headline and within the search preview, which now allows to find pages by tags, as shown in the following screenshots:

Tags

Tag search

Adding a tags index

The built-in tags plugin allows to define a file to render a tags index, which can be any page that is part of the nav section. To add a tags index, create a page, e.g. tags.md:

# Tags

Following is a list of relevant tags:

[TAGS]

The [TAGS] marker specifies the position of the tags index, i.e. it is replaced with the actual tags index when the page is rendered. You can include arbitrary content before and after the marker:

Tags index

Hiding the tags

Source · Metadata

While the tags are rendered above the main headline, sometimes, it might be desirable to hide them for a specific page, which can be achieved by using the Metadata extension:

---
hide:
  - tags
---

# Document title
...

  1. The built-in tags plugin has no affiliation with mkdocs-plugin-tags, another option to add tag support to MkDocs, which has several caveats: it requires a title set in the front matter for every page for which tags should be added, doesn't support all syntactic flavors of front matter, doesn't integrate tags in search and doesn't render tags on pages without additional effort. The built-in tags plugin supports all of these features out-of-the-box.