Diagrammes Mermaid

Écrivez des organigrammes, diagrammes de séquence, graphiques à secteurs et diagrammes de Gantt en texte Mermaid : l’éditeur les dessine sous forme de blocs dans le document. Mermaid n’est pas inclus : votre page le charge, ou votre serveur produit le rendu.

Activation

Cette fonctionnalité est fournie par le plugin mermaiddiagram.js (également inclus dans plugins/all_plugins.js). L’élément de la barre d’outils est insertdiagram (infobulle « Diagram »). La barre par défaut le place dans le menu « More » (⋮) ; ajoutez insertdiagram à votre propre barre. Pour dessiner dans le navigateur, chargez Mermaid avant de créer l’éditeur :

<link rel="stylesheet" href="/richtexteditor/rte_theme_default.css" />
<script src="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js"></script>
<script src="/richtexteditor/rte.js"></script>
<script src="/richtexteditor/plugins/mermaiddiagram.js"></script>

<div id="div_editor1"><p>How a change ships:</p></div>
<script>
mermaid.initialize({ startOnLoad: false });
var editor1 = new RichTextEditor("#div_editor1", {
  toolbar: "custom",
  toolbar_custom: "{bold,italic,underline}|{insertdiagram}|{undo,redo}"
});
</script>

Origine du dessin

Le plugin ne charge rien depuis le réseau. Pour chaque diagramme, il utilise la première source disponible :

1. diagramResolver, votre fonction. Elle reçoit la source Mermaid et renvoie une Promise de { svg: "<svg…" } ou { imageUrl: "…" }. Utilisez-la pour produire le rendu côté serveur (avec Kroki ou mermaid-cli, par exemple).
2. window.mermaid sur la page (ou sa fenêtre parente). Le plugin prend en charge l’ancienne méthode mermaid.render qui renvoie une chaîne (versions 8 et 9) comme celle renvoyant une Promise (10 et ultérieures) ; ces pages ont été testées avec 11.4.1.
3. Aucune des deux : le bloc affiche la source comme du code et la boîte de dialogue indique « No Mermaid renderer detected on the page ». La source est conservée pour dessiner le diagramme ultérieurement.

Options

Option	Valeur par défaut	Fonctionnement
diagramResolver	null	Votre moteur de rendu, prioritaire sur window.mermaid. En cas de rejet, la source apparaît avec le message d’erreur.
diagramSamples	Quatre exemples : un organigramme (graph TD), un sequenceDiagram, un pie et un gantt	Boutons d’exemples de la boîte de dialogue. Chaque bouton affiche la première ligne de son exemple.
text_insertdiagram, text_insertdiagramtitle, text_insertdiagramlabel, text_insertdiagrampreview	"Diagram", "Insert / edit diagram", "Mermaid", "Preview"	Infobulle du bouton, titre de la boîte de dialogue et libellés.

Voici un résolveur côté serveur (l’URL est la vôtre) :

diagramResolver: function (source) {
  return fetch("/api/diagram", { method: "POST", body: source })
    .then(function (r) { return r.text(); })
    .then(function (svg) { return { svg: svg }; });
}

Utilisation

• Cliquez sur le bouton, appelez editor1.execCommand("insertdiagram"), ou choisissez « Diagram » dans le menu de commandes slash. Saisissez une source ou choisissez un exemple, puis Insert.
• Modification. Double-cliquez sur un diagramme pour rouvrir sa source dans la boîte de dialogue ; le bouton devient Update.
• Suppression. Survolez le bloc et cliquez sur le × rond dans son coin, ou appuyez sur Suppr ou Retour arrière avec le curseur dans le bloc.
• Erreurs. Si Mermaid ne peut pas analyser la source, l’aperçu affiche la source et le message de Mermaid en rouge (« Parse error on line 3 … »).
• editor1.renderDiagrams() redessine tous les blocs de diagramme et renvoie leur nombre. Appelez cette méthode après setHTMLCode avec un contenu sans dessin.

À savoir

• Le bloc enregistré conserve la source dans data-diagram et le dessin à l’intérieur (abrégé ici) :

  <div class="rte-mermaid" data-rte-diagram="1" data-diagram="graph LR
    A[Pull request] --&gt; B{Review}
    …" contenteditable="false" style=""><button type="button" class="rte-mermaid-remove" data-rte-mermaid-remove="1" aria-label="Remove diagram" title="Remove diagram">x</button><div class="rte-mermaid-render"><svg …>…</svg></div></div>

  Avec Mermaid, le dessin est du SVG en ligne (environ 4 KB pour l’organigramme ci-dessus) ; sans lui, un <pre class="rte-mermaid-src">.
• Le bouton de suppression × est enregistré avec le contenu. Masquez-le sur la page d’affichage, sinon un « x » apparaît.
• Après modification avec Update, son data-diagram est encodé deux fois en HTML (--> est enregistré sous la forme -->). L’éditeur lit les deux formes, mais votre code doit décoder la valeur une fois de plus.
• Le style du cadre n’existe que dans l’éditeur. Pour afficher les diagrammes enregistrés, masquez le bouton et dessinez depuis la source ; cette méthode a fonctionné pour les blocs nouveaux comme modifiés :

  <style>.rte-mermaid-remove { display: none; }</style>
  <script src="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js"></script>
  <script>
  mermaid.initialize({ startOnLoad: false });
  function decode(s) {
    return s.replace(/&quot;/g, '"').replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
  }
  document.querySelectorAll(".rte-mermaid[data-diagram]").forEach(function (block, i) {
    var target = block.querySelector(".rte-mermaid-render") || block;
    mermaid.render("saved-diagram-" + i, decode(block.getAttribute("data-diagram")))
      .then(function (result) { target.innerHTML = result.svg; });
  });
  </script>

• Les filtres de nettoyage doivent conserver les attributs de div ci-dessus et soit autoriser le SVG en ligne, soit le retirer puis redessiner depuis data-diagram comme indiqué.
• mermaid.min.js en version 11.4.1 pèse environ 2.6 MB. Chargez-le uniquement sur les pages qui éditent ou affichent des diagrammes, et hébergez-le vous-même si la page doit fonctionner hors ligne.

Voir aussi : démonstration des diagrammes, référence des éléments de la barre d’outils.