[go: up one dir, main page]
Skip to content

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 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, 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, 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

8.2.0 tags – built-in

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

enabled

9.1.7 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

The following settings are available for tags:

tags

9.3.2 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 is enabled.

tags_file

8.2.0

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

tags_slugify

insiders-4.25.0 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

insiders-4.25.0 -

Use this setting to change the separator that is passed to the slugification function set as part of 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

insiders-4.48.0 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:

tags_hierarchy

insiders-4.48.0 false

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

insiders-4.48.0 /

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

tags_sort_by

insiders-4.26.2 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.

tags_sort_reverse

insiders-4.26.2 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

insiders-4.48.0 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

insiders-4.48.0 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

tags_allowed

insiders-4.25.0

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 metadata property.

Listings

The following settings are available for listings:

listings

insiders-4.48.0 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 is enabled.

listings_map

insiders-4.48.0

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.

listings_sort_by

insiders-4.39.0 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.

listings_sort_reverse

insiders-4.39.0 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

insiders-4.48.0 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.

listings_tags_sort_reverse

insiders-4.48.0 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

listings_directive

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

listings_toc

insiders-4.48.0 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

The following settings are available for shadow tags:

shadow

insiders-4.48.0 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

shadow_on_serve

insiders-4.48.0 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

shadow_tags

insiders-4.48.0

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

plugins:
  - tags:
      shadow_tags:
        - Draft
        - Internal

shadow_tags_prefix

insiders-4.48.0

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

shadow_tags_suffix

insiders-4.48.0

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:

export

insiders-4.49.0 true

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

plugins:
  - tags:
      export: true

export_file

insiders-4.49.0 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.

export_only

insiders-4.49.0 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 and listings settings.

Usage

Metadata

The following properties are available:

tags

8.2.0

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

scope

insiders-4.48.0 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 -->

shadow

insiders-4.49.0

This setting specifies whether the listing should include shadow tags, which allows to override the global 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 -->

toc

insiders-4.48.0 listings_toc

This setting specifies whether the listing should render tags inside the table of contents, allowing to override the global 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 -->

include

insiders-4.48.0

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.

exclude

insiders-4.48.0

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.