Python pour les macros

Le plugin/framework MkDocs-Macros offre de "libérer la puissance de Mkdocs, en utilisant des variables et des macros" à partir de scripts codés en Python...

Installation

Dans Visual Studio Code (VSC), ouvrir un nouveau Terminal (menu Terminal > New Terminal) pour saisir :

pip install mkdocs-macros-plugin

Dans le dossier du projet, modifier les fichiers suivants tels que :

mkdocs.ymlci.yml

plugins:
  - search
  - mkdocs-jupyter:
      include_source: True
  - macros

name: ci
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x      
      - run: pip install --upgrade pip
      - run: pip install mkdocs-material
      - run: pip install mkdocs-jupyter
      - run: pip install mkdocs-macros-plugin
      # C'est ici qu'il faut ajouter si besoin
      # les instructions pour installer avec pip
      # les autres plugins MkDocs ou extensions MarkDown
      # souhaités pour le déploiement du site...

      - run: mkdocs gh-deploy --force

Au prochain redémarrage avec la commande mkdocs serve en local et au prochain déploiement distant sur GitHub le plugin mkdocs-macros sera actif.

Hello world :

A la racine du projet, à coté de mkdocs.yml, créer un fichier main.py tel que par exemple :

def define_env(env):
    "Toto's hook"

    @env.macro
    def hello() :
        return "**Demat d'an holl**<br>_Toto est dans la place !_"

Dans n'importe quel fichier source.md on peut alors insérer le code MarkDown {{ hello() }} pour appeler la macro hello() et obtenir le rendu ainsi généré :

MarkDown saisiMarkDown généréRendu

{{ hello() }}

**Demat d'an holl**<br>_Toto est dans la place !_

Demat d'an holl
Toto est dans la place !

Remarques :

• Une macro comme hello() doit renvoyer une chaine de caractères constituée de MarkDown, \(\LaTeX\), HTML, SVG, ...
• Le plugin macros est désactivé sur ce site, la configuration présentée ici est déployée dans le dépôt et le résultat est visible sur le site.

---

Toujours en construction...

---