Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
To get started, add `macros` to your `plugins` list in `mkdocs.yml`. Then, create a Python file (e.g., `main.py` within your `docs` directory or a custom directory specified by `custom_dir`) containing a `define_env(env)` function. This function is the entry point for defining your custom variables, macros, and filters, which can then be used in your Markdown pages. Run `mkdocs serve` to see your changes.
mkdocs.yml:
plugins:
- search
- macros
# Optional: point to a custom directory for macros (default: 'docs/macros')
# custom_dir: my_macros_folder
my_macros_folder/main.py (or docs/main.py if no custom_dir):
def define_env(env):
"""
This is the hook for defining variables, macros and filters.
"""
# Define a simple variable
env.variables['project_name'] = 'My Awesome Project'
# Define a macro function
@env.macro
def hello(name='World'):
return f"Hello, {name}!"
# Define a Jinja2 filter
@env.filter
def capitalize_words(text):
return ' '.join(word.capitalize() for word in str(text).split())
Markdown example (e.g., index.md):
# Welcome to {{ project_name }}
This is a greeting: {{ hello('AI Agent') }}
Apply a filter: {{ 'hello world' | capitalize_words }}
mkdocs --version
Debug
Known issues
breakingThe syntax for declaring macros and filters within `define_env` changed significantly in version 0.3.0. Previously, `@macro` and `@filter` decorators were used directly. From 0.3.0 onwards, these were replaced by `@env.macro` and `@env.filter`.fixUpdate your decorator syntax from `@macro` to `@env.macro` and `@filter` to `@env.filter` for all custom functions in your `define_env` module.
affects: <0.3.0
gotchaOlder versions (<1.0.4) of `mkdocs-macros-plugin` could experience filter-related warnings or issues when used with `MkDocs >= 1.5`. This was due to changes in how MkDocs handled filters.fixUpgrade `mkdocs-macros-plugin` to version 1.0.4 or newer to ensure full compatibility with `MkDocs >= 1.5`.
affects: <1.0.4 with MkDocs >= 1.5
gotchaIn versions prior to 1.2.0, a `define_env()` function was implicitly required in your Python module even if you weren't defining custom macros or variables, leading to unexpected errors if omitted. This is no longer the case.fixIf you are on an older version and encounter issues, ensure you have at least an empty `define_env(env): pass` function in your main macros module. For versions 1.2.0+, `define_env` is only required if you actually define custom logic.
affects: <1.2.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mkdocs-macros-plugin'
The `mkdocs-macros-plugin` Python package is not installed in the environment where MkDocs is being run.
fixInstall the plugin using pip: `pip install mkdocs-macros-plugin`
Error: The "macros" plugin is not installed
This error occurs when the 'macros' plugin is listed in the `plugins` section of `mkdocs.yml` but either the package is not installed, or there's a typo in the plugin name (e.g., 'macros' instead of 'mkdocs-macros'). It can also occur if the installation was faulty.
fixFirst, ensure the plugin is installed with `pip install mkdocs-macros-plugin`. Then, verify that `mkdocs.yml` correctly lists the plugin under the `plugins` section as `- macros` (the official short name) or ensure no other plugin has a name conflict.
Jinja2 syntax error (or similar traceback related to unexpected Jinja2 interpretation)
The `mkdocs-macros-plugin` processes markdown pages as Jinja2 templates. If your markdown contains text that resembles Jinja2 syntax (e.g., `{{ ... }}` or `{% ... %}`) but is not intended to be a macro or variable, the plugin will try to interpret it and fail, leading to a syntax error or incorrect rendering. This is common with code examples (like JavaScript/Django templates), LaTeX, or other templating languages.
fixWrap the problematic content in `{% raw %}` and `{% endraw %}` tags to prevent Jinja2 from processing it: `{% raw %}{{ your_literal_jinja_like_content }}{% endraw %}`. Alternatively, you can escape the markers, e.g., `{{'{{'}}` for `{{`. ModuleNotFoundError: No module named 'main' (or 'utils', or other custom Python module name)
When defining custom macros, filters, or variables in a Python file (typically `main.py` or a custom module), this error indicates that the `mkdocs-macros-plugin` cannot locate or import the specified Python module. This often happens due to incorrect file placement, incorrect `module_name` configuration, or Python's inability to find the module in its path.
fixEnsure your Python module (e.g., `main.py`) is in the root directory of your MkDocs project (next to `mkdocs.yml`), or specify the correct relative path in your `mkdocs.yml` under `plugins`: `- macros: module_name: path/to/your_module`. For modules with internal imports, ensure they are structured as a Python package with `__init__.py` files if they reside in subdirectories, and that all necessary Python dependencies are installed.
ModuleNotFoundError: No module named 'packaging'
This specific `ModuleNotFoundError` indicates that a dependency required by `mkdocs-macros-plugin` itself (or one of its internal dependencies) is missing. The `packaging` library is a common example of such a dependency.
fixInstall the missing dependency: `pip install packaging`. If other similar `ModuleNotFoundError` errors appear, install those specific packages as well.
Upgrade
Version history
1.5.0latest on PyPI · released Nov 13, 2025
Audit
Dependencies
No dependency data recorded yet.