Mermaid pour vos diagrammes

2 minutes de lecture
mermaid hugo

Comme vous le savez, j’utilise Hugo un CMS me permettant de publier simplement sur mon blog mes articles en Markdown.

Malheureusement, dès que j’ai besoin d’illustrer quelque chose de complexe, je devais utiliser un logiciel comme Yed, créer mon illustration, puis exporter le diagramme en temps qu’image, pour enfin importer l’image via Markdown.

Puis je suis tombé sur Mermaid, une librairie permettant de créer simplement des diagrammes directement dans un fichier Markdown !

exemple de graph mermaid

Cette librairie est utilisée nativement par GitLab et vous aidera surement à documenter vos dépôts, expliquer des fonctions complexes, décrire des process ou même gérer de façon simple l’organisation et la roadmap d’une petite équipe de développement, il y a pleins de possibilités :

  • Procédures
  • Diagrammes de classe
  • Diagrammes de séquence
  • Diagrammes d’état
  • Parcours utilisateurs
  • Gantt
  • Camemberts

Instalation sur Hugo

Etape 1 : appeler le script

Commençons par appeler le script Mermaid dans le modèle HTML contenant vos scripts :

Ici j’ai un template script.html qui contient l’ensemble de mes script

  <!-- librairie MermaidJS -->
  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

Etape 1bis (optionnelle)

Vous pouvez décider d’appeler le script sous condition. Pour ce faire, nous allons utiliser les possibilités offertes par Hugo afin de permettre d’utiliser la librairie Mermaid sous condition :

  {{ if (.Params.mermaid) }}
    <!-- librairie MermaidJS -->
    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
  {{ end }}

Pour mon site par exemple, j’ai choisi de ne pas appeler mermaid dans mes archétypes archetypes/default.md et archetypes/post.md, donc par défaut, Mermaid n’est pas activée sur l’ensemble de mon site.

  +++ 
  draft = true
  date = {{ .Date }}
  title = ""
  slug = "" 
  mermaid = false
  +++

Pour utiliser mermaid, il faut que dans l’entête, ou le fichier de configuration régissant la page, que le paramettre mermaid soit activé :

  ---
  title: "Mermaid pour vos diagrammes : cèdez aux champs des sirènes..."
  date: 2020-08-23T14:00:00+02:00
  slug: "/mermaid/"
  img: "/images/article1.jpg"
  alt: "mermaid hugo"
  mermaid : true
  ---

Etape 2 : définir une macro

Enfin, pour utiliser Mermaid, j’ai créé une macro dans layouts/shortcodes/mermaid.html pour indiquer à Hugo que le contenu de la macro est à interpréter par la librairie Mermaid :

  <div class="mermaid">
    {{.Inner}}
  </div>

Grace à l’appel de votre macro, vous pouvez maintenant afficher n’importe quel diagramme nativement dans votre site Hugo :

graph TD; A(installer mermaid)-->B(créer condition); A-- sans conditions-->C(créer macro); B-->C; C-->D(créer diagramme); D-->F(écrire article); F-->E(publier article); style E fill:#f88,stroke:#333,stroke-width:4px

Merci d’avoir lu cet article !

Si l’article vous a plu, n’hésitez pas à m’ajouter sur LinkedIn.