J’utilise beaucoup Mermaid — des organigrammes dans les documents de conception, des diagrammes de séquence dans les README, parfois un diagramme ER. Le diagramme en tant que code, c’est très pratique : versionnable, comparable, sans glisser-déposer de boîtes. Ce qui ne l’a jamais été, c’est le rendu visuel.
Les thèmes intégrés sont fonctionnels, mais les couleurs semblent datées. Mermaid possède pourtant un vrai système de thèmes — définissez theme: 'base' et remplacez ce que vous voulez dans themeVariables. Le problème, c’est le flux de travail : modifier un bloc frontmatter, relancer le rendu, plisser les yeux, deviner laquelle des 70 et quelques variables peint l’élément qui vous déplaît, recommencer.
Ma goutte d’eau, c’était un diagramme de séquence. J’ai changé primaryColor et les boîtes d’acteurs ont changé de couleur avec — il s’avère qu’elles relèvent de actorBkg. Dix minutes par couleur, l’essentiel à deviner, parce que le nom d’une variable ne dit presque rien de ce qu’elle peint.
Ce que je voulais était simple : modifier une variable, voir ce qu’elle fait. Immédiatement.
Alors j’ai construit mermaid.design — le code Mermaid à gauche, un aperçu en direct au centre, et tout le système de thèmes modifiable à droite. Chaque changement relance le rendu du diagramme sur place. La boucle de rétroaction est passée de minutes à quelques secondes.
Voilà pour la vitrine. Voici les modules qui font réellement gagner du temps.
La galerie : tous les types de diagrammes d’un coup d’œil
Ce qui agace avec les variables de thème, c’est qu’une même variable se comporte différemment selon les types de diagrammes. La page galerie rend les 84 modèles — organigrammes, diagrammes de séquence, de classes, d’états, ER et plus — en direct avec votre thème actuel. Modifiez une variable, faites défiler la galerie, et l’effet sur chaque type de diagramme est là, sous vos yeux. Plus besoin de basculer d’un type à l’autre pour vérifier. C’est ça, le temps gagné.
Variables de thème : valeurs par défaut et héritage à nu
Chacune des 73 variables affiche sa valeur par défaut issue du thème de base de mermaid. Celles que vous n’avez pas définies portent un badge AUTO avec la valeur que mermaid déduit au moment du rendu — et l’origine de cette valeur :
mainBkgsuitprimaryColorprimaryBorderColorest une couleur de bordure calculée à partir deprimaryColorsecondaryTextColorest l’inverse desecondaryColor(pour le contraste)actorBkgsuitmainBkg— ce qui explique le piège du début : changerprimaryColora déplacé mes boîtes d’acteurs parce qu’il existe une chaîne d’héritageprimaryColor→mainBkg→actorBkg
Une fois la chaîne visible, recolorer cesse d’être une devinette.
Préréglages : officiels, design, et d’autres à venir
21 préréglages, un clic pour appliquer : les 11 thèmes officiels de mermaid (default, neutral, dark, forest, base, plus les familles redux et neo de la v12) et 10 préréglages design que j’ai réglés à la main. Chacun montre un mini-aperçu en direct — et la collection continue de grandir.
Génération : une couleur primaire, toute une palette
Choisissez une seule couleur primaire de départ et le générateur fait ramper la luminosité dans l’espace HSL autour de sa teinte — une échelle de 8 teintes — pour déduire une palette complète, variante sombre incluse. Le moyen le plus rapide d’accorder un diagramme à votre marque.
Configuration de rendu : au-delà des couleurs
Les couleurs ne sont que la moitié. Mermaid compte 438 champs de configuration qui influencent le rendu, regroupés par type de diagramme en 34 groupes. Quelques exemples :
- Global :
fontFamily,fontSize,wrap(retour à la ligne automatique),look(classic ou handDrawn, façon dessin à la main) - Organigrammes :
flowchart.curve(style des courbes),flowchart.nodeSpacing/flowchart.rankSpacing,flowchart.diagramPadding - Diagrammes de séquence :
sequence.actorMargin,sequence.messageMargin,sequence.showSequenceNumbers(numérotation des messages),sequence.mirrorActors - Camemberts :
pie.textPosition,pie.donutHole,pie.legendPosition
Le groupe correspondant à votre type de diagramme actuel s’ouvre automatiquement.
Mode ASCII : le diagramme en texte
Le même diagramme peut se rendre en art ASCII — un clic pour copier, prêt pour les commentaires de code, les messages de commit ou les documents en texte brut. Il prend actuellement en charge cinq types de diagrammes : organigrammes, séquence, classes, états et ER. Le jeu de caractères peut être les box-drawing Unicode ou l’ASCII pur.
En résumé
La motivation derrière mermaid.design est simple : les couleurs officielles des thèmes sont difficiles à aimer, régler les themeVariables à la main prend du temps, et je voulais un endroit où chaque changement montre immédiatement son effet. Aujourd’hui, on y trouve des variables de thème éditables en direct avec valeurs par défaut et héritage visibles, une galerie qui montre tous les types de diagrammes d’un coup, des préréglages officiels et design, un générateur qui tire toute une palette d’une seule couleur primaire, 438 champs de configuration de rendu, et un mode ASCII qui transforme les diagrammes en texte.
Si vous aussi vous vous battez avec les thèmes Mermaid, essayez-le.