Macros for listing images inside a specific folder with usage example and preview

[Andre601]

I want to improve the documentation of a badge provider by having the pages listing these badges be auto-generated.

The files exist outside the docs folder and are structured like this:

<root of repo>/
  |- assets/
  |    |- compact/
  |    |    |- .../
  |    |        |- <name>_<height>h.png
  |    |        |- <name>_vector.svg
  |    |- compact-minimal/
  |    |    |- .../
  |    |        |- <name>_<height>h.png
  |    |        |- <name>_vector.svg
  |    |- cozy/
  |    |    |- .../
  |    |        |- <name>_<height>h.png
  |    |        |- <name>_vector.svg
  |    |- cozy-minimal/
  |    |    |- .../
  |    |        |- <name>_<height>h.png
  |    |        |- <name>_vector.svg
  |- docs/
  |    |- ...
  |- mkdocs.yml

• .../ means there are multiple folders with various names here.
• <name> can be any name the file has.
• <height> is a number

I now considered making a macro that would allow me to list images from one of the folders relative to assets/ with each sub-folder being used as a header on the page.

The listed content should contain a preview of the image(s) and an example on how to include it through HTML or Markdown.
Also, images of the same <name> should be grouped together.

To explain it a bit better, imagine this setup:

<root of repo>/
  |- assets/
  |    |- compact/
  |         |- example/
  |             |- example_64h.png
  |             |- example_vector.svg
  |- docs/
  |    |- index.md
  |        |- badges/
  |            |- compact.md
  |- mkdocs.yml

In compact.md I would include the macro {{ gen_list("compact") }} and it would generate a page containing something similar to this:

# Compact

## Example <!-- Folder name -->

### Example <!-- Image name, prettyfied (i.e. removed -) -->

#### Preview

![example-png](https://cdn.example.com/assets/compact/example/example_64h.png)
![example-svg](https://cdn.example.com/assets/compact/example/example_vector.svg)

#### HTML (Recommended)

```html
<img alt="example-png" src="https://cdn.example.com/assets/compact/example/example_64h.png" height="64">
<img alt="example-svg" src="https://cdn.example.com/assets/compact/example/example_vector.svg" height="64">
```

#### Markdown

```markdown
![example-png](https://cdn.example.com/assets/compact/example/example_64h.png)
![example-svg](https://cdn.example.com/assets/compact/example/example_vector.svg)
```

I really hope what I explain here makes sense, because I honestly have a hard time explaining it...

I'm not sure if it would be better making the macro in Python or having it as a jinja2 macro and use that... Or if there is a better alternative that doesn't even use Macros or smth...

I'm fine with the content being in HTML rather than markdown, if that is unavoidable...

[fralau]

I think it's an excellent question and it requires to take a step back. Rather than answering it in your specific case, I will provide a general answer (and let you work it out according to your own judgement and preferences).

The tools in the toolbox

When you work with different tools at the same time, the first step to get a crystal clear picture of what each tool is for (with its strengths and weaknesses) and what essential role it is playing in the ecosystem. So its important to differentiate them, roughly:

1. Markdown is for laying out the rich text you want to be in your page.
2. Extensions are for enriching the Markdown syntax, to add new functionality.
3. Code blocks is for litteral text, computer code to be printed out (colorized) or code that needs to be compiled or executed on the fly (like diagram rendering). Anything that is not litteral text, will require either javascript and/or a plugin.
4. Plugins are pieces of code that expand the functionality of Mkdocs in various ways. The plugin system works with "hooks" (events) that can be used to trigger various actions that the plugin must executie at specific steps of the website production process.
5. Html (+ css + javascript) is for content you cannot express with any of the above .

How Mkdocs-Macros expands the toolbox

Mkdocs-Macros expand this toolbox by adding the power of jinja2 templates.

So here would be the guiding principles, if want to you wish to extract maximum power from Mkdocs-Macros:

1. Use your markdown page as a jinja2 template. For that you need source data (your Mkdocs-Macros environment, which includes the extra section in your config file).
   Do not hesitate to make liberal use the following jinja2 constructs:
   • loops (for)
   • conditions (if)
   • filters -- really, filters can be super useful for formatting your data.
2. For the proper use of macros in your template, we can use the jinja2 definition: Macros are comparable with functions in regular programming languages. They are useful to put often used idioms into reusable functions to not repeat yourself (“DRY”). You have two possibilities for defining them:
   a. jinja2 syntax
   b. Pure Python (as a module)

jinja2 versus Python macros?

TLDR: write your macros in Python.

The long answer: Which you chose is, really, whichever you prefer, since they do the same. However, here is my viewpoint about it, i.e. the philosophy behind Mkdocs-Macros.

I suppose that the designers of Jinja2 added the possibility of defining jinja2 macros inside templates as a convenience solution, an extra flexibility; that's because writing a Python function (loaded when booting the jinja2 environment) would imply a change to the project's "hard-code"; and depending on how the code or project is organized, it can be too much work. The syntax of jinja2 macros works and is actually quite elegant, so it could be a time saver. But let's be honest: compared to Python, that syntax is fussy.

But with Mkdocs-Macros, the operating principle has been turned on its head, with a little white magic in the plugin (dynamic loading of Python code). A key aim of the project was to make it super-easy to write a Python module to define macros (and filters) specifically for a website. This was born out of my frustration with wikis like Confluence, which turned writing macros into an adventure into Javassic Park, complete with skeletons and Velocity raptors.

I just wanted to express: "here is my function" with a def in Python, put a decorator on it that defines whether it's a macro or a filter, and that had to be that.

Allowing a programmer to quickly write macros in Python on a "per-website" basis, was the whole point of this plugin.

More on it on the About page of the project.

[Andre601]

In all honesty... I only understood like half of this reply.

[fralau]

Bottom line:

You can write a macro that does everything, but it would be a pity not to use the power of templating.

1. Treat your markdown page as a jinja2 template, with variables, and with {% for .... %} and {% if .... %}.
2. When you find yourself repeating the same pattern over an over, write a Python macro for that pattern.