Skip to content
Return to: MkDocs-MaterialX Start Page

Built-in Tags Plugin

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.

Back to: #Advanced-Configuration

Objective⚓︎

How It Works⚓︎

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:

  •   Built-in meta plugin

    The meta plugin makes it possible to ensure that subsections of your project are annotated with [specific tags][meta.tags], so they can't be forgotten when adding pages.

    Simpler organization and management of tags in different subsections

  •   Built-in blog plugin

    The tags plugin allows to categorize posts alongside with pages in your project, to improve their discoverability and connect posts to your documentation.

    Your documentation's tag system integrates with your blog

Configuration⚓︎

Configuration

<!-- md:version 8.2.0 -->
<!-- md:plugin [tags] – built-in -->
<!-- md:flag multiple -->

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⚓︎

General

The following settings are available:

Setting config.enabled

config.enabled⚓︎

<!-- md:version 9.1.7 -->
<!-- md:default `true` -->

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⚓︎

Tags

The following settings are available for tags:

Setting config.tags

Setting config.tags⚓︎

<!-- md:version 9.3.2 -->
<!-- md:default `true` -->

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.

This Setting is Deprecated

Config.tags_file⚓︎

<!-- md:version 8.2.0 -->
<!-- md:default none -->

As of version , this setting is deprecated, as this version ships a ground up rewrite of the tags plugin which is much more powerful than the previous version. Tags listings can be used on any page now.

Depreciated

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].

Config.tags_slugify

Config.tags_slugify⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->

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.

Tags_slugify_separator

slugify_separator⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `-` -->

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: _

Tags_slugify_format

Tags_slugify_format⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `tag:{slug}` -->

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]

Config.tags_hierarchy

Conf.tags_hierarchy⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `false` -->
<!-- md:flag experimental -->

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

Tags_hierarchy_separator

hierarchy_separator⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `/` -->
<!-- md:flag experimental -->

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: .

Config.tags_sort_by

Config.tags_sort_by⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `material.plugins.tags.tag_name` -->

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].

Config.tags_sort_reverse

tags_sort_reverse⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `false` -->

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

Tags_name_property

Tags_name_property⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default [`tags`][meta.tags] -->

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

Tags_name_variable

Tags_name_variable⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `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

Config.tags_allowed

Config.tags_allowed⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default none -->

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⚓︎

Listings

The following settings are available for listings:

Setting config.listings

config.listings⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `true` -->

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.

Config.listings_map

Config.listings_map⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default none -->

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.

Config.listings_sort_by

listings_sort_by⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `material.plugins.tags.item_title` -->

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:

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

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].

Conf.listings_sort_reverse

listing_sort_reverse⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `false` -->

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

Listings_tags_sort_by

Listing_tags_sort_by⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `material.plugins.tags.tag_name` -->

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].

Listings_tags_sort_reverse

tags_sort_reverse⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `false` -->

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

Config.listings_directive

listings_directive⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `material/tags` -->

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] } -->

Config.listings_toc

Config.listings_toc⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `true` -->

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⚓︎

Shadow Tags

The following settings are available for shadow tags:

Setting config.shadow

config.shadow⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `false` -->

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:

plugins:
  - tags:
      shadow: true

plugins:
  - tags:
      shadow: false

Config.shadow_on_serve

shadow_on_serve⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `true` -->

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

Config.shadow_tags

Config.shadow_tags⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default none -->

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

Config.shadow_tags_prefix

shadow_tags_prefix⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default none -->

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: _

Config.shadow_tags_suffix

shadow_tags_suffix⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default none -->

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⚓︎

Export

The following settings are available for exporting:

Setting config.export

config.export⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `true` -->

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

Config.export_file

Config.export_file⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `tags.json` -->

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].

Config.export_only

Config.export_only⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default `false` -->

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⚓︎

Metadata

The following properties are available:

Setting meta.tags

Setting meta.tags⚓︎

<!-- md:version 8.2.0 -->
<!-- md:flag metadata -->
<!-- md:default none -->

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⚓︎

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 below:

Setting listing.scope

listing.scope⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default `false` -->

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:

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

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

Then, just reference the listing identifier:

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

Setting listing.shadow

listing.shadow⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default computed -->

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:

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

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

Then, just reference the listing identifier:

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

Setting listing.toc

Setting listing.toc⚓︎

<!-- md:version 9.7.0 -->
<!-- md:default [`listings_toc`][config.listings_toc] -->

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:

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

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

Then, just reference the listing identifier:

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

Setting listing.include

listing.include⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default none -->

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:

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

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

Then, just reference the listing identifier:

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

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

Setting listing.exclude

listing.exclude⚓︎

<!-- md:version 9.6.0 -->
<!-- md:default none -->

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:

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

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

Then, just reference the listing identifier:

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

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

Limitations⚓︎

Limitations!

  • The implementation of the tags plugin is tricky due to MkDocs architecture.

  • Notably, tag listing markers cannot appear within code blocks. For technical details, refer to #8114.

  • Installation Guide
    View Guide

    Step-by-step instructions to get MkDocs up and running.

  • Configuration (docs_dir)
    View Config

    Learn how to set up your source directory structure.

  • Deploying Your Docs
    View Guide

    How to publish your documentation to the web.

  • Documentation Layout
    View Layout

    Configure the navigation and global site structure.

  • GitHub Discussions
    Join Discussions

    Ask questions and engage with the community.

  • GitHub Issues
    View Issues

    Report bugs or request new features.

  • Site Name
    View Settings

    Define the title of your project and browser tab.

  • Theme
    View Theme

    Customise the look and feel of your documentation.

  • User Guide
    Open Guide

    The complete manual for all MkDocs features.

Back to: #Advanced-Configuration