Variables¶

Macros and variables are powerful tools to parametrize Markdown files, as they allow to perform Jinja templating directly from Markdown. This is especially useful to include technical data from other files and add central variables via mkdocs.yml.

Configuration¶

Macros¶

The macros plugin adds support to reference variables and call macros and supports Jinja templating directly from Markdown. It can be installed with pip:

pip install mkdocs-macros-plugin

Then, add the following to mkdocs.yml:

plugins:
  - macros

Usage¶

Using predefined variables¶

A set of predefined variables is enabled by default and can be used from Markdown, including data from mkdocs.yml. More specifically, predefined variables fall into the following categories:

config.*: configuration parameters from mkdocs.yml
page.*: metadata and content of current page
navigation.*: list of all pages and sections
environment.*: underlying operating system
git.*: git-related information, if available

Example:

Welcome to {{ config.site_name }}!

Result:

Welcome to Material for MkDocs!

A list of all predefined variables can be printed with:

{{ macros_info() }}

Using custom variables¶

All data defined under extra in mkdocs.yml is automatically exposed as a variable and can be used from the template. This enables centralized parameter storage and management.

Example:

docs/page.md

The unit price is {{ unit.price }}

mkdocs.yml

extra:
  unit:
    price: 12.50

Result:

The unit price is 12.50.

Using variables in snippets¶

The macros plugin can be used to allow variables in snippets, which is not possible with the Snippets extension alone. Add the snippets location to the plugin configuration in mkdocs.yml:

plugins:
  - search
  - macros:
      include_dir: snippets

In your Markdown file, include snippets with Jinja's include function:

{% include "definitions.md" %}

Example:

snippets/definitions.md

The unit price is {{ page.meta.unit.price }}

docs/page-1.md

---
unit:
  price: 12.50
---

{% include "definitions.md" %}

docs/page-2.md

---
unit:
  price: 25.00
---

{% include "definitions.md" %}

Customization¶

Custom macros¶

The macros plugin allows to define custom macros, which can then be used from Markdown files. See the official documentation for more information how to define custom macros.