MkDocs Macros Plugin

1.5.0 · active · verified Fri Apr 10

The MkDocs Macros Plugin extends MkDocs with powerful templating capabilities, allowing users to define custom variables, macros, and filters using Python. It enables dynamic content generation within Markdown pages and integrates seamlessly with the MkDocs build process. The current version is 1.5.0, and it has a regular release cadence, with updates typically every few months.

Warnings

breaking The 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`.
Fix: Update your decorator syntax from `@macro` to `@env.macro` and `@filter` to `@env.filter` for all custom functions in your `define_env` module.
gotcha Older 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.
Fix: Upgrade `mkdocs-macros-plugin` to version 1.0.4 or newer to ensure full compatibility with `MkDocs >= 1.5`.
gotcha In 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.
Fix: If 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.

Install

pip install mkdocs-macros-plugin Install latest version

Quickstart

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 }}

view raw JSON →