Loading macroses from a file globally or per-page with docstring

[hellt]

Hi,
My use case for macroses is to simplify certain html/markdown blocks by creating a macros that generates them using user-provided input. Like shortcodes do.

So I am totally fine with defining macroses using jinja2, and not requiring python interpreter for this.
What I am missing though is defining my macroses in a file that would be loaded by default when mkdocs starts.
Currently I can only do local-to-the-page loading using import directive.

What would be cool is to have a setting similar to include_yaml, e.g. include_macros_files which takes a list of files where macroses are defined.

[fralau]

Writing jinja2 macros (instead of Python ones) seems legitimate to me and I am glad that you are bringing that up.

Indeed I would use the import directive in each page, and the idea of having a default import in the config file had never occured to me. 🤔

So that means your macros would be defined once, in one or more files, and you would want an "auto-import" them on all pages?

It is not a shocking idea, but some thought is needed.

Are we going to be opinionated about it (I would prefer it, for obvious reasons), or give some freedom?

• Could we safely assume that you would import your macros files completely and without context?
• What do we want to do with the namespaces? Should macros be available with dot notation (module.macro), or directly?
• What about the as keyword? Do we assume that the name of the file is the name of the namespace?

Better to think about all those questions in advance and choose a simple, sensible approach, than falling later into a rabbit hole 🙂

[hellt]

Let me give you an example how I use macroses today so that some context might help shape out the feature design.

I am using mkdocs-material for my docs site, there are some nice UI elements that require a bit of HTML to be written to make them rendered.

For example, consider this version information snippet

This small UI element is nice and dandy, but effectively it needs to be defined like this

<span class="mdx-badge"><span class="mdx-badge__icon"><a href="#" title="Minimum SR Linux version"><span
                                class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
                                        <path
                                                d="m21.41 11.58-9-9A2 2 0 0 0 11 2H4a2 2 0 0 0-2 2v7a2 2 0 0 0 .59 1.42l9 9A2 2 0 0 0 13 22a2 2 0 0 0 1.41-.59l7-7A2 2 0 0 0 22 13a2 2 0 0 0-.59-1.42M13 20l-9-9V4h7l9 9M6.5 5A1.5 1.5 0 1 1 5 6.5 1.5 1.5 0 0 1 6.5 5Z">
                                        </path>
                                </svg></span></a></span><span class="mdx-badge__text"><a
                        href="https://github.com/nokia/srlinux-container-image/pkgs/container/srlinux/120042212?tag=23.7.1">23.7.1</a></span></span>

Now no one wants to copy paste is every time they want this UI element to be rendered, so I hide it in a macros:

[[[% macro srl_version(version) -%]]]
<span class="mdx-badge"><span class="mdx-badge__icon"><a href="#" title="Minimum SR Linux version"><span
                                class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
                                        <path
                                                d="m21.41 11.58-9-9A2 2 0 0 0 11 2H4a2 2 0 0 0-2 2v7a2 2 0 0 0 .59 1.42l9 9A2 2 0 0 0 13 22a2 2 0 0 0 1.41-.59l7-7A2 2 0 0 0 22 13a2 2 0 0 0-.59-1.42M13 20l-9-9V4h7l9 9M6.5 5A1.5 1.5 0 1 1 5 6.5 1.5 1.5 0 0 1 6.5 5Z">
                                        </path>
                                </svg></span></a></span><span class="mdx-badge__text"><a
                        href="https://github.com/nokia/srlinux-container-image/pkgs/container/srlinux/120042212?tag=[[[version]]]">[[[version]]]</a></span></span>
[[[%- endmacro %]]]

Then I call it on my page as

### Installing SR Linux GPT NDK Application

[[[% import 'macros.html' as macros %]]]
[[[ macros.srl_version('23.7.1') ]]]

Since there are many UI elements that can leverage that shortcode-as-macros approach, I would define all of them in one/several file(s) and would like to globally import them.

Ideally in the plugin settings, maybe as:

plugins:
  - meta
  - glightbox
  - macros:
      include_dir: macros
      include_macroses:
        - macros.html as macros

[fralau]

Thanks for your input and it makes sense.

In your understanding, would the program copy the strings listed there, and paste them as jinja2 directives at the top of every page?

There is still a point that is not clear in my mind: what would be the location of macros.html? How to make sure that jinja2 will always find it, regardless of the position of the markdown file in the mkdocs hierarchy of files?

I imagine that jinja2 should have a solution to that problem, but I don't know what it is. 🤔

[hellt]

macros.html is located in the include_dir, so the plugin already finds the file with included jinja2 syntax today

[fralau]

💡 Good to know, thanks.

[fralau]

I have done some thinking about it. One possibility, would be to generalize the problem, to have a solution that solves a wide range of problems. 🤔

Why not having one auto-include template file; the plugin would insert that file (as a string) at the top of every markdown page that is being parsed?

That file could be called header.md (it could be renamed). Then you would be able to define all the macros in it; or better (to separate your code and allow caching) put all the import directives into it.

But not only; it could contain any markdown, HTML, or combination that one would need to have insert at the top of every markdown page. I already have a use case, where I would like to have a python macro to be executed at the top of every page. Currently, it is problematic, because I wish to insert it manually in each page.

What do you think?

[hellt]

I am willing to try that if you have a prototype. When I was playing with the current way of inserting macros inline:

[[[% import 'macros.html' as macros %]]]
[[[ macros.srl_version('23.7.1') ]]]

I noticed that this instruction is not parsed in material-mkdocs blog plugin, this is likely unrelated to the macros plugin and is rooted in the way blog plugin works, but would be nice to see if the default injection you're talking about could fix that.

[fralau]

OK I will pursue that idea, and see where it leads to.

For the incompatibility between the blog plugin and Mkdocs-Macros, the main reason I have see so far, is when the other plugin is also using a jinja2 templating system with the same syntax. But here, it seems that you have redefined the start and ending strings for blocks and variables, so that does not seem to apply? 🤷

Another reason could be that the blog module is doing some white magic behind the scenes, and Mkdocs-Macros starts losing its marbles? 🤔. In the config file, if you tried to put the call to Mkdocs-Macros before the call to the blog module, what would happen?

[hellt]

yeah I already had macros plugin ahead of the blog plugin, but it just seems that when blog plugin populates the index page of the blog it does so by taking the raw md...

plugins:
  - meta
  - glightbox
  - macros:
      j2_block_start_string: "[[[%"
      j2_block_end_string: "%]]]"
      j2_variable_start_string: "[[["
      j2_variable_end_string: "]]]"
      include_dir: macros
  - blog:
      blog_dir: blog
      post_url_date_format: yyyy
      archive: false
      categories: false
      post_excerpt_max_authors: 2

[fralau]

The best way to solve that, would be to see which events the blog is operating on. What I would do, I were you, would be to ask the author of the plugin, @squidfunk. He has also worked with Mkdocs-Macros so he would know what you are talking about.

(Of course, I am not dumping the problem on him, but he might have a clue).