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 plugin¶

8.2.0 · Plugin

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

The following configuration options are available:

enabled

Default: true – This option specifies whether the plugin is enabled when building your project. If you want to speed up local builds, you can use an environment variable:

plugins:
  - tags:
      enabled: !ENV [CI, false]

tags_file

Default: none – This option specifies which page 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 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 – only use it if you want a tags index page.

tags_extra_files

insiders-4.20.0 · Default: none – This option specifies additional pages, i.e. to render subsets of the tags index, in order to provide scoped tags indexes for specific sections:

plugins:
  - tags:
      tags_extra_files:
        compatibility.md:
          - compat # (1)!
        web.md:
          - html
          - js
          - css

Each page can be assigned a list of tag identifiers, which must be defined as part of extra.tags in mkdocs.yml:
```
extra:
  tags:
    Compatibility: compat
    HTML5: html
    JavaScript: js
    CSS: css
```
In this example, all pages with the tag Compatibility will be included in the additional tags index on compatibility.md, all pages defining at least one of the tags HTML5, JavaScript or CSS will be included in the additional tags index on web.md.

Note that the values listed under each tags extra file must be alphanumeric tag identifiers, not tags themselves. See #3864 for more information.

tags_slugify

insiders-4.25.0 · Default: headerid.slugify – This option specifies which function to use for generating URL-compatible slugs from tags. Python Markdown Extensions includes several Unicode-aware slug functions which are a good choice for non-ASCII languages:

UnicodeUnicode, case-sensitive

plugins:
  - tags:
      tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

plugins:
  - tags:
      tags_slugify: !!python/object/apply:pymdownx.slugs.slugify

tags_slugify_separator

insiders-4.25.0 · Default: - – This option specifies the separator which is used by the slug function. By default, a hyphen is used, but it can be changed to any string:

plugins:
  - tags:
      tags_slugify_separator: "-"

tags_compare

insiders-4.26.2 · Default: None – This option specifies which function to use when comparing tag values for sorting. If you wish to compare tags irregardless of casing, use:

plugins:
  - tags:
      tags_compare: !!python/name:material.plugins.tags.plugin.casefold

You can also define your own comparison function which must return a tag value (as a string) that is used for sorting, and reference it accordingly.

tags_compare_reverse

insiders-4.26.2 · Default: false – This option specifies whether tags are sorted in reverse order. It is mainly provided for completeness. To change direction, use:

plugins:
  - tags:
      tags_compare_reverse: true

tags_allowed

insiders-4.25.0 · Default: none – This option allows the author to define explicitly which tags are allowed to be used on pages. If this setting is omitted, the built-in tags plugin won't check tag names. Use this option to define a list of tags in order to catch typos:

plugins:
  - tags:
      tags_allowed:
        - HTML5
        - JavaScript
        - CSS

Tag icons and identifiers¶

8.5.0 · Experimental

Each tag can be associated with an icon, which is then rendered inside the tag. Before assigning icons to tags, associate each tag with a unique identifier, by adding the following to mkdocs.yml:

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

The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a tag Compatibility, you can set compat as an identifier:
```
extra:
  tags:
    Compatibility: compat
```
Identifiers can be reused between tags. Tags which are not explicitly associated will use the default tag icon which is

Next, each identifier can be associated with an icon, even a custom icon, by adding the following lines to mkdocs.yml under the theme.icon configuration setting:

Tag iconTag default icon

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

Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

theme:
  icon:
    tag:
      default: <icon>

Expand to inspect example

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

Usage¶

Adding tags¶

When the built-in tags plugin is enabled, tags can be added for a document with the front matter tags property. Add the following lines at the top of a Markdown file:

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

...

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.

How to set tags for an entire folder?

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

tags:
  - HTML5
  - JavaScript
  - CSS

The tags set in .meta.yml are merged and deduplicated with the tags defined for a page, which means you can define common tags in .meta.yml and then add specific tags for each page. The tags in .meta.yml are appended.

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:

Hiding tags on a page¶

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 with the front matter hide property:

---
hide:
  - tags
---

# Document title
...

Last update: April 14, 2023
Created: April 14, 2023