{"id":4119,"library":"mkdocs-meta-manager","title":"MkDocs Meta Manager","description":"mkdocs-meta-manager is an MkDocs plugin that facilitates the management of meta tags across folders and files within your documentation site. It allows for hierarchical merging of metadata from `.meta.yml` files, simplifying the application of front matter to multiple pages. The current version is 1.1.0, and it has a moderate release cadence driven by feature enhancements and bug fixes.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/timmeinerzhagen/mkdocs-meta-manager","tags":["mkdocs","plugin","documentation","metadata","frontmatter","yaml"],"install":[{"cmd":"pip install mkdocs-meta-manager","lang":"bash","label":"Install plugin"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"mkdocs","optional":false},{"reason":"Requires Python 3.4 or higher.","package":"python","optional":false}],"imports":[{"note":"MkDocs plugins are enabled in mkdocs.yml, not imported via Python code. 'meta-manager' is the plugin name to use in the configuration.","symbol":"meta-manager","correct":"plugins:\n  - meta-manager"}],"quickstart":{"code":"plugins:\n  - search\n  - meta-manager:\n      meta_filename: .meta.yml # Default value, can be customized\n      merge_entries: [tags, authors] # Example of merging tags and authors\n\n# In your docs directory, create a .meta.yml file, e.g.:\n# docs/chapter1/.meta.yml\n# tags:\n#   - Chapter 1\n# authors:\n#   - John Doe","lang":"yaml","description":"To quickly enable the plugin, add `meta-manager` to your `plugins` section in `mkdocs.yml`. You can optionally configure the `meta_filename` and specify `merge_entries` (e.g., `tags`, `authors`) to define which metadata keys should be merged hierarchically. Create `.meta.yml` files in your documentation folders to define metadata that will apply to all Markdown files in that folder and its subfolders."},"warnings":[{"fix":"Change `merge_tags: true` to `merge_entries: [tags]` in your `mkdocs.yml` to maintain the previous functionality. If you were merging other entries, add them to the list, e.g., `merge_entries: [tags, authors]`.","message":"In version 1.0.0, the configuration option `merge_tags` was renamed and generalized to `merge_entries`. Projects upgrading from versions prior to 1.0.0 will need to update their `mkdocs.yml`.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure your meta files are named `.meta.yml` or explicitly set `meta_manager:\n    meta_filename: your_custom_name.yml` in your `mkdocs.yml`.","message":"The plugin looks for meta files named `.meta.yml` by default. If your meta files have a different name, you must configure the `meta_filename` option in `mkdocs.yml`, otherwise, your metadata will not be applied.","severity":"gotcha","affected_versions":"All"},{"fix":"Pin your MkDocs version to `<2` in your `requirements.txt` (e.g., `mkdocs>=1.5.1,<2`) and monitor the `mkdocs-meta-manager` repository for updates and compatibility announcements regarding MkDocs 2.0.","message":"The upcoming MkDocs 2.0 is expected to be a complete rewrite, fundamentally changing the plugin system and potentially breaking all existing plugins, including `mkdocs-meta-manager`. The `mkdocs-material` team has explicitly stated they will not support MkDocs 2.0, indicating widespread incompatibility.","severity":"breaking","affected_versions":"Future MkDocs 2.0 and beyond"},{"fix":"Upgrade to `mkdocs-meta-manager` version 1.1.0 or newer to benefit from the fix for Windows path compatibility. Ensure consistent path separators in your project structure.","message":"Prior to version 1.1.0, there was a known issue with path separators, particularly affecting Windows compatibility. This could lead to meta files not being correctly discovered or applied.","severity":"gotcha","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}