1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-30 18:24:35 +01:00
mkdocs-material/docs/plugins/meta.md
2023-11-21 08:37:48 +01:00

5.1 KiB
Raw Blame History

title icon
Built-in meta plugin material/file-tree

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:

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:

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.