{"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.","language":"python","status":"active","last_verified":"Fri Apr 10","install":{"commands":["pip install mkdocs-macros-plugin"],"cli":{"name":"mkdocs","version":"mkdocs, version 1.6.1 from /usr/local/lib/python3.11/site-packages/mkdocs (Python 3.11)"}},"imports":[],"auth":{"required":false,"env_vars":[]},"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.","tag":null,"tag_description":null,"last_tested":"2026-04-25","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]},"compatibility":null}