Built-in tags plugin

The tags plugin adds first-class support for categorizing pages with the use of tags, adding the possibility to group related pages and make them discoverable via search and dedicated tags indexes. If your documentation is large, tags can help to discover relevant information faster.

Objective

How it works

The plugin scans all pages for the [tags][meta.tags] metadata property and generates a tags index, which is an inverted list of tags and the pages they appear on. The tags index can be located anywhere in the [nav][mkdocs.nav], allowing for maximum flexibility when adding tags to your project.

When to use it

If you want to add one or multiple tags indexes to your project, the tags plugin is a perfect choice as it makes this process ridiculously simple. Additionally, it integrates perfectly with several of the other built-in plugins that Material-for-MkDocs offers:

Configuration

As with all built-in plugins, getting started with the tags plugin is straightforward. Just add the following lines to mkdocs.yml, and start using [tags][meta.tags] to categorize your pages:

plugins:
  - tags

The tags plugin is built into Material-for-MkDocs and doesn’t need to be installed.

General

The following settings are available:

Use this setting to enable or disable the plugin when building your project. It’s normally not necessary to specify this setting, but if you want to disable the plugin, use:

plugins:
  - tags:
      enabled: false

Tags

The following settings are available for tags:

Use this setting to enable or disable rendering of tags. The plugin still extracts tags from all pages, e.g., for exporting tags without rendering them. Rendering can be disabled with:

plugins:
  - tags:
      tags: false

This setting is automatically disabled if [export_only][config.export_only] is enabled.

!!! info “This setting is not needed in Insiders”

Insiders ships a __ground up rewrite of the tags plugin__ which is infinitely
more powerful than the current version in the community edition. It allows
for an arbitrary number of tags indexes (listings), [scoped listings],
[shadow tags], [nested tags], and much more.

Use this setting to specify the location of the tags index, which is the page used to render a list of all tags and their associated pages. If this setting 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][mkdocs.nav] section of mkdocs.yml. This setting is not required – you should only use it if you want to have a tags index.

The provided path is resolved from the [docs directory][mkdocs.docs_dir].

Use this setting to change the function for generating URL-compatible slugs from post titles. By default, the slugify function from Python Markdown Extensions is used as follows:

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

The default configuration is Unicode-aware and should produce good slugs for all languages. Of course, you can also provide a custom slugification function for more granular control.

Use this setting to change the separator that is passed to the slugification function set as part of [tags_slugify][config.tags_slugify]. While the default is a hyphen, it can be set to any string, e.g., _:

plugins:
  - tags:
      tags_slugify_separator: _

Use this setting to change the format string that is used when generating tag slugs. It is a good idea to prefix tag slugs with a string that makes them unique, the default being:

plugins:
  - tags:
      tags_slugify_format: "tag:{slug}"

The following placeholders are available:

• slug – Tag slug, slugified with [tags_slugify][config.tags_slugify]

Use this setting to enable support for tag hierarchies (nested tags, e.g., foo/bar). If you intend to create hierarchical listings of tags, you can enable this setting in mkdocs.yml with:

plugins:
  - tags:
      tags_hierarchy: true

Use this setting to change the separator that is used when creating tag hierarchies. By default, tags are separated by a forward slash /, but you can change this to any string, e.g., .:

plugins:
  - tags:
      tags_hierarchy_separator: .

Use this setting to specify a custom function for comparing tags. By default, tag comparison is case-sensitive, but you can use tag_name_casefold for case-insensitive comparison:

plugins:
  - tags:
      tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold

You can also define your own comparison function, which must return a string or number representing the tag, that is used for sorting, and reference it in [tags_sort_by][config.tags_sort_by].

Use this setting to reverse the order in which tags are sorted when comparing them. By default, tags are sorted in ascending order, but you can reverse ordering as follows:

plugins:
  - tags:
      tags_sort_reverse: true

Use this setting to change the name of the front matter property that is used by the plugin. It is normally not necessary to change this setting, but if you want to change it, you can use:

plugins:
  - tags:
      tags_name_property: tags

Use this setting to change the name of the template variable that is used by the plugin. It is normally not necessary to change this setting, but if you want to change it, you can use:

plugins:
  - tags:
      tags_name_variable: tags

The plugin allows to check tags against a predefined list, in order to catch typos or make sure that tags are not arbitrarily added. Specify the tags you want to allow with:

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

The plugin stops the build if a page references a tag that is not part of this list. Pages can be assigned to tags by using the [tags][meta.tags] metadata property.

Listings

The following settings are available for listings:

Use this setting to enable or disable listings. It is normally not necessary to change this setting, as listings are created entirely by inline comments, but you can disable them if necessary with:

plugins:
  - tags:
      listings: false

This setting is automatically disabled if [export_only][config.export_only] is enabled.

Use this define listing configurations that you can then reference in listings with a custom identifier. Sharing configurations is a good idea, especially when you have many tag listings:

plugins:
  - tags:
      listings_map:
        custom-id:
          scope: true
          exclude: Internal

Then, just reference the listing identifier:

<!-- material/tags custom-id -->

See the listings section for a list of all available settings.

Use this setting to specify a custom function for comparing listing items. By default, items are ordered by their titles, but you can change the sorting criterion with the following configuration:

=== “Sort by item title”

``` yaml
plugins:
  - tags:
      listings_sort_by: !!python/name:material.plugins.tags.item_title
```

=== “Sort by item URL”

``` yaml
plugins:
  - tags:
      listings_sort_by: !!python/name:material.plugins.tags.item_url
```

You can also define your own comparison function, which must return a string or number representing the item, that is used for sorting, and reference it in [listings_sort_by][config.listings_sort_by].

Use this setting to reverse the order in which items are sorted when comparing them. By default, items are sorted in ascending order, but you can reverse ordering as follows:

plugins:
  - tags:
      listings_sort_reverse: true

Use this setting to specify a custom function for comparing tags in listings. By default, tag comparison is case-sensitive, but you can use tag_name_casefold for case-insensitivity:

plugins:
  - tags:
      tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold

You can also define your own comparison function, which must return a string or number representing the tag, that is used for sorting, and reference it in [tags_sort_by][config.tags_sort_by].

Use this setting to reverse the order in which tags are sorted when comparing them. By default, tags are sorted in ascending order, but you can reverse ordering as follows:

plugins:
  - tags:
      tags_sort_reverse: true

Use this setting to change the name of the directive the plugin will look for when processing pages. If you want to use a shorter directive than material/tags, you could use:

plugins:
  - tags:
      listings_directive: $tags

Using this setting, listings must now be referenced as such:

<!-- $tags { include: [foo, bar] } -->

Use this setting to enable or disable tags showing up in the table of contents. If you don’t want tags to show up in the table of contents, you can disable this behavior with:

plugins:
  - tags:
      listings_toc: false

Shadow tags

The following settings are available for shadow tags:

Use this setting to specify whether the plugin should include shadow tags on pages and in listings when building your project, which might be useful for deploy previews:

=== “Show shadow tags”

``` yaml
plugins:
  - tags:
      shadow: true
```

=== “Hide shadow tags”

``` yaml
plugins:
  - tags:
      shadow: false
```

Use this setting to control whether the plugin should include shadow tags on pages and in listings when previewing your site. If you don’t wish to include them when previewing, use:

plugins:
  - tags:
      shadow_on_serve: false

The plugin allows to specify a predefined list of shadow tags which can be included and excluded from builds by using the [shadow][config.shadow] setting. Shadow tags must be specified as a list:

plugins:
  - tags:
      shadow_tags:
        - Draft
        - Internal

Use this setting to specify a string that is checked as a prefix for each tag. If the tag starts with this string, the tag is marked as a shadow tag. A common practice is to use _ as a prefix:

plugins:
  - tags:
      shadow_tags_prefix: _

Use this setting to specify a string that is checked as a suffix for each tag. If the tag ends with this string, the tag is marked as a shadow tag. One option can be to use Internal as a suffix:

plugins:
  - tags:
      shadow_tags_suffix: Internal

Export

The following settings are available for exporting:

Use this setting to control whether the plugin creates a tags.json file inside your [site directory][mkdocs.site_dir], which can then be consumed by other plugins and projects:

plugins:
  - tags:
      export: true

Use this setting to change the path of the file where the exported tags are stored. It’s normally not necessary to change this setting, but if you need to, use:

plugins:
  - tags:
      export_file: tags.json

The provided path is resolved from the [site directory][mkdocs.site_dir].

This setting is solely provided for convenience to disable the rendering of tags and listings with a single setting (e.g. by using an environment variable), while keeping the export functionality:

plugins:
  - tags:
      export_only: true

This will automatically disable the [tags][config.tags] and [listings][config.listings] settings.

Usage

Metadata

The following properties are available:

Use this property to associate a page with one or more tags, making the page appear in the generated tags index. Tags are defined as a list of strings (whitespaces are allowed):

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

# Page title
...

If you want to prevent accidental typos when assigning tags to pages, you can set a predefined list of allowed tags in mkdocs.yml by using the [tags_allowed][config.tags_allowed] setting.

Listing configuration

The listings configuration controls which tags are included in or excluded from a listing and whether a listing only includes pages in the current scope. Furthermore, listings can override some values from the global configuration.

The following settings are available:

This setting specifies whether the listing should only consider pages that are within the current subsection of the documentation of the page the listing is embedded in:

=== “Inline usage”

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

=== “Usage in mkdocs.yml”

``` yaml
plugins:
  - tags:
      listings_map:
        custom-id:
          scope: false
```

Then, just reference the listing identifier:

``` html
<!-- material/tags custom-id -->
```

This setting specifies whether the listing should include shadow tags, which allows to override the global [shadow][config.shadow] setting on a per-listing basis:

=== “Inline usage”

``` html
<!-- material/tags { shadow: true } -->
```

=== “Usage in mkdocs.yml”

``` yaml
plugins:
  - tags:
      listings_map:
        custom-id:
          shadow: true
```

Then, just reference the listing identifier:

``` html
<!-- material/tags custom-id -->
```

This setting specifies whether the listing should render tags inside the table of contents, allowing to override the global [listings_toc][config.listings_toc] setting on a per-listing basis:

=== “Inline usage”

``` html
<!-- material/tags { toc: true } -->
```

=== “Usage in mkdocs.yml”

``` yaml
plugins:
  - tags:
      listings_map:
        custom-id:
          toc: true
```

Then, just reference the listing identifier:

``` html
<!-- material/tags custom-id -->
```

Use this setting to specify which tags should be included in the listing. Each page that features a tag that is part of this setting, is listed under the respective tag:

=== “Inline usage”

``` html
<!-- material/tags { include: [foo, bar] } -->
```

=== “Usage in mkdocs.yml”

``` yaml
plugins:
  - tags:
      listings_map:
        custom-id:
          include:
            - foo
            - bar
```

Then, just reference the listing identifier:

``` html
<!-- material/tags custom-id -->
```

If this setting is left empty, all tags and pages are included.

Use this setting to specify which tags should be excluded from the listing. Each page that features a tag that is part of this setting, is excluded from the listing entirely:

=== “Inline usage”

``` html
<!-- material/tags { exclude: [foo, bar] } -->
```

=== “Usage in mkdocs.yml”

``` yaml
plugins:
  - tags:
      listings_map:
        custom-id:
          exclude:
            - foo
            - bar
```

Then, just reference the listing identifier:

``` html
<!-- material/tags custom-id -->
```

If this setting is left empty, no tags or pages are excluded.