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 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:

Built-in social plugin

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
```
Built-in blog plugin

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
```
Built-in tags plugin

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
```
Built-in search plugin

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¶

insiders-4.21.0 meta – built-in

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:

`enabled`¶

insiders-4.38.0 true

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:

`meta_file`¶

insiders-4.21.0 .meta.yml

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:

plugins:
  - meta:
      meta_file: .meta.yml

The provided path is resolved from the docs directory recursively.