Saltar a contenido

Macros

Documentacion oficial Un macro es un fragmento de codigo parametrizado que podemos usar como una template.

Necesitamos instalar el plugin macros: 

pip install mkdocs-macros-plugin

Lo configuramos en mkdocs.yml indicando cual es la carpeta absoluta que incluye nuestras 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/

Definiendo una macro

Creamos un archivo dentro y definimos una macro usando las directivas :

{% 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 %}

Importando la macro

En cualquiera de nuestros markdown podemos importar la macro

{% from 'embeded_media.macros' import youtubeVideo %}
y la usamos posteriormente invocandola indincando los argumentos, esto renderizara el contenido de la template en nuestro fichero markdown

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

O podemos importar todas las macros de un archivo y tenerlas bajo un prefijo para su uso:

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

y luego en el documento la usamos asi , pasandole los argumentos:

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

Variables en las macros

A nivel de pagina podemos definir variables globales para el documento, añadiendo en el encabezado:

---
title: Macros 
description: Explicacion de las macros

variableA: valueA
variableList: ["valorA", "valorB", "valorC"]
variableListObjects: [{"name":"Luis"}, {"name":"Juan"}, {"name":"Maria"}]
---
Podemos usar esas variables asi: 
La variable A es {{ variableA }}
Resultado:

La variable A es mi super value A

y blucles for: 

<ul>

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

  • valorA
  • valorB
  • valorC

Bucles con objetos 

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

  • Luis
  • Juan
  • Maria

Definiendo macros en ficheros externos

Importamos todas las funciones de la macro bajo el alias simple_macros 

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

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

Pedri
Maribel
Marisa

Podemos utilizar los plugins de mkdocs en nuestra macros

Importamos todas las funciones de la macro bajo el alias simple_macros 

Creamos una nueva macro que haga uso de 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 %}


La importamos 

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

La usamos

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

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.

Ejemplo usando 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}])}}
Resultado:

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