Macros

Official Documentation A macro is a parameterized code fragment that we can use as a template.

We need to install the macros plugin:

pip install mkdocs-macros-plugin

We configure it in mkdocs.yml indicating which is the absolute folder that includes our macros:

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
  - macros:
      include_dir: docs/_include/macros   # https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/

Defining a macro

We create a file inside and define a macro using the directives:

{% macro youtubeVideo(videoId, videoTitle) %}
<div class="embed-youtube">
    <iframe width="560" height="315" src="https://www.youtube.com/embed/{{ videoId }}" title="{{ videoTitle }}" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
{% endmacro %}

Importing the macro

In any of our markdown files we can import the macro

{% from 'embeded_media.macros' import youtubeVideo %}

and we use it later by invoking it indicating the arguments, this will render the template content in our markdown file

{{youtubeVideo('BcJSsEekO-U?si=POEgTtopYQ4uddHp', 'Al son del macarron')}}

Or we can import all macros from a file and have them under a prefix for use:

{% import 'embeded_media.macros' as embeded_media_macros %}

and then in the document we use it like this, passing the arguments:

{{embeded_media_macros.spotifyList('0WjifMva8IEzE937TGqt9D?si=d4bd4aafcf244840')}}

Variables in macros

At the page level we can define global variables for the document, adding in the header:

---
title: Macros
description: Explanation of macros

variableA: valueA
variableList: ["valueA", "valueB", "valueC"]
variableListObjects: [{"name":"Luis"}, {"name":"Juan"}, {"name":"Maria"}]
---

We can use those variables like this:

Variable A is {{ variableA }}

Result:

Variable A is my super value A

and for loops:

<ul>

{% for variable in variableList %}
    <li>{{ variable|e }}</li>
{% else %}
    <li><em>no users found</em></li>
{% endfor %}
</ul>

valueA
valueB
valueC

Loops with objects

<ul>
{% for person in variableListObjects %}
    <li>{{ person.name|e }}</li>
{% else %}
    <li><em>no persons found</em></li>
{% endfor %}
</ul>

Luis
Juan
Maria

Defining macros in external files

We import all functions from the macro under the alias simple_macros

{% import 'simple.macros' as simple_macros %}

{{simple_macros.createTable([{"name":"Pedri"}, {"name":"Maribel"}, {"name":"Marisa"}])}}

Result:

Pedri

Maribel

Marisa

We can use mkdocs plugins in our macros

We import all functions from the macro under the alias simple_macros

We create a new macro that uses tabs

{% macro createPersonsTabs(persons) %}
    {% for person in persons %}
=== "{{ person.name }}"

    My name is {{ person.name|e }} .
    {% if person.name == 'Pedri' %}
    :man_raising_hand: I like {{ person.hobbies|e }}
    {% elif person.name == 'Maribel' %}
    :grinning: I like {{ person.hobbies|e }}
    {% else %}
    I like {{ person.hobbies|e }} and hate other persons.
    {% endif %}

    {% endfor %}
{% endmacro %}


We import it

{% import 'simple.macros' as simple_macros %}

We use it

{{simple_macros.createPersonsTabs([{"name":"Pedri", "hobbies":"sing, jump"}, {"name":"Maribel", "hobbies":"Play Guitar"}, {"name":"Marisa", "hobbies":"Listen to Judas Priest"}])}}

Result:

PedriMaribelMarisa

My name is Pedri .

🙋‍♂️ I like sing, jump

My name is Maribel .

I like Play Guitar

My name is Marisa .

I like Listen to Judas Priest and hate other persons.

Example using PieChart

{% macro createPersonsChartPie(persons) %}
    ```mermaid
    pie title How are the best voted person?
        {% for person in persons %}
        "{{ person.name|e }}" : {{ person.voted|e }}
        {% endfor %}
    ```
{% endmacro %}

{% import 'simple.macros' as simple_macros %}

{{simple_macros.createPersonsChartPie([{"name":"Pedri", "voted":15}, {"name":"Maribel", "voted":65}, {"name":"Marisa", "voted":20}])}}

Result:

pie title How are the best voted person? "Pedri" : 15 "Maribel" : 65 "Marisa" : 20