MkDocs Meta Manager

1.1.0 · active · verified Sat Apr 11

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.

Warnings

breaking 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`.
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]`.
gotcha 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.
Fix: Ensure your meta files are named `.meta.yml` or explicitly set `meta_manager: meta_filename: your_custom_name.yml` in your `mkdocs.yml`.
breaking 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.
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.
gotcha 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.
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.

Install

pip install mkdocs-meta-manager Install plugin

Imports

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.

Quickstart

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

view raw JSON →