Comment contrôler la disposition des diagrammes dans Mermaid

Dans Mermaid 12, la clé de configuration layout détermine le moteur de disposition. ELK est désormais le moteur par défaut pour la plupart des diagrammes de type graphe. Pour retrouver l’ancien moteur, définissez layout: dagre dans le front matter ou dans mermaid.initialize().

Vous avez effectué la mise à jour et reconstruit votre site de documentation. Un flowchart auquel personne n’a touché présente maintenant une forme et des couleurs différentes. Une section de configuration propre à un type de diagramme, comme flowchart: { defaultRenderer: ... } reprise d’une ancienne réponse, ne corrigera pas le problème.

Cet article explique ce qui a changé, où définir la disposition, quel paramètre est prioritaire, comment régler ELK et pourquoi un retour en arrière peut sembler sans effet. Pour les bases des flowcharts, consultez créer des flowcharts pour vos workflows.

Qu’est-ce qui a changé dans Mermaid 12 ?

À partir de Mermaid 12, un diagramme qui ne précise pas de disposition est agencé par ELK au lieu de dagre. Un diagramme inchangé peut donc prendre une forme différente après la mise à jour. La page de configuration des dispositions recense sept types de diagrammes qui utilisent désormais ELK par défaut : flowchart, états, classes, entité-relation, exigences, cas d’utilisation et agentflow. ELK est livré avec le paquet principal et s’enregistre automatiquement. Les mindmaps utilisent toujours cose-bilkent par défaut, et tidy-tree est fourni par le paquet distinct @mermaid-js/layout-tidy-tree.

Les notes de version de mermaid@12.0.0 décrivent aussi un second changement. Le thème par défaut est désormais redux-color et le look par défaut est désormais neo. Ce changement concerne un ensemble plus large de types de diagrammes, listés dans la section des valeurs par défaut par diagramme de la page consacrée aux thèmes. Un diagramme en v12 peut donc changer d’aspect pour deux raisons distinctes : le moteur de disposition a changé, et le thème et le look ont changé.

Où définir la disposition : front matter, initialize() ou configuration par type ?

Vous pouvez définir la disposition Mermaid pour un seul diagramme ou pour tous les diagrammes d’un site. Vous pouvez aussi restreindre le thème et le look à un seul type de diagramme. En cas de conflit, le paramètre le plus spécifique l’emporte.

Les notes de version 12.0.0 donnent l’ordre de résolution suivant : d’abord le front matter ou la directive, puis initialize(), puis la valeur par défaut du type de diagramme, et enfin la valeur par défaut globale.

Voici comment rétablir complètement l’ancien rendu d’un seul diagramme :

---
config:
  layout: dagre
  theme: default
  look: classic
---
flowchart LR
  Request --> Auth{Valid token?}
  Auth -->|yes| Handler
  Auth -->|no| Reject

À l’échelle du site, le premier appel ci-dessous change uniquement le moteur : les nouvelles couleurs restent en place. Le second appel rétablit l’intégralité du rendu d’avant la version 12 :

mermaid.initialize({ layout: 'dagre' });

mermaid.initialize({ layout: 'dagre', theme: 'default', look: 'classic' });

Mermaid 12 permet aussi de restreindre theme, look et layout à un type de diagramme, dans la section de configuration de ce type. Une valeur ainsi restreinte l’emporte sur une valeur globale définie au même endroit. Supposons que vous vouliez passer tous les diagrammes sous dagre et rétablir l’ancienne apparence uniquement pour les diagrammes de classes. Laissez alors layout au premier niveau et placez theme et look dans la section class, comme le montre la page sur les diagrammes de classes :

mermaid.initialize({
  layout: 'dagre',
  class: { theme: 'default', look: 'classic' },
});

Le front matter l’emporte toujours sur mermaid.initialize(). Par exemple, un site définit layout: 'dagre' globalement, mais un diagramme déclare layout: elk dans son front matter. Ce diagramme est alors rendu avec ELK.

Quand la disposition ELK de Mermaid est-elle utile et comment la régler ?

Utilisez ELK pour les diagrammes volumineux ou chargés. Conservez dagre lorsqu’un petit diagramme s’affiche déjà correctement. La documentation de Mermaid présente ELK comme adapté aux graphes complexes et de grande taille. dagre reste disponible en tant que disposition hiérarchique historique. Si vos diagrammes s’affichaient bien avant la mise à jour, revenir à dagre est un choix raisonnable.

La section consacrée à la disposition dans la référence de syntaxe documente plusieurs clés de réglage d’ELK, dont celles-ci :

• mergeEdges fusionne les arêtes parallèles.
• nodePlacementStrategy accepte SIMPLE, NETWORK_SIMPLEX, LINEAR_SEGMENTS ou BRANDES_KOEPF. BRANDES_KOEPF est la valeur par défaut avec le preset default.
• nodePlacementAlignment définit l’alignement Brandes-Koepf (par exemple BALANCED ou NONE). Si vous l’omettez, l’alignement est déterminé par le preset.

---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: NETWORK_SIMPLEX
---
flowchart TD
  Build --> Test --> Deploy
  Build --> Lint --> Deploy

Les diagrammes qui utilisaient déjà ELK avant la v12 peuvent eux aussi changer, car le placement Brandes-Koepf équilibré est désormais la valeur par défaut. Le schéma des presets ELK liste quatre valeurs de preset : legacy, default, modelOrder et depthFirst. D’après ce schéma, depthFirst correspond à l’ancienne valeur par défaut, et legacy reproduit le rendu d’ELK antérieur à l’apparition des presets.

Le rendu d’ELK a également évolué au fil des versions 12.x :

• Mermaid 12.1.0 a ajouté orientFeedbackEdges, activé par défaut. Prenons un sous-graphe qui alimente un nœud, lequel renvoie une arête vers ce même sous-graphe. Cette arête de rétroaction est désormais tracée vers l’aval au lieu de contourner le sous-graphe.
• Mermaid 12.2.0 empêche ELK de redresser l’extrémité d’une arête lorsque cela placerait une étiquette par-dessus une autre arête.

config:
  layout: elk
  elk:
    preset: legacy
    orientFeedbackEdges: false

Quelles variantes d’ELK et quels algorithmes par sous-graphe pouvez-vous utiliser ?

En plus de layout: elk, la page Layouts de Mermaid recense six variantes d’ELK utilisables comme valeurs de layout : elk.stress, elk.force, elk.mrtree, elk.sporeOverlap, elk.box et elk.rectpacking.

---
config:
  layout: elk.mrtree
---
flowchart TD
  Root --> API
  Root --> Web
  API --> Workers

D’après les notes de version 12.0.0, elk.box et elk.rectpacking positionnent les nœuds sans router les arêtes. Leurs arêtes sont donc tracées en ligne droite, de centre à centre.

Un sous-graphe peut choisir son propre algorithme avec @{ algorithm: ... }. Selon les mêmes notes de version, les valeurs acceptées sont les six variantes ci-dessus, plus elk.layered et elk.radial. Ces notes précisent deux points sur ce mécanisme de surcharge. Mermaid ignore les valeurs non prises en charge en émettant un avertissement. Il utilise l’algorithme hérité dès que des arêtes franchissent la frontière du sous-graphe.

Pourquoi ma correction de disposition ne fonctionne-t-elle pas ?

La plupart des retours en arrière ratés s’expliquent par l’une de ces cinq causes. Vérifiez-les dans cet ordre :

1. Vous utilisez encore defaultRenderer. La page de syntaxe des flowcharts indique que cette option a été supprimée des sections flowchart, class et state en v12. Utilisez plutôt layout.
2. Vous avez défini uniquement layout: dagre. Le thème redux-color et le look neo restent actifs. Définissez les trois clés.
3. Le front matter écrase votre initialize(). Retirez layout du front matter de ce diagramme.
4. Un nom de disposition est mal orthographié ou non enregistré. D’après les notes de version, Mermaid se rabat alors sur dagre en émettant un avertissement, sans lever d’erreur. Consultez la console.
5. Vous utilisez le build tiny. Reportez-vous à la section suivante.

Abandonner defaultRenderer ne demande qu’une ligne de modification :

// Before (removed in v12)
mermaid.initialize({ flowchart: { defaultRenderer: 'elk' } });

// After
mermaid.initialize({ layout: 'elk' });

Si votre plateforme de documentation n’est pas encore passée à la v12, ces clés peuvent encore se comporter à l’ancienne. Consultez la documentation de votre plateforme.

Pourquoi le build tiny se rabat-il sur dagre ?

Le build tiny de Mermaid n’inclut pas ELK. Tout diagramme qui demande ELK y est donc rendu avec dagre. Le paquet @mermaid-js/layout-elk reste publié pour ce cas de figure. Suivez les étapes d’enregistrement décrites dans la section ELK and the tiny build de la documentation d’utilisation. Avec le build standard, les appels existants à registerLayoutLoaders fonctionnent toujours mais ne sont plus nécessaires : vous pouvez les supprimer.

Conclusion

Lorsqu’un diagramme a changé après la mise à jour vers Mermaid 12, deux causes sont presque toujours en jeu : le moteur de disposition ELK, et le nouveau thème et le nouveau look. Déterminez d’abord ce que vous voulez retrouver. Pour récupérer uniquement les anciennes formes, définissez layout: dagre. Pour retrouver le rendu complet d’avant la version 12, définissez layout: dagre, theme: default et look: classic. Recherchez ensuite dans votre configuration les éventuels paramètres defaultRenderer résiduels. Vérifiez aussi qu’aucun front matter ne vient écraser votre choix global.

FAQ

Le mot-clé de diagramme flowchart-elk fonctionne-t-il encore dans Mermaid 12 ?

Oui. Les notes de version de Mermaid 12.0.0 indiquent que flowchart-elk fonctionne toujours en tant que mot-clé de diagramme explicite. C'est l'option defaultRenderer qui a changé. Mermaid l'ignore au lieu de la rejeter : une configuration qui la définit encore ne génère aucune erreur, mais n'a aucun effet. Un diagramme qui obtenait sa disposition ELK grâce à une valeur defaultRenderer de 'elk' dans la section flowchart doit désormais définir layout: elk.

L'intégration d'ELK alourdit-elle le chargement de Mermaid 12 ?

Seul le build en fichier unique grossit de façon notable. Dans les builds ESM, ELK constitue un chunk distinct, chargé uniquement lorsqu'un diagramme l'utilise. Selon les notes de version 12.0.0, le build IIFE, mermaid.min.js, intègre ELK directement et gagne environ 500 ko compressés avec gzip. Le build tiny n'inclut pas ELK et conserve la même taille. Il traite les demandes de disposition ELK avec dagre.

Peut-on définir les options de réglage d'ELK pour tout le site plutôt que dans le front matter de chaque diagramme ?

Oui. elk est une propriété de premier niveau du schéma de configuration de Mermaid. Vous pouvez donc la transmettre à mermaid.initialize() à côté de layout, par exemple layout: 'elk' avec un objet elk contenant mergeEdges: true et nodePlacementStrategy: 'NETWORK_SIMPLEX'. Une directive %%{init}%% accepte le même objet elk pour un seul diagramme. Le front matter d'un diagramme donné continue de l'emporter sur les valeurs définies pour tout le site.