MkDocs Auto Tag Plugin

0.1.3 · active · verified Sat Apr 11

The mkdocs-auto-tag-plugin is an MkDocs plugin designed to automatically add tags to documentation pages based on their file path or name. It uses glob patterns and regular expressions to define rules for tag assignment. The current version is 0.1.3, released in August 2023, and it is actively maintained with a focus on MkDocs 1.x compatibility.

Warnings

breaking MkDocs 2.0 is being rewritten without a plugin system, which will make this plugin and other existing MkDocs 1.x plugins incompatible. Material for MkDocs has already limited its version range to '<2' to avoid breakage. Plan for alternative solutions or remain on MkDocs 1.x if relying on plugins.
Fix: Remain on MkDocs 1.x or identify an alternative tagging solution compatible with MkDocs 2.0 when it is released.
gotcha There is another MkDocs plugin named `mkdocs-auto-tags` (note the plural 'tags' and hyphen) by a different author, which has similar functionality but potentially different configuration and behavior. Ensure you are installing and configuring the correct `mkdocs-auto-tag-plugin` as intended.
Fix: Double-check the PyPI name (`mkdocs-auto-tag-plugin`) and refer to its specific documentation for configuration.
gotcha The order of plugins in your `mkdocs.yml` can be critical. If you are using `mkdocs-auto-tag-plugin` in conjunction with other tag-related plugins (like the built-in `tags` plugin from Material for MkDocs), ensure `auto_tag` is placed appropriately in the plugin list, usually after any official `tags` plugin if it modifies the tag list.
Fix: Experiment with plugin order if unexpected behavior occurs. Consult documentation for specific plugin interactions.
gotcha This plugin appends tags to pages based on its rules without overwriting any tags already defined in the page's front matter. If a page explicitly defines tags, the automatically generated tags will be added alongside them.
Fix: Be aware that existing front matter tags will persist and auto-tags will be additive. Adjust front matter tags or plugin rules accordingly if you require specific tag sets.

Install

pip install mkdocs-auto-tag-plugin Install with pip

Imports

auto_tag
```
plugins:
  - auto_tag:
```
MkDocs plugins are typically configured in mkdocs.yml, not directly imported in Python code.

Quickstart

To enable the plugin, add `auto_tag` to your `plugins` section in `mkdocs.yml` and define tagging rules using `pattern` (glob or regex) and `tags`. This example tags files ending with '_API_Reference.md' as 'API-Reference' and files within 'dev_guide/' as 'Development-Guide'.

plugins:
  - auto_tag:
      rules:
        - pattern: '.*_API_Reference\.md$'
          tags:
            - 'API-Reference'
        - pattern: 'dev_guide/.*'
          tags:
            - 'Development-Guide'
        - pattern: 'docs/README.md'
          tags:
            - 'Home'

view raw JSON →