---
id: mkdocs-macros-plugin
version: "1.5.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# mkdocs-macros-plugin — Unleash the power of MkDocs with macros and variables

License: permissive · Maintenance: active · Downloads: 2.5M/mo

## What it is and what it does

mkdocs-macros-plugin transforms MkDocs markdown pages into Jinja2 templates, allowing you to embed variables, call Python functions as macros, and use conditional logic and loops directly in your documentation. Variables can be defined globally in mkdocs.yml or external YAML files, or locally within individual pages; macros and custom filters are written as Python functions and invoked as template directives. The plugin also supports pluglets—lightweight Python packages that extend functionality without requiring separate MkDocs plugins.

This is useful when your documentation needs dynamic content (pricing tables, version-specific instructions, generated lists), reusable content blocks, or custom HTML extensions (buttons, embeds, formatted callouts). The plugin handles undefined variables gracefully by default but can be configured to fail strictly. It integrates into the standard MkDocs build pipeline and is listed as a high-quality plugin in the official MkDocs catalog.

Use it for:

- Generate pricing or product tables with formulas applied to base values using macro functions
- Maintain version-specific documentation by conditionally rendering sections based on variables
- Create reusable content snippets (e.g., common disclaimers, formatted code examples) via macros
- Embed custom HTML elements (buttons, video embeds, styled callouts) without writing raw HTML
- Build pluglets to package and share documentation extensions across multiple MkDocs projects

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Extends MkDocs with Jinja2 templating to use variables and macros in markdown pages, enabling dynamic content generation and custom syntax extensions.

Yes. The plugin is actively maintained, widely adopted (2K+ dependent repositories), has zero known vulnerabilities, and installs with low friction. It is production-stable and well-suited for documentation projects that benefit from templating—particularly those needing dynamic content, reusable blocks, or custom syntax. Install it if your MkDocs site requires variables, macros, or conditional rendering.

## Install

pip install mkdocs-macros-plugin
uv add mkdocs-macros-plugin
poetry add mkdocs-macros-plugin

## Installing mkdocs-macros-plugin

Before you install: Low friction installation with a pure Python wheel. Active maintenance with a recent release and 410 repository stars. Supports Python 3.8 through 3.12 and integrates cleanly into MkDocs 1.0+.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions, making it safe for both open-source and commercial documentation projects.

Quickstart:

pip install mkdocs-macros-plugin

Then in mkdocs.yml:
plugins:
  - search
  - macros

In a markdown page:
{{ unit_price }} EUR
{{ price(unit_price, 50) }} EUR

Requires MkDocs >= 1.0 and Python >= 3.8. The plugin must be declared in mkdocs.yml to function.

Verify before relying:

- Whether custom macro functions defined in main.py are automatically discovered or require explicit registration
- Performance impact when processing large documentation sites with many variables and macros
- Compatibility with MkDocs themes that have custom template rendering pipelines

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs variables and macros, jinja2 templating for mkdocs, dynamic markdown content generation, mkdocs plugin templating, markdown macro expansion, mkdocs custom syntax, template variables in documentation, mkdocs-plugin, jinja2-templating, documentation-automation

[View on SkillFed](https://skillfed.io/packages/mkdocs-macros-plugin) · [View on PyPI](https://pypi.org/project/mkdocs-macros-plugin/)