Mermaid.js est une bibliothèque JS puissante qui permet de générer des diagrammes et des graphiques organisationnels à partir de texte brut dans une syntaxe qui ressemble au Markdown.
Nous allons voir ici comment installer et utiliser Mermaid.js et découvrir la syntaxe mermaid pour définir des diagrammes.
Attention, la version actuelle de Mermaid.js nécessite une intégration sur la page HTML comme un script de type module. La syntaxe des scripts de type module est une fonctionnalité récente de JavaScript avec une syntaxe particulière. Il est nécessaire d'inclure la ligne d'import avant toute autre ligne de code JavaScript. Toute action sur l'objet JS mermaid, nécessite l'import du module.
<script type="module">
/* Import du module Mermaid.js */
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
/* Initialisation de l'objet JS mermaid */
mermaid.initialize({ startOnLoad: true });
/* Création du graphique quand la page est chargée */
window.addEventListener("load", async () => {
const result = await mermaid.render("ID_diagram", "code en syntaxe Mermaid");
document.getElementById("diagram").innerHTML = result.svg;
});
</script>
Vous pouvez aussi choisir de ne pas dépendre d'un service externe et inclure les scripts avec npm ou yarn en exécutant dans le terminal au niveau de votre projet la commande :
npm install mermaid
Voici un premier exemple de code mermaid:
Ce qui rend un graphique comme celui-ci :
Notez que mermaid.render()attend en entrée deux paramètres :
- Le premier paramètre est un identifiant de graphique de type string. C'est l'identifiant unique du graphique dans votre application.
- Le second est la chaine de caractères contenant le descriptif du graphique, la convertit et retourne un objet complexe.
Le graphique est généré sous forme d'une image SVG, une image au format vectoriel qui ne génère ni flou ni pixelisation quel que soit le niveau de grossissement.
Le code de l'image est contenu dans l'attribut svg qui doit être placé dans le contenu HTML de l'élément recevant le graphique.
La première ligne de code graph TD est une instruction mermaid qui
définit le type de graphique que vous voulez créer. Dans ce cas, nous
utilisons un graphique dirigé du haut vers le bas (TD: Top Down).
La ligne suivante A[Start] --> B{Ca marche ?} définit le
premier noeud A avec comme libellé "Start" et le second noeud B avec comme
libellé "Ca marche ?".
Le lien entre les deux noeuds est une arrête qui indique que l'on peut aller
de A à B.
Le style de noeud box est défini par les crochets [ ] autour du
libellé.
Les accolades { } définissent le noeud B comme une boite de
condition.
La ligne suivante B -->|Oui| C[Super !] définit un lien entre le
noeud B et le nouveau noeud C.
Le libellé Oui est affiché sur la flêche car il est entouré du
caractère pipe (|) qui indique que l'on peut aller de B à C si la
réponse est positive.
Le nouveau noeud C a comme libellé "Super !" et le style de noeud box est
défini par les crochets [ ] autour du libellé.
Enfin, la dernière ligne B -->|Non| D[Vérifier le code]reprend les
éléments de syntaxe déja vus :
Un libellé Non sur la flêche et un dernier noeud D avec le libellé
"Vérifier le code".
Avec la syntaxe potentiellement complexe de Mermaid, il est recommandé d'utiliser le gestionnaire d'erreurs pour identifier les mauvaises syntaxes.
Notre appel à mermaid.render() est effectué dans une fonction asynchrone qui ne bloque pas le processus du navigateur.
Si l'erreur se produit, elle sera capturée par la clause catch. Elle est affichée sur la console sans bloquer le reste du script :
window.addEventListener("load", async () => {
try {
const result = await mermaid.render(
"mermaidDiagram",
document.getElementById("editor").value
);
document.getElementById("diagram").innerHTML = result.svg;
} catch (error) {
console.log(error);
}
});
En utilisant cette approche, nous pouvons détecter et corriger les erreurs de syntaxe de la définition des graphs grâce à une analyse fine et précise de Mermaid.
Par exemple, si on ajoute un espace dans la définition du lien entre deux noeuds B - ->|Oui| C[Super !], la console affiche exactement l'emplacement de l'erreur et les caractères possibles attendus :
Error: Parse error on line 3:
B - ->|Oui| C[Super !]
--^
Expecting 'SEMI', 'NEWLINE', 'EOF', 'AMP', 'START_LINK', 'LINK', got 'NODE_STRING'
Les graphes TD (Top Down) et LR (Left Right) sont des graphes qui sont utilisés pour visualiser les relations entre les éléments d'un système.
Voici une liste exhaustive des syntaxes de Mermaid pour les graphes TD et LR :
La première ligne définit le type de graphique. On peut donc avoir graph TD ou graph LR
Un noeud est défini par la syntaxe node [label]. node est le nom interne du noeud qui servira dans la définition des relations. label est le texte qui sera affiché sur le noeud. Le label peut être entouré par des crochets pour afficher une boîte rectangulaire, par des parenthères pour afficher une boîte rectangulaire avec des bords arrondis ou avec des accolades pour une boîte losange utilisée pour marquer une condition.
La connexion entre les noeuds A et B est définie par ces syntaxes :
A --> B. Une flêche relie A vers B.
A <--> B. Une flêche double relie A et B.
A -- Lien --> B. Une flêche relie A vers B, avec le libellé "Lien" au milieu de la connexion.
Voici un graphe LR prédifini. Vous pouvez le modifier et cliquer sur le bouton "Générer" pour mettre à jour le rendu ou l'éventuel erreur détectée :
Naturellement, vous pouvez définir la mise en forme et les couleurs de tous les éléments du graphique.
La mise en forme générale de votre diagramme peut être définie à l'initialisation de l'objet mermaid. Voici quelques options parmi les plus intéressantes :
fontFamily est une chaîne de caractères. Par exemple "Arial, \"Helvetica Neue\", sans-serif"look vaut "handDrawn" ou "classic". L'option dessiné à la main a un rendu particulièrement réussi.theme offre le choix parmi de nombreux thèmes prédéfinis, comme "light", "dark", "forest", ...mermaid.initialize({
startOnLoad: true,
look: "handDrawn",
theme: "forest",
fontFamily: "Arial, \"Helvetica Neue\", sans-serif"
});La configuration globale peut être définie aussi dans le code mermaid avec l'entête suivante, semblable à du code JSON :
---
config:
look: handDrawn
theme: forest
fontFamily: Arial, "Helvetica Neue", sans-serif
---
graph LR
...Chaque élément du diagramme peut aussi être stylisé directement dans le code mermaid de définition de l'organisation du diagramme.
Les balises HTML sont reconnues pour mettre en forme le texte avec le soulignement <u>, l'italiques <i>ou le gras <b>.
La mise en forme des couleurs utilisent une syntaxe inspirée du CSS.
Par exemple, pour que le noeud A soit écrit en blanc et gras sur fond rouge entouré de noir, on ajoute en fin de code mermaid :style A fill:#f00000,stroke:#000000,color:#ffffff
linkStyle 0 stroke:#ff0000,stroke-width:4px,stroke-dasharray: 5 5
Mermaid supporte plusieurs autres formes de diagrammes comme la séquence sequenceDiagram, le Gantt Gantt, les classes classDiagram, la timeline classDiagram et bien d'autres.
Cliquez sur les boutons suivants pour voir le rendu en direct. Vous pouvez aussi éditer le code et voir le rendu en temps réel.
En savoir plus