Diagrammes (Mermaid)

Comment ça marche

Diagrammes Mermaid. Une clôture ```mermaid contenant un organigramme (flowchart/graph, dans les quatre directions), un diagramme de séquence (sequenceDiagram) ou un camembert (pie) est dessinée comme diagramme en mode lecture, dans le fichier exporté et dans les réponses d’Interroger les notes — d’où viennent la plupart des diagrammes. Le dessin suit le thème de la note (encre, papier et accent) : il s’accorde donc au texte autour dans les deux thèmes. En édition formatée — le mode par défaut — le diagramme est lui aussi dessiné, avec la barre du bloc par-dessus (copier, modifier, supprimer). Modifier ouvre en bas une barre contenant la source : la note est verrouillée tant qu’elle est ouverte et le dessin se refait pendant la frappe ; fermer applique (il n’y a ni enregistrer ni annuler), Ctrl+Z défait toute la modification en une étape et vider le champ supprime le bloc. En mode divisé, cliquer sur le diagramme amène le curseur jusqu’à la clôture dans le texte brut. Dans l’éditeur de texte tout reste du texte : Ctrl+E affiche le diagramme. Dans un élément de liste, le diagramme — ainsi que la structure SMILES, la formule en bloc, [files] et ![[note]] — reste du texte en édition formatée et apparaît dessiné en mode lecture : là, la puce de l’élément n’aurait aucun moyen de revenir dans le fichier.

Les sous-graphes (subgraph … end, imbriqués compris) deviennent des cadres avec titre, et les arêtes traversent la bordure en partant du vrai nœud ; l’id d’un sous-graphe peut aussi être une extrémité d’arête (sub --> X). Les couleurs déclarées par l’auteur s’appliquent : classDef, class, :::classe et style (remplissage, contour, épaisseur, pointillés et couleur du texte). Pour en commencer un, utilisez Insérer → Diagramme (Mermaid) dans la barre de la note : il pose un squelette prêt du type choisi. Le menu propose directement les six les plus utilisés ; Tous les diagrammes… ouvre un sélecteur avec les 33, groupés par usage, avec une recherche (par nom ou par ce que le diagramme montre) et l'aperçu dessiné de chacun — ce sont 33 dessins, et voir le dessin décide plus vite que lire le nom. Le frontmatter du diagramme — le bloc entre --- avant la première ligne — est lu lui aussi : le title devient le titre dessiné au-dessus du dessin (un title dans le corps l’emporte) et les clés de config que LightNote connaît parviennent au diagramme (gitGraph.mainBranchName, gantt.displayMode, et celles de packet : bitsPerRow, bitOrder: descending — qui met la rangée en miroir — et showBits: false) ; ce qu’il ne connaît pas est ignoré, sans refuser la note.

Séquence, entités, classes et états

Dans le diagramme de séquence on a participant/actor (avec as), les formes de flèche (->>, -->>, -x, -)), l’activation (+/- et activate/deactivate), les notes (Note left of/right of/over), les blocs loop/alt/else/opt/par et autonumber. Ce qui n’est pas encore dessiné — les autres types de diagramme — continue d’apparaître comme bloc de code ; direction à l’intérieur d’un sous-graphe et linkStyle sont ignorés. La syntaxe de nœud de Mermaid v11 (A@{ shape: rounded, label: "texte" }) est lue, et le catalogue de formes de la v11 est dessiné : doc, lin-doc, docs, tag-rect, win-pane, hourglass, bolt, flag, das… — chacune est le symbole que son nom annonce, et aucune ne devient un rectangle, car un rectangle à la place d’un document serait un autre diagramme. Un nom que Mermaid n’a pas fait redevenir le diagramme un bloc de code, avec la ligne indiquée. L’identifiant d’arête (A e1@--> B) et e1@{ animate: true } sont acceptés et ignorés : l’animation n’est pas dessinée. Un participant typé (participant DB@{ "type": "database" }) dessine le symbole UML au-dessus de la ligne de vie — boundary, control, entity, database, queue et collections —, et l’"alias" déclaré là vaut comme as.

Le erDiagram est également dessiné : chaque entité devient une boîte avec ses attributs et la cardinalité apparaît aux deux extrémités de la relation (||--o{, }o--||, |o, |{) ; -- est une relation identifiante et .. non identifiante. L'alias p[Personne] nomme la boîte sans changer l'id que les relations citent. Le subgraph … end vaut ici aussi : les entités à l’intérieur obtiennent un cadre avec titre, les sous-graphes s’imbriquent et l’identifiant du cadre peut être une extrémité de relation (CLIENT ||--o{ Ventes : passe), rejoignant la frontière plutôt qu’une entité de ce nom.

Le classDiagram de même : une boîte à trois compartiments (nom, attributs et méthodes, séparés par les parenthèses de la méthode), <<interface>> sur sa propre ligne, namespace comme boîte et les six relations (<|--, *--, o--, -->, ..>, ..|>). Attention au sens : dans A <|-- B le triangle est sur A — celui qui hérite est B. La cardinalité entre guillemets apparaît aux deux extrémités ("1" --> "*"). Les génériques Liste~T~ s'affichent comme Liste<T>, dans les membres aussi. L’interface sucette (bar ()-- foo) dessine le cercle en haut du cadre du côté où se trouve le () — et de ce côté seulement —, la relation venant toucher le cercle ; les namespace s’imbriquent aussi, et après le } interne une classe revient au namespace extérieur.

Le stateDiagram-v2 dessine la machine à états : [*] est le début (disque plein) et la fin (disque avec anneau), state X { … } devient une boîte, <<fork>>/<<join>> une barre et <<choice>> un losange. Un -- à l'intérieur d'un état composite sépare les régions concurrentes, marquées par un trait pointillé.

Frise, parcours, quadrants et Gantt

La timeline est également dessinée : chaque période devient une colonne de la frise, avec ses événements empilés en dessous, et section regroupe les époques en bandes colorées. Les deux écritures pour plusieurs événements fonctionnent — deux-points sur la même ligne (2004 : Facebook : Google) et continuation à la ligne suivante (: autre événement) —, et ici toute ligne qui n’est pas title, section ou direction est du texte libre. direction TD (frise verticale) n’est pas encore dessiné et conserve le bloc de code.

Le journey (parcours utilisateur) est dessiné lui aussi : chaque tâche devient une boîte sur l’axe du parcours, et la note de 1 à 5 déplace son visage vers le haut ou vers le bas — c’est le profil qu’ils forment que le diagramme existe pour montrer. section regroupe les phases, et les acteurs deviennent des marqueurs colorés sur la tâche, avec une légende à gauche. Ici la grammaire est stricte (Tâche : note : Acteur, Acteur), contrairement à celle du timeline : sans le couple nom/note il n’y a nulle part où poser le visage, donc une ligne mal formée — ou une note hors de 1 à 5 — refuse le diagramme en indiquant la ligne.

Et le quadrantChart dessine le plan des quatre quadrants : x-axis et y-axis nomment les extrémités de chaque axe (le côté droit du --> est facultatif), quadrant-1 à quadrant-4 étiquettent les régions, et chaque point s’écrit Nom : [x, y], avec x et y de 0 à 1. Attention à la numérotation : c’est celle du plan cartésien, pas celle de la lecture — quadrant-1 est celui d’en haut à droite, puis on tourne dans le sens antihoraire ; y = 1 est en haut. La couleur et le rayon d’un point peuvent venir directement (P: [0.5, 0.5] radius: 10, color: #109060) ou d’une classe (P:::classe plus classDef), et le style direct l’emporte sur la classe. Une coordonnée hors de 0 à 1 refuse le diagramme en indiquant la ligne au lieu d’être rognée — c’est la position dans le plan, et la rogner placerait le point dans un quadrant que vous n’avez pas écrit.

Le gantt dessine le planning : dateFormat indique le format des dates que vous écrivez (par défaut YYYY-MM-DD) et axisFormat celui des étiquettes de l’axe (%d/%m) ; section regroupe les tâches en bandes. Chaque tâche s’écrit Texte : marqueurs, id, début, fin — les marqueurs done, active, crit et milestone viennent en premier et se combinent, le début est une date ou after autreId, et la fin est une date, une durée (5d, 2w, 3h, 45m) ou until autreId. Avec un seul champ, la tâche commence là où la précédente s’est terminée.

after peut citer une tâche déclarée plus bas dans la note ; en revanche un id qui n’existe nulle part — ou une dépendance circulaire — refuse le diagramme en indiquant la ligne, au lieu de poser la barre au jour d’aujourd’hui. excludes weekends (ou excludes monday, ou une date) repousse la fin de chaque tâche des jours exclus, et change donc la longueur des barres ; includes 2026-03-07 l’emporte sur le week-end, pour dire que ce samedi-là on travaille. Le jalon (milestone) apparaît sous forme de losange, et todayMarker off retire la ligne du jour. Le displayMode compact empile plusieurs tâches sur la même ligne, et ici une tâche ne partage la ligne que si rien de ce qu’elle occupe ne touche ce qui s’y trouve déjà — l’étiquette comprise. Le marqueur vert (Ouverture : vert, v1, 20:15, 0m) dessine l’instant comme une ligne verticale qui traverse tout le graphique, sans occuper de ligne, et son étiquette passe sous l’axe. Le dateFormat X (ou x) lit la date comme un temps Unix en secondes (ou millisecondes), et sur l’axe %s/%Q la réécrit. Un tickInterval que Mermaid ne connaît pas (1decade) est ignoré en silence, comme là-bas, et l’axe revient à l’automatique.

Carte mentale, exigences, Git et C4

Dans la mindmap la hiérarchie vient de l’indentation : le niveau d’un élément est la colonne où son texte commence, sans accolades ni flèches (une tabulation compte jusqu’au prochain arrêt de 4, comme dans un éditeur). Le premier élément est la racine — un second élément dans sa colonne serait une seconde racine, et le diagramme est alors refusé en indiquant la ligne. Chaque élément peut déclarer sa forme : [carré], (arrondi), ((cercle)), {{hexagone}}, ))explosion(( et )nuage( ; sans délimiteur il sort arrondi. ::icon(...) et :::classe sont reconnus et ignorés (nous n’embarquons pas la police d’icônes, et la classe renvoie à un CSS externe qui n’existe pas ici). Le dessin est à deux côtés — la racine au centre, les branches réparties à gauche et à droite —, chaque branche avec sa propre couleur dont héritent les descendants, et le rameau s’affine avec la profondeur.

C’est un arbre, et non une simulation de forces comme dans mermaid : dans une carte mentale la hiérarchie est le contenu, elle doit donc se lire à la position — et, le dessin étant refait au changement de thème, une disposition convergeant depuis des positions aléatoires réorganiserait toute la carte à chaque fois.

Le treeView (treeView-beta) dessine l’arborescence de dossiers d’un projet, et accepte les deux graphies : l’indentation (ce qu’on tape) et les caractères mêmes de la commande tree (├──, │, └──), ce qui permet de coller la sortie du terminal directement dans la note — là, l’indentation ne suffit pas, car │ et une espace occupent la même colonne et seul le premier dit que la branche continue. La barre finale marque le dossier (src/), un nom avec espaces se met entre guillemets, ## texte accroche un commentaire en fin de ligne et :::highlight met le nom en valeur. icon(...) est reconnu et ignoré, comme l’::icon() de la carte mentale : les paquets d’icônes viennent d’Iconify par JavaScript, et Mermaid lui-même ne les dessine pas par défaut.

L’ishikawa (ishikawa-beta) dessine le diagramme en arêtes de poisson d’une analyse de causes : le premier élément est l’EFFET (la tête, à droite), le niveau suivant les catégories (les arêtes) et les deux du dedans les causes et sous-causes. Trois niveaux — un quatrième refuse le diagramme en indiquant la ligne, car il n’existe pas dans Mermaid. Les arêtes alternent au-dessus et au-dessous de l’axe, ce qui permet à deux catégories voisines de tenir sans que le texte de l’une tombe sur celui de l’autre, et l’ordre dans lequel vous écrivez les causes se lit de haut en bas des deux côtés.

Le venn (venn-beta) dessine des ensembles qui se croisent : set A["Souhaitable"] en déclare un, union A,B["Réalisable"] nomme la région commune (une union se nomme par les ensembles qu’elle croise) et text A1["React"], juste en dessous de l’un d’eux, place un élément dans cette région. Ce sont jusqu’à trois ensembles, et le quatrième refuse le diagramme en indiquant la ligne : avec quatre cercles, aucune disposition ne produit toutes les régions, et en dessiner un "presque juste" cacherait une région que vous avez déclarée. Le :nombre après l’étiquette (set A["Alpha"]:20) met le cercle à l’échelle — l’aire suit le nombre — et non les intersections : un Venn à intersections proportionnelles est un autre diagramme (Euler), qui demande une optimisation numérique. style A fill:#ff6b6b peint un ensemble, et avec une virgule (style A,B color:#333) cela vaut pour l’union de ces ensembles.

Le cynefin (cynefin-beta) dessine le cadre de Snowden pour classer les décisions : les cinq domaines ont un nom fixe — complex, complicated, chaotic, clear et confusion — et une position fixe (les quatre quadrants, la confusion au milieu) ; ce que vous choisissez, c’est ce qui va dedans. Chaque élément va entre guillemets, un par ligne, et complex --> complicated : "Motif identifié" dessine la transition entre deux domaines. Un nom hors des cinq refuse le diagramme en indiquant la ligne et en donnant la liste. La frontière entre clear et chaotic sort ondulée : dans le modèle c’est une falaise, et la forme le dit — ici l’onde est toujours la même, pour que la note ne change pas de dessin à chaque ouverture.

Le swimlane (swimlane-beta) dessine un processus en couloirs, un par responsable : la syntaxe est celle de l’organigramme (mêmes formes, flèches, étiquettes et classDef), et chaque subgraph cesse d’être un cadre pour devenir un couloir. Chaque nœud doit se trouver dans l’un d’eux — un nœud isolé refuse le diagramme, car rien ne dirait à qui appartient la tâche — et un couloir dans un couloir refuse aussi. Avec LR les couloirs sont des lignes et le flux va vers la droite ; avec TB ce sont des colonnes et le flux descend. La position le long du flux vient du plus long chemin jusqu’à chaque tâche, et la bande est celle du propriétaire : une tâche ne quitte jamais son couloir, même si cela rendait le dessin plus compact.

L’agentflow (agentflow-beta) dessine un flux avec des agents d’IA, et c’est un autre vocabulaire pour l’organigramme : les flèches sont les mêmes, flow id["Nom"] … end joue le rôle de subgraph (et s’imbrique), global … end contient ce que tous les agents consultent, et connector id["Nom"] déclare un système extérieur. Ce qui change vraiment, c’est la forme, qui dit le rôle de chaque étape : @{ shape: input }, task, tool (appel d’outil), decision, refdoc (document de référence) et action (action finale). Reliez le document avec -.-, sans flèche : il est consulté, ce n’est pas une étape. Les clés qui décrivent l’agent par écrit (instruction, params, returns, connectorRef, protocol, endpoint) sont lues et ignorées au dessin. Ces noms de forme ne valent qu’ici — dans un flowchart ils refusent, car Mermaid ne les a pas non plus là-bas.

L’usecase (usecase-beta) dessine le diagramme de cas d’utilisation UML : ce qui est déclaré par actor devient le bonhomme, et tout le reste est un cas d’utilisation, dessiné en ellipse — c’est la distinction que ce type existe pour montrer. Le cas d’utilisation s’écrit Id("Libellé"), Id[Libellé], juste Id ou juste le texte entre guillemets ; systemBoundary "Nom" … end est la frontière du système et note for X "texte" accroche une note. Les relations sont celles d’UML : --> associe, --|> est la généralisation (le triangle creux est du côté du général) et A ..> : include B — avec la cible après les deux-points — dessine l’« include » pointillé, de même pour extend. Ce qui décrit l’acteur sans changer le dessin (type, business, icon) est lu puis ignoré, et le <<Stéréotype>> passe dans le libellé. Le nœud json n’est pas encore dessiné et conserve le bloc de code : c’est un bloc de plusieurs lignes contenant l’arbre de la donnée, et là le JSON reste lisible comme texte.

Le wardley (wardley-beta) dessine une carte de Wardley : un plan dont l’axe vertical est la visibilité pour l’utilisateur (le haut, c’est ce qu’il voit) et l’axe horizontal l’évolution, de Genesis à Commodity.

Attention à l’ordre de la paire : component Thé [0.63, 0.81] vaut [visibilité, évolution] — le premier nombre est l’axe vertical, et lu à l’envers la carte se dessine quand même et se met à raconter une autre stratégie. L’anchor est l’utilisateur en haut, A -> B relie la chaîne (un nom peut contenir des espaces, avec ou sans guillemets), A +> B est un flux (plus épais ; +<> dans les deux sens et +'texte'> avec libellé) et evolve Bouilloire 0.62 dessine la flèche pointillée jusqu’où la pièce doit aller. Valent aussi evolution (renomme les étapes de l’axe), size, (build)/(buy)/(outsource)/(market), (inertia) (la barre de résistance), label [dx, dy], pipeline X { … }, note, accelerator/deaccelerator et les annotation numérotées avec la légende annotations.

L’eventmodeling dessine un event modeling : une frise en trois couloirs — l’écran en haut, la commande (et le modèle de lecture) au milieu, l’événement en bas. Chaque ligne s’écrit tf 02 cmd AjouterArticle : le nombre est l’instant (la colonne) et le mot du milieu le type, qui choisit le couloir — ui, cmd/command, pcr/processor, rmo/readmodel, view et evt/event (les formes longues valent pareil). Le couloir ne se déclare pas : c’est la méthode. Le rf (resetframe) ouvre une nouvelle tranche, avec un séparateur pointillé — c’est là que l’histoire recommence. Le schéma du cadre va entre accolades ({ description: string }) ou par référence ([[Donnees]]) à un bloc data Donnees { … }, qui peut venir après ; et ->> 02 ->> 03 relie le cadre aux instants qui l’alimentent, par numéro.

Le railroad (railroad-ebnf-beta, -abnf-beta, -peg-beta ou railroad-beta) dessine une grammaire en rails de chemin de fer : chaque règle devient un chemin que l’on suit du doigt, et ce qu’on peut écrire est ce qu’on peut parcourir. La règle s’écrit nom = expression ; (ou nom <- … ; en PEG) et peut tenir sur plusieurs lignes : elle se ferme au ;. Le texte entre guillemets est un terminal (dessiné en capsule) et un nom seul est une autre règle (rectangle) ; | (ou /) est un choix, ? optionnel, + une fois ou plus, * zéro fois ou plus, et ( ), [ ] et { } groupent, rendent optionnel et répètent. L’ABNF met la répétition avant (1*( ALPHA / "-" ), *DIGIT), le PEG accepte les prédicats !x et &x — qui passent dans le libellé, car ils ne consomment rien — et railroad-beta accepte l’écriture par fonctions (sequence(choice(terminal("+"), …))). Les quatre aboutissent au même dessin : le contournement par le haut est l’optionnel et la boucle par le bas, flèche vers l’arrière, la répétition.

Le requirementDiagram dessine exigences et éléments comme des boîtes à compartiments : le type déclaré (requirement, functionalRequirement, performanceRequirement, interfaceRequirement, physicalRequirement, designConstraint) apparaît entre guillemets au-dessus du nom, et les champs id, text, risk et verifymethod deviennent des lignes — dans un element, type et docref. Les relations (satisfies, traces, derives, verifies, refines, copies, contains) s'écrivent a - satisfies -> b ou en forme miroir b <- satisfies - a, et dans celle-ci le premier nom est la destination. Seul contains est un trait plein, avec le symbole du côté de celui qui contient ; les autres sont en pointillé avec la flèche à la destination. Un nom avec espace se met entre guillemets droits.

Le gitGraph dessine l'historique d'un dépôt : chaque commit avance dans le temps, branch nom ouvre une nouvelle voie et y travaille aussitôt (comme git switch -c), checkout revient à une autre et merge réunit les deux. Les attributs prennent deux-points : commit id: "texte" tag: "v1" type: HIGHLIGHT (aussi REVERSE), et branch nom order: 2 change l'ordre des voies ; cherry-pick id: "…" exige l'id d'un commit qui existe. La forme dit le type — disque plein pour le commit ordinaire, carré pour celui mis en avant, cercle barré d'un X pour le commit annulé, double anneau pour la fusion et cercle coupé pour le cherry-pick —, car dans un thème où deux tons de la palette se ressemblent, seule la forme les sépare. LR: (par défaut), TB: et BT: tournent l'axe du temps. Un checkout/merge vers une branche qui n'existe pas refuse le diagramme en indiquant la ligne, au lieu de créer une voie que vous n'avez pas demandée.

La famille C4 (C4Context, C4Container, C4Component, C4Dynamic et C4Deployment) est dessinée elle aussi, et là tout est macro : il n'y a aucune flèche dans la syntaxe. Chaque élément devient une boîte avec le type entre guillemets, le nom en gras et la description en dessous : Person(alias, "Nom", "Description"), System, Container, Component et les variantes Db, Queue et _Ext. Dans Container et Component le troisième argument est la TECHNOLOGIE (Container(app, "App", "C++/Qt", "ce qu'il fait")) ; dans les autres c'est déjà la description. Les frontières (Boundary, Enterprise_Boundary, System_Boundary, Container_Boundary et le Node de C4Deployment) ouvrent une accolade et deviennent une boîte à titre, imbriquées comprises. Le lien est Rel(a, b, "libellé", "technologie") ; BiRel met une flèche aux deux bouts et Rel_Back pointe en arrière. Le C4Dynamic numérote les relations dans l'ordre où elles apparaissent. Les indications de position (Rel_U, Rel_D, Rel_L, Rel_R) et les Update…Style sont acceptés et ignorés : l'agencement vient du même layout que les autres diagrammes, et la couleur vient du thème de la note. Une relation citant un alias jamais déclaré refuse le diagramme en indiquant la ligne, au lieu d'inventer une boîte que vous n'avez pas écrite.

Tableau, graphiques et paquet

Dans le kanban l'indentation est la syntaxe, sur deux niveaux : celui du dehors est la voie et celui du dedans la carte (id[Libellé], ou juste le texte). Le @{ ticket: LN-9, assigned: 'ana', priority: 'High' } après une carte n'entre pas dans son texte : le ticket et le responsable vont dans un pied de page à eux, et la priorité (Very High, High, Low, Very Low) devient la couleur du bandeau du bord gauche, sur une échelle du chaud au froid. Toutes les voies se terminent sur la même ligne, et une voie sans carte reste affichée — c'est elle qui montre la colonne vide. C'est un tableau dessiné, pour expliquer un flux dans une note ; le tableau sur lequel on travaille, avec des cartes que l'on déplace, c'est le panneau Tâches de l'application.

Le xychart (xychart-beta) dessine des barres et des lignes sur deux axes : x-axis "Titre" [jan, fév, mar] donne les catégories — un nom avec espace ou virgule se met entre guillemets droits —, y-axis "Titre" 0 --> 100 fixe l'échelle et chaque bar [10, 40, 90] ou line [20, 30, 80] ajoute une série, avec une valeur par catégorie, dans l'ordre où elles ont été déclarées. Une série avec plus ou moins de valeurs refuse le diagramme en indiquant la ligne : les barres glisseraient sur d'autres catégories et le graphique affirmerait autre chose. Sans y-axis, l'échelle vient des données et commence à zéro tant qu'elles ne descendent pas plus bas — commencer à la plus petite valeur exagère l'écart entre les barres, et personne ne l'a demandé ; avec une plage déclarée, une valeur hors plage est refusée plutôt que de déborder du cadre.

x-axis accepte aussi une plage continue (0 --> 100), et sans lui les catégories sont les indices. Deux séries de barres apparaissent côte à côte, et non superposées comme dans mermaid — superposées, celle du fond disparaît. xychart-beta horizontal n'est pas encore dessiné et garde le bloc de code, car le dessiner à la verticale livrerait le graphique transposé. Une série peut avoir un nom (bar "Ouverts" [10, 40], line "Fermés" [20, 30]) : les noms forment une légende au-dessus du plan, chacun avec la forme de sa série — barre pleine, ligne avec point —, car la couleur seule ne les distingue pas. Et dans une série en ligne une valeur peut porter une étiquette ([540 "PaLM", 65]), dessinée au-dessus du point ; sur les barres l’étiquette est ignorée, comme dans Mermaid.

Le radar (radar-beta) dessine le profil d'une ou plusieurs courbes sur des axes partant du centre : axis a["Libellé"], b, c déclare les axes — la ligne peut se répéter — et curve x["Nom"]{80, 60, 90} donne une valeur par axe, dans l'ordre où ils ont été déclarés ; la forme nommée ({a: 80, c: 90, b: 60}) vaut aussi. Attention au sens : le premier axe pointe vers le haut et le tour se fait dans le sens horaire. max et min fixent l'échelle — sans max, elle vient de la plus grande valeur lue — et une valeur hors échelle refuse le diagramme en indiquant la ligne, plutôt que d'être rognée ; ticks change le nombre d'anneaux, graticule circle les rend ronds et showLegend false retire la légende. Une courbe avec plus ou moins de valeurs que d'axes est refusée elle aussi : ce ne serait pas un dessin incomplet, mais un autre dessin.

Le packet (packet-beta) dessine la carte des bits d'un paquet : chaque champ s'écrit 0-15: "Libellé", et la plage est fermée aux deux bouts — 0-15 font seize bits. Un bit seul s'écrit 4: "Libellé", et la forme relative +16: "Libellé" prend les seize suivants, pour ne pas avoir à tout recompter en insérant un champ au milieu. Les champs doivent être contigus : un trou ou un chevauchement refuse le diagramme en indiquant la ligne, car l'un comme l'autre décalerait en silence tout ce qui suit. Une rangée contient 32 bits, et un champ qui franchit le passage à la ligne apparaît sur les deux, avec le libellé dans la partie la plus large ; les nombres au-dessus de la grille marquent où commence chaque champ, plus le dernier bit de chaque rangée.

Grille, aires, architecture, flux et ZenUML

Le block (block-beta) dessine une grille de cases, et la position y est l'ordre dans lequel vous les avez écrites : columns 3 fixe le nombre de colonnes — sans lui, tout tient sur une seule rangée —, chaque case accepte les formes de l'organigramme (a["Libellé"], b(("cercle")), c{"losange"}), a:2 fait occuper deux colonnes à la case et space (ou space:2) laisse un trou. block:id … end imbrique une grille dans une autre, avec son propre columns, et devient une case autour. Les flèches sont celles de l'organigramme (a --> b, libellée en a -- "texte" --> b), mais ici elles ne font que citer des blocs déjà déclarés : une flèche vers un nom qui n'existe pas refuse le diagramme en indiquant la ligne, plutôt que d'inventer une case dans une cellule que vous n'avez pas écrite. L'écart entre les colonnes s'agrandit jusqu'à ce que le libellé de la flèche tienne, pour qu'il ne touche pas la case voisine. La flèche de bloc (a<["Aller"]>(right)) est un cadre en forme de flèche : les directions vont entre parenthèses (right, left, up, down, ou x pour les deux horizontales et y pour les deux verticales) et se combinent ((x, down)) ; une direction inventée refuse le diagramme en indiquant la ligne, plutôt que de devenir une flèche quelconque.

Le treemap (treemap-beta) dessine une carte de surfaces : chaque rectangle a une aire proportionnelle à sa valeur, et l'indentation imbrique, à profondeur libre. La feuille déclare la valeur ("Nom" : 12) et la section ne déclare rien — la sienne est la somme des enfants, et un total propre permettrait un rectangle qui ment sur ses propres parties ; c'est donc refusé, avec la ligne indiquée. Un nom avec espace ou deux-points se met entre guillemets droits ; classDef et :::classe donnent la couleur. La disposition est le squarified, qui garde les rectangles proches du carré : découper toujours sur le même axe produirait des bandes qu'on ne compare pas à l'œil, et comparer des aires est la seule chose que fait ce type. Le libellé et la valeur n'apparaissent que s'ils tiennent entiers dans le rectangle : coupés par le bord, ils n'apprendraient rien.

L'architecture (architecture-beta) dessine des services et les liens entre eux : service api(server)[API] déclare un composant, group nuage(cloud)[Nuage] ouvre une frontière, le suffixe in nuage place le service dedans (les groupes s'imbriquent) et junction j crée un coin pour plier un lien.

C'est le côté du lien qui décide de la position : a:R -- L:b pose la droite de a contre la gauche de b, donc met b à droite de a ; L, R, T et B sont acceptés, et la pointe apparaît du côté du < ou du > (-->, <-->, ou -- sans pointe). Le suffixe {group} sur une extrémité envoie la ligne vers la frontière du groupe plutôt que vers la case à l'intérieur. Les icônes sont les cinq que Mermaid intègre — cloud, database, disk, internet et server — et tout autre nom refuse le diagramme en indiquant la ligne et en nommant celles qui existent. Les autres (logos:aws-lambda et compagnie) viennent d'Iconify et n'apparaissent que là où celui qui publie la page enregistre le paquet en JavaScript, ce que GitHub lui-même ne fait pas : les accepter ici livrerait un dessin qui ne se reproduit nulle part ailleurs. L’align row a b c (ou align column) place les membres cités sur la même rangée — ou dans la même colonne —, et un nom qui n’existe pas refuse le diagramme en indiquant la ligne, plutôt que de laisser la disposition telle quelle sans dire pourquoi.

Le sankey (sankey-beta) dessine un diagramme de flux où l'épaisseur du ruban est la valeur : le corps ne contient aucune flèche — c'est un CSV à trois colonnes (source,cible,valeur), un lien par ligne, et c'est la répétition d'un nom aux deux bouts qui enchaîne le flux. Une étiquette contenant une virgule va entre guillemets droits, et un guillemet à l'intérieur s'écrit doublé ("Coût ""fixe""") ; la même paire source/cible répétée s'additionne. La barre d'un nœud a la hauteur du plus grand des deux totaux, entrant et sortant, pour que les rubans sortants d'un nœud qui distribue plus qu'il ne reçoit ne débordent pas. Les colonnes viennent du plus long chemin jusqu'à chaque nœud, et ce qui n'a pas de sortie va dans la dernière colonne. Une valeur inférieure ou égale à zéro, un lien d'un nœud vers lui-même et un cycle refusent le diagramme en indiquant la ligne — dans un cycle il n'y a pas de plus long chemin, et couper un lien pour pouvoir dessiner montrerait un flux que vous n'avez pas écrit. Il n'y a pas de title ici : le corps est du CSV pur, et l'accepter dessinerait bien dans LightNote et serait une erreur de syntaxe dans Mermaid.

Le zenuml est une autre syntaxe pour le même dessin — un diagramme de séquence —, écrite comme du code plutôt qu'avec des flèches. L'appel synchrone ne nomme que la cible (Magasin.enregistrer(article)) et l'expéditeur est le bloc qui l'entoure : dans Magasin.enregistrer() { Stock.reserver() }, c'est le Magasin qui appelle le Stock. Au niveau extérieur, l'appelant est le démarreur — @Starter(Ana) le nomme, et sans lui un User en bonhomme-bâton est utilisé, qui n'apparaît que si un appel en a besoin. Le message asynchrone s'écrit A->B : texte (pointe ouverte, personne n'attend) et A->B.methode() est l'appel synchrone avec l'expéditeur écrit à la main. {} imbrique, return x revient à celui qui a fait l'appel englobant (un if au milieu n'y change rien), x = A.m() est l'autre écriture de la même réponse, new A(args) crée et // commentaire devient une note au-dessus du message suivant. Les blocs sont if/else if/else, while/for/forEach/loop, opt, par et try/catch/finally — et } else { poursuit le même cadre, avec un séparateur, au lieu d'en ouvrir un autre. @Actor dessine le bonhomme ; les autres annotateurs (@Database, @Boundary…) deviennent un stéréotype dans l'étiquette («Database» Stock), car leurs icônes ne sont pas dessinées ici — le nom reste visible, et c'est ce qui compte. Un nom avec espace va entre guillemets droits.

Attention à l'endroit où ce bloc atterrit : dans Mermaid, zenuml est un diagramme externe que la page doit enregistrer en JavaScript — GitHub ne le fait pas, donc la même note qui se dessine ici y apparaît comme un bloc de code.

Et lorsque LightNote ne parvient pas à lire un diagramme, il dit pourquoi et à quelle ligne, juste sous le bloc — un type que nous ne dessinons pas encore ne déclenche aucun avertissement, car rien n'y est faux.