Pour simplifier un diagramme d’état Mermaid dans Obsidian sur Mac, gardez chaque transition valide explicite, raccourcissez les libellés et vérifiez le sens de lecture. Comparez les états source et destination ainsi que le texte de transition avant de valider le résultat.

Ce guide utilise quatre états synthétiques, A à D. L’objectif est de rendre un diagramme plus facile à lire tout en préservant ses transitions directes, ses chemins de retour et ses marqueurs de début et de fin. Le tableau des transitions fournit un moyen concret de vérifier cette préservation indépendamment de la façon dont le moteur de rendu positionne les flèches.

Que faut-il conserver lors de la simplification du diagramme ?

Commencez par distinguer les changements de présentation des changements apportés au modèle. Des libellés affichés plus courts et un sens de lecture différent peuvent améliorer la lisibilité. Supprimer une flèche modifie l’ensemble des transitions directes, même si un autre chemin mène toujours à la même destination.

Par exemple, supposons qu’il existe à la fois une transition directe de A vers C et un chemin passant par B. La suppression de la transition directe obligerait le lecteur à déduire une visite intermédiaire à B. La destination reste atteignable, mais une transition valide en une seule étape est perdue. Pour cette tâche, atteindre finalement la même destination ne suffit pas.

Utilisez l’inventaire de transitions suivant comme spécification d’origine. Les libellés sont des noms d’événements synthétiques ; ils ont un sens dans cet exemple et doivent rester associés à leurs flèches d’origine.

Source Destination Texte de transition
Début A Aucun
A B step
A C alternate
B C next
B A reset
C B back
C A reset
C D finish
D Fin Aucun

Il y a neuf transitions, en comptant le début et la fin. Deux flèches portent le libellé reset, mais partent d’états différents. Conservez-les toutes les deux. De même, les flèches entre B et C ont des directions et des libellés différents ; ce sont des transitions distinctes.

Pour un diagramme plus grand, notez chaque transition sous la forme d’une combinaison de source, de destination et de texte avant de le modifier. Si votre texte d’origine inclut des conditions ou des actions, conservez-les également. Le simple fait de faire correspondre le nombre total de flèches ne permet pas de repérer une flèche dont la destination ou le libellé a changé.

Vérifiez quel moteur de rendu utilise votre version d’Obsidian

Sur votre Mac, ouvrez les Settings à l’aide de l’icône d’engrenage dans la barre latérale, puis sélectionnez General. Notez la version actuelle de l’application et la version de l’installateur affichées en haut. Utilisez la version de l’application pour consulter les notes de version pertinentes. Ces emplacements sont indiqués dans l’aide des paramètres d’Obsidian.

Le moteur de rendu fait une différence. La version Desktop 1.15.0 d’Obsidian en accès anticipé, datée du 22 octobre 2026, utilise Pele pour le rendu des diagrammes et indique sa compatibilité avec la syntaxe Mermaid 12.1.0. Les notes de version précisent également que cette version n’inclut plus la bibliothèque Mermaid. Cette déclaration concerne la version mentionnée ; elle n’identifie pas le moteur de rendu de chaque version installée d’Obsidian. Consultez les notes de version d’Obsidian 1.15.0 Desktop.

Traitez la compatibilité syntaxique et l’apparence visuelle comme deux vérifications distinctes. Un diagramme accepté par un autre éditeur constitue un point de comparaison utile, mais c’est dans votre application installée qu’il faut vérifier le résultat final. Ne supposez pas qu’un paramètre de mise en page en amont ou qu’un exemple tiré d’une documentation plus récente se comportera de la même façon dans votre moteur de rendu local.

L’exemple ci-dessous évite volontairement les paramètres du moteur de rendu, les paramètres de thème et le style. Si vous avez déjà un diagramme fonctionnel, partez de sa déclaration actuelle et ne modifiez qu’un détail de présentation à la fois. Une mise à niveau n’est pas nécessaire pour effectuer l’inventaire des transitions et les modifications de libellés décrits ici.

Créez une version compacte avec des transitions explicites

L’exemple complet ci-dessous met en œuvre les neuf lignes de l’inventaire. Les noms d’état affichés sont volontairement courts. L’état A est le point de départ, B et C ont des chemins de retour, et seul D possède une transition vers le marqueur de fin.

Mermaid documente les alias d’état, les transitions libellées, les marqueurs de début et de fin, ainsi que la déclaration du sens dans sa référence des diagrammes d’état. La méthode documentée par Obsidian consiste à utiliser un bloc de code délimité portant l’identifiant de langage mermaid, comme l’explique la syntaxe de mise en forme avancée.

```mermaid
stateDiagram-v2
    direction LR

    state "Stage A" as A
    state "Stage B" as B
    state "Stage C" as C
    state "Stage D" as D

    [*] --> A

    A --> B : step
    A --> C : alternate

    B --> A : reset
    B --> C : next

    C --> A : reset
    C --> B : back
    C --> D : finish

    D --> [*]
```

Collez l’intégralité de cet exemple Markdown, y compris ses lignes d’ouverture et de fermeture avec trois accents graves, dans une note. Le bloc externe de quatre accents graves montré ici sert uniquement à afficher l’exemple dans cet article ; il ne fait pas partie du contenu de la note.

Pour examiner le texte exact, utilisez Source mode. Pour examiner le résultat rendu, passez en Reading view ; sur macOS, Cmd+E bascule entre les vues de lecture et d’édition. Obsidian décrit ces commandes dans Vues et mode d’édition.

Les déclarations de transition sont regroupées par état source afin que les options de sortie de chaque état puissent être examinées ensemble. Cette organisation facilite la maintenance du texte source ; elle ne garantit pas l’emplacement des états dans le moteur de rendu.

Essayez l’exemple à la largeur de note que vous utilisez habituellement. Supprimez ensuite uniquement la ligne direction LR et comparez le résultat. Gardez la présentation qui facilite le suivi des bifurcations et des chemins de retour. Un diagramme orienté de gauche à droite peut nécessiter davantage d’espace horizontal ; évaluez donc le résultat dans le volet de note réel.

Raccourcissez les libellés uniquement dans la mesure où leur sens le permet. Dans cet exemple synthétique, Stage B n’a pas besoin d’explication supplémentaire. Dans votre propre diagramme, conservez toute formulation qui distingue deux états. Si une longue explication est nécessaire, placez-la dans un paragraphe de prose adjacent et indiquez clairement à quel identifiant d’état elle correspond.

Quels raccourcis peuvent modifier le modèle ?

La répétition de flèches peut inciter à introduire un nœud intermédiaire partagé. Avant de le faire, demandez-vous ce que représente ce nœud et si les transitions directes d’origine existent toujours.

Un nœud de réinitialisation partagé modifie les chemins directs

Dans l’inventaire, B et C mènent chacun directement à A lors de reset. Remplacer ces flèches par des chemins passant par un nouvel état nommé R crée un état intermédiaire et supprime les arêtes directes d’origine. Le lecteur peut toujours suivre un chemin jusqu’à A, mais le diagramme décrit désormais des étapes différentes.

Pour obtenir le résultat exact de cet article, conservez les deux flèches de réinitialisation. Leur répétition indique deux conditions de départ valides pour le même événement. Réduire leur encombrement visuel n’est utile que si leur sens est préservé.

Un choix ou une bifurcation doit avoir une justification dans le modèle

Mermaid documente <<choice>> pour la bifurcation entre chemins, ainsi que <<fork>> et <<join>> pour les structures de bifurcation et de jonction. Il s’agit de constructions distinctes dans la référence des diagrammes d’état.

N’en introduisez pas une uniquement pour regrouper plusieurs flèches désordonnées dans un embranchement commun. Dans cet exemple, la tâche consiste à conserver les transitions directes d’un état à l’autre. L’ajout d’une construction intermédiaire nécessiterait d’expliquer séparément la correspondance entre ses chemins et le modèle d’origine. Des flèches explicites rendent cette correspondance immédiate.

Les états composites ont des limites documentées

Mermaid prend en charge les états composites, mais sa documentation interdit explicitement les transitions entre des états internes appartenant à différents états composites. Consultez États composites.

Si le regroupement de vos nœuds crée cette situation, gardez les états connectés à plat pour cette tâche. Déplacer une flèche vers l’état composite externe en modifie le point d’arrivée ; ce n’est pas automatiquement une solution équivalente. Utilisez une hiérarchie lorsqu’elle représente la structure réelle du modèle et que vous pouvez expliquer le comportement à l’entrée et à la sortie.

Pour l’exemple à quatre états, l’imbrication apporte peu. La simplification utile consiste à raccourcir les libellés et à clarifier la présentation tout en conservant la structure des transitions.

Vérifiez les transitions et le résultat rendu

Effectuez deux vérifications avant de remplacer le diagramme d’origine. La première porte sur le modèle ; la seconde vérifie l’utilité de la présentation choisie.

  1. Comparez chaque ligne de l’inventaire à une déclaration de transition. Vérifiez les deux extrémités et le libellé complet.
  2. Comparez chaque déclaration de transition à l’inventaire. Cela permet de repérer les flèches supplémentaires autant que les flèches manquantes.
  3. Vérifiez séparément le début et la fin. Ici, le début mène uniquement à A, et seul D mène à la fin.
  4. Examinez le diagramme rendu pour vérifier que les libellés sont lisibles et que les pointes des flèches sont distinctes.
  5. Suivez les chemins de retour à partir de B et de C, car ils sont faciles à manquer lorsqu’on ne vérifie que la progression vers l’avant.

Pour cet exemple, essayez trois parcours : du début à A, puis à C, puis à D, puis à la fin ; du début à A, puis à B, puis par la réinitialisation à A ; et du début à A, puis à C, puis en retour à B. Ces vérifications couvrent le chemin alternatif, la réinitialisation et la connexion en sens inverse. Elles complètent la comparaison des lignes sans la remplacer.

Une comparaison textuelle déterministe a confirmé que les neuf déclarations de transition de l’exemple correspondent à l’inventaire, libellés compris. L’exemple n’a pas été rendu dans une application Obsidian installée lors de sa préparation ; il reste donc à vérifier l’espacement final et le tracé des flèches dans votre version locale.

Si la note affiche du code littéral, vérifiez d’abord que vous la consultez en Reading view et que le bloc d’ouverture indique mermaid. Si vous obtenez une erreur d’analyse après modification, repartez de l’exemple complet et réappliquez les changements un par un. Si seule la mise en page est maladroite, conservez les transitions et comparez la longueur des libellés, le sens de lecture et la largeur disponible du volet.

Conservez la version dont les libellés et les chemins sont les plus faciles à lire une fois la comparaison avec l’inventaire réussie. Une simplification réussie permet au lecteur de suivre les mêmes transitions valides plus facilement, tout en gardant un texte source simple à examiner et à maintenir.

Sources