mkdocs-macros-plugin

Mkdocs-Macros is a plugin and mini-framework for MkDocs that transforms Markdown pages into Jinja2 templates. It allows contributors to use variables, macros (Python functions), and filters directly within .md files. It can also replace standard MkDocs plugins for tasks like navigation manipulation or post-generation file handling.

Note: The Jinja2 engine used by Mkdocs-Macros is specifically for Markdown pages and is distinct from the Jinja2 engine used by MkDocs for HTML themes.

In mkdocs-macros, post-production refers to actions defined outside of the define_env(env) hook. These actions typically occur after the Jinja2 engine has converted variables and macros into raw Markdown.

There are three main types of post-production:

1. Modifying markdown pages: Altering the Markdown content either before or after macro rendering.
2. Influencing HTML pages: Affecting the HTML templates used by the MkDocs theme.
3. Post-build operations: Performing operations after MkDocs has completely finished execution.

A pluglet is a preinstalled module for mkdocs-macros distributed via standard Python packaging (e.g., PyPI).

Key distinctions:

• Vs. Modules: While a standard macro module is typically a local file like main.py, a pluglet is a preinstalled package that can be shared and reused across different projects.
• Vs. MkDocs Plugins: A pluglet is a lightweight tool that sits on top of the mkdocs-macros plugin. Unlike an MkDocs plugin, you do not need to subclass BasePlugin; you only need to implement a define_env(env) function. While MkDocs plugins can hook into any build event, pluglets primarily operate on the on_config event via define_env, though they can be extended using other hooks.

A pluglet can define macros and perform changes on the website architecture.

def define_env(env):
    ....

A macro is a Python function that accepts arguments and returns a string. When you call a macro from a Markdown page using Jinja2 syntax, the plugin executes the Python function and embeds the returned string into the page before MkDocs renders the final HTML.

Macros can range from simple UI elements (like a button) to complex logic (like querying a database and formatting the results). This allows users to add rich functionality to Markdown without needing to write HTML or CSS directly in their content files.

{{ button('Try this', 'http://your.website.com/page') }}

While both use hooks to customize behavior, they serve different purposes:

When using macros, be aware of the security implications, especially if the authors of the Markdown files are different from the maintainers of the web server:

• Side Effects: Macros can have unintended side effects if they contain complex logic or error-prone code.
• Information Exposure: Macros might inadvertently expose sensitive information.
• Shell Access: Depending on your use case, you may need to decide whether to grant macros access to the shell (e.g., for internal development teams) or to "sandbox" them for business applications to prevent unauthorized execution.

Because MkDocs translates Markdown files into a different HTML structure (e.g., /docs/foo.md becomes /site/foo/index.html), standard relative links often fail.

The Problem: A link like [other page](foo) or ![image](image.jpg) will likely break because the HTML nesting level has changed.

The Solution: Use the fix_url() function within a macro to automatically lift relative URLs up one level so they behave as they do in Markdown.

# In your main.py
from mkdocs_macros import fix_url 

def define_env(env):
    @env.macro
    def image(url: str, alt: str = ''):
        # fix_url converts 'foo.jpg' to '../foo.jpg'
        url = fix_url(url)
        return f'<img src="{url}", alt="{alt}">'

While Markdown is simple, it lacks expressiveness for complex UI elements. The mkdocs-macros-plugin provides three ways to extend your documentation beyond standard Markdown:

1. Markdown Extensions: Using standard Python-Markdown extensions (configured in mkdocs.yml). These are good for standard features like footnotes or admonition.
2. Custom HTML: Writing raw HTML/CSS directly in Markdown. This is flexible but difficult to maintain and scale if you need to repeat the same patterns.
3. Macros: Using Python functions via Jinja2 syntax. This is the preferred method for reusable, programmable components. It allows you to teach non-technical users to use complex UI elements by providing simple function calls, while allowing developers to write the underlying logic in Python.

The plugin transforms Markdown pages into Jinja2 templates. This allows you to use:

1. Variables: Access data using {{ variable_name }}.
2. Macros: Call Python functions using {{ macro_name(arg1, arg2) }}.
3. Filters: Apply transformations to variables.
4. Jinja2 Logic: Use control structures like {% if ... %} and {% for ... %}.

Macros can return HTML code, making them useful for creating custom syntax like buttons, YouTube embeds, or email links.

The unit price of product A is {{ unit_price }} EUR.
Taking the standard discount into account,
the sale price of 50 units is {{ price(unit_price, 50) }} EUR.

When adding mkdocs-macros-plugin to an existing project, you may encounter syntax errors or incorrect rendering. This happens because the plugin attempts to interpret any text starting with {% or {{ as a Jinja2 directive or macro.

Common conflict locations include:

• Code blocks: Documenting Jinja2, Django, Nunjucks, Twig, or Ansible syntax.
• Maths: LaTeX snippets containing {{ or }} (e.g., {{?}}).
• Other templates: Pre-existing templating languages using {# or {{.

Important Caution: Simply wrapping these statements in Markdown code fences (using triple backticks ``` or tildes ~~~) will not prevent the plugin from attempting to interpret them. The plugin intentionally ignores code fences to allow for dynamic content computation within code blocks.