{"id":2588,"library":"mkdocs-macros-plugin","title":"MkDocs Macros Plugin","description":"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.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/fralau/mkdocs_macros_plugin","tags":["mkdocs","plugin","macros","documentation","jinja2","templating"],"install":[{"cmd":"pip install mkdocs-macros-plugin","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[],"quickstart":{"code":"mkdocs.yml:\n  plugins:\n    - search\n    - macros\n\n  # Optional: point to a custom directory for macros (default: 'docs/macros')\n  # custom_dir: my_macros_folder\n\nmy_macros_folder/main.py (or docs/main.py if no custom_dir):\n\n  def define_env(env):\n      \"\"\"\n      This is the hook for defining variables, macros and filters.\n      \"\"\"\n      # Define a simple variable\n      env.variables['project_name'] = 'My Awesome Project'\n\n      # Define a macro function\n      @env.macro\n      def hello(name='World'):\n          return f\"Hello, {name}!\"\n\n      # Define a Jinja2 filter\n      @env.filter\n      def capitalize_words(text):\n          return ' '.join(word.capitalize() for word in str(text).split())\n\nMarkdown example (e.g., index.md):\n\n  # Welcome to {{ project_name }}\n\n  This is a greeting: {{ hello('AI Agent') }}\n\n  Apply a filter: {{ 'hello world' | capitalize_words }}","lang":"yaml","description":"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."},"warnings":[{"fix":"Update your decorator syntax from `@macro` to `@env.macro` and `@filter` to `@env.filter` for all custom functions in your `define_env` module.","message":"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`.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Upgrade `mkdocs-macros-plugin` to version 1.0.4 or newer to ensure full compatibility with `MkDocs >= 1.5`.","message":"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.","severity":"gotcha","affected_versions":"<1.0.4 with MkDocs >= 1.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.2.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}