Skip to content

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.

Sponsors only – this plugin is currently reserved to our awesome sponsors.

Objective

How it works

The plugin scans the [docs directory][mkdocs.docs_dir] 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:

.meta.yml
tags:
  - Example

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:

.
├─ docs/
│  ├─ ...
│  ├─ example/
│  │  ├─ .meta.yml
│  │  ├─ a.md
│  │  ├─ ...
│  │  └─ z.md
│  └─ ...
└─ mkdocs.yml

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:

- :material-share-circle:   __[Built-in social plugin][social]__ --- The meta plugin can be used to [change the layout] for social cards or [change specific layout options] like [background] or [color] for a subset of pages.
.meta.yml
social:
  cards_layout: default/variant
- :material-newspaper-variant-outline:   __[Built-in blog plugin][blog]__ --- The meta plugin allows to automatically associate blog posts with specific [authors] and [categories], ensuring that blog posts are always correctly annotated.
.meta.yml
authors:
  - squidfunk
- :material-tag-text:   __[Built-in tags plugin][tags]__ --- 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.
.meta.yml
tags:
  - Example
- :material-magnify:   __[Built-in search plugin][search]__ --- The meta plugin makes it easy to [boost] specific sections in search results or to [exclude] them entirely from being indexed, giving more granular control over search.
.meta.yml
search:
  exclude: true

Configuration

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:

plugins:
  - meta

The meta plugin is included with Material for MkDocs and doesn't need to be installed.

General

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:

plugins:
  - meta:
      enabled: false

Meta file

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][mkdocs.docs_dir]. It's normally not necessary to change this setting, but if you want to change it, use:

plugins:
  - meta:
      meta_file: .meta.yml

The provided path is resolved from the [docs directory][mkdocs.docs_dir] recursively.