Built-in meta plugin¶
The meta plugin solves the problem of setting metadata (front matter) for all pages in a folder, i.e., a subsection of your project, which is particularly useful to ensure that a certain subset of pages features specific tags, uses a custom template, or is attributed to an author.
How it works¶
The plugin scans the
docs directory for
.meta.yml files, and recursively merges the contents of those files with the metadata (front matter) of all pages that are contained in the same folder and all subfolders. For example, if you want to add the tag Example to multiple pages, use:
Now, given the following directory layout, if you store the file in the folder named
example, all pages in that folder receive the tag, while all pages outside of the folder remain unaffected:
When combining metadata, lists and dictionaries are recursively merged, which means you can append values to a list and add or set specific properties in a dictionary on arbitrary levels.
When to use it¶
While the plugin itself doesn't offer much functionality beyond adding and merging metadata, it is a perfect companion for many of the other built-in plugins that Material for MkDocs offers. Some of the most powerful combinations of the meta plugin and other built-in plugins are:
The meta plugin makes it possible to ensure that subsections of your project are annotated with specific tags, so they can't be forgotten when adding pages.
As with all built-in plugins, getting started with the meta plugin is straightforward. Just add the following lines to
mkdocs.yml, and start applying metadata for multiple pages at once:
The meta plugin is included with Material for MkDocs and doesn't need to be installed.
The following settings are available:
Use this setting to enable or disable the plugin when building your project. It's normally not necessary to specify this setting, but if you want to disable the plugin, use:
The following settings are available for meta files:
Use this setting to change the meta file name the plugin will look for when scanning the
docs directory. It's normally not necessary to change this setting, but if you want to change it, use:
The provided path is resolved from the
docs directory recursively.