---
template: overrides/main.html
---

# 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][1] 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`:

``` yaml
plugins:
  - macros
```

  [1]: https://github.com/fralau/mkdocs_macros_plugin

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

``` markdown
Welcome to {{ config.site_name }}!
```

_Result_:

``` markdown
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"

    ```` markdown
    The unit price is {{ unit.price }}
    ````

=== "mkdocs.yml"

    ``` yaml
    extra:
      unit:
        price: 12.50
    ```

_Result_:

The unit price is 12.50.

### Using variables in snippets

You may want to use variables in snippets, for example, when describing the same
procedure in multiple contexts where only one piece of information differs. This
does not work with snippets that are included using the [Snippets][2] extension.
Instead, you can use the [macros][3] plugin for defining snippets.

To this end, add the snippet location using the `include_dir` parameter to the 
plugin's configuration in `mkdocs.yml`, for example:

``` yaml
plugins:
  - search
  - macros:
      include_dir: snippets
```

In your Markdown file, you can include snippets with Jinja's [`include`][4]
function:

``` markdown
{% include "definitions.md" %}
```

This example illustrates the behavior:

=== "snippets/definitions.md"

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

=== "docs/page-1.md"

    ``` markdown
    ---
    unit:
      price: 12.50
    ---

    {% include "definitions.md" %}
    ```

=== "docs/page-2.md"

    ``` markdown
    ---
    unit:
      price: 25.00
    ---

    {% include "definitions.md" %}
    ```

  [2]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
  [3]: #macros
  [4]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include

## Customization

### Custom macros

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

  [5]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/