Include macros from an external file, without explicit import

[hellt]

Hi @fralau
thank you for this project, it is a life saver.

May I ask your guidance on how to achieve the following best:

I am creating an alternative to shortcodes for my doc site, where I use macroses to generate rich HTML content driven by the variables passed over to the macros.

My macroses are defined in a macros.html file and look like this:

[[[% macro diagram(url,page, title, zoom='2') -%]]]
<figure>
        <div class='mxgraph'
                style='some style'
                data-mxgraph='{"page":[[[page]]],"zoom":[[[zoom]]],"url":"[[[url]]]"}'>
        </div>
        [[[%- if title -%]]]
        <figcaption>[[[title]]]</figcaption>
        [[[%- endif -%]]]
</figure>
[[[%- endmacro %]]]

Currently I use this macros in the md file like so:

[[[% import 'macros.html' as macros %]]]
[[[ macros.diagram(url='https://url.drawio', title='Lab Topology', page=0) ]]]

What I wanted to know if I can make this macros.html file which contains all my macroses to be loaded automatically, without explicitly calling it out on every page that uses the macros?

[hellt]

I think I can rather define my templates in python

"""
Mkdocs-macros module
"""

from jinja2 import BaseLoader, Environment


def define_env(env):
    """
    Macroses used in SR Linux documentation
    """

    @env.macro
    def diagram(url, page, title, zoom=2):
        """
        Diagram macro
        """

        diagram_tmpl = """
<figure>
    <div class='mxgraph'
            style='max-width:100%;border:1px solid transparent;margin:0 auto; display:block;box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.25);border-radius: 0.25rem;'
            data-mxgraph='{"page":{{ page }},"zoom":{{ zoom }},"highlight":"#0000ff","nav":true,"resize":true,"edit":"_blank","url":"{{ url }}"}'>
    </div>
    {% if title %}
    <figcaption>{{ title }}</figcaption>
    {% endif %}
</figure>
"""

        template = Environment(loader=BaseLoader()).from_string(diagram_tmpl)

        return template.render(url=url, page=page, title=title, zoom=zoom)

[fralau]

This is correct, and more idiomatic than your first solution. Indeed, in that way the macro will be available for all pages.

Using a Jinja2 template certainly works, and I understand why you did it.

I prefer to use f-strings for that, even though in that case it might be a little more tricky:

def define_env(env):
    """
    Macros used in SR Linux documentation
    """

    @env.macro
    def diagram(url, page, title, zoom=2):
        """
        Diagram macro
        """

        diagram_tmpl = f"""
<figure>
    <div class='mxgraph'
            style='max-width:100%;border:1px solid transparent;margin:0 auto; display:block;box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.25);border-radius: 0.25rem;'
            data-mxgraph='{{"page":{page},"zoom":{zoom},"highlight":"#0000ff","nav":true,"resize":true,"edit":"_blank","url":"{url}"}}'>
    </div>
    {f"<figcaption>{title}</figcaption>" if title else ""}
</figure>
"""
        return diagram_tmpl

It is easy to implement the conditional clause, using the f-string with a ternary operator. It is necessary, however, to double the "real" brackets.

It is a matter of taste/style.

[hellt]

oh yes, I was quick to stuff j2 there, I would rather stay without the templating engine where I can, and ternary op makes a lot of sense, thanks for reminding me of this.

[fralau]

You're very welcome. Thanks also for your appreciation for the Mkdocs-Macros project.