mkdocs-macros-plugin

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 on this page — 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

mkdocs-macros-plugin on PyPI

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

Evidence: mkdocs_macros_plugin-1.5.0-py3-none-any.whl

Keywords: macros, markdown, mkdocs, python

Tags

More Documentation packages