Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 33.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.1s · import 0.000s · 34MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
meta-manager
✓ plugins:
- meta-manager
MkDocs plugins are enabled in mkdocs.yml, not imported via Python code. 'meta-manager' is the plugin name to use in the configuration.
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.
plugins:
- search
- meta-manager:
meta_filename: .meta.yml # Default value, can be customized
merge_entries: [tags, authors] # Example of merging tags and authors
# In your docs directory, create a .meta.yml file, e.g.:
# docs/chapter1/.meta.yml
# tags:
# - Chapter 1
# authors:
# - John Doe
Debug
Known issues
breakingIn 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`.fixChange `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]`.
affects: <1.0.0
gotchaThe 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.fixEnsure your meta files are named `.meta.yml` or explicitly set `meta_manager:
meta_filename: your_custom_name.yml` in your `mkdocs.yml`. affects: All
breakingThe 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.fixPin 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.
affects: Future MkDocs 2.0 and beyond
gotchaPrior 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.fixUpgrade 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.
affects: <1.1.0
Upgrade
Version history
1.1.0latest on PyPI · released Jan 20, 2025
Audit
Dependencies
mkdocsrequiredThis is an MkDocs plugin and requires MkDocs to function.
pythonrequiredRequires Python 3.4 or higher.