{"id":4113,"library":"mkdocs-auto-tag-plugin","title":"MkDocs Auto Tag Plugin","description":"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.","status":"active","version":"0.1.3","language":"en","source_language":"en","source_url":"https://github.com/six-two/mkdocs-auto-tag-plugin","tags":["mkdocs","documentation","tags","plugin","automation"],"install":[{"cmd":"pip install mkdocs-auto-tag-plugin","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"mkdocs","optional":false},{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"MkDocs plugins are typically configured in mkdocs.yml, not directly imported in Python code.","symbol":"auto_tag","correct":"plugins:\n  - auto_tag:"}],"quickstart":{"code":"plugins:\n  - auto_tag:\n      rules:\n        - pattern: '.*_API_Reference\\.md$'\n          tags:\n            - 'API-Reference'\n        - pattern: 'dev_guide/.*'\n          tags:\n            - 'Development-Guide'\n        - pattern: 'docs/README.md'\n          tags:\n            - 'Home'\n","lang":"yaml","description":"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'."},"warnings":[{"fix":"Remain on MkDocs 1.x or identify an alternative tagging solution compatible with MkDocs 2.0 when it is released.","message":"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.","severity":"breaking","affected_versions":"MkDocs >= 2.0"},{"fix":"Double-check the PyPI name (`mkdocs-auto-tag-plugin`) and refer to its specific documentation for configuration.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Experiment with plugin order if unexpected behavior occurs. Consult documentation for specific plugin interactions.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}