AnisAbdellatif/d2

Diagrammes D2

D2 est un langage déclaratif : vous décrivez les formes et les connexions entre elles, et un moteur de disposition décide où tout se place. Vous ne placez jamais de coordonnées à la main. C'est pourquoi un diagramme D2 est court, diffable et facile à modifier plus tard, et aussi pourquoi la plupart des erreurs proviennent de la syntaxe et des bizarreries du moteur de disposition, et non de la conception.

Cette compétence est une connaissance fonctionnelle complète de D2 v0.9.x, vérifiée par rapport au compilateur réel. Chaque exemple dans references/ et assets/templates/ compile.

Flux de travail

1. Vérifiez l'outil. Exécutez d2 --version (ou scripts/d2check.sh --version). Si d2 est manquant, informez l'utilisateur et proposez brew install d2 ou curl -fsSL https://d2lang.com/install.sh | sh -s -- ; ne l'installez pas silencieusement.
2. Choisissez le type de diagramme et lisez la référence correspondante (tableau ci-dessous). Commencez à partir d'un modèle dans assets/templates/ lorsqu'il correspond.
3. Écrivez le fichier .d2 à côté de l'endroit où l'utilisateur le souhaite (par défaut : diagrams/<name>.d2).
4. Compilez et générez avec scripts/d2check.sh <file.d2> [outdir] [pdf|pptx|gif] (formate, compile, génère SVG, met un aperçu PNG dans outdir/preview/, et tous les formats supplémentaires). Ne vous fiez jamais à d2 validate seul : il ne fait qu'analyser la syntaxe. Les mauvais noms de forme, les styles hors limites, les fonctionnalités de disposition non prises en charge et les importations manquantes réussissent tous la validation validate et échouent à la compilation.
5. Regardez l'image. Ouvrez le PNG dans preview/ (outil Read sur le .png) et jugez : étiquettes qui se chevauchent, bords emmêlés, direction de flux erronée, disposition déséquilibrée. Corrigez et générez à nouveau. Un diagramme qui compile mais est illisible n'est pas terminé.
6. Livrez le source .d2 plus le fichier généré, et dites quel moteur de disposition, thème et direction vous avez utilisés afin que l'utilisateur puisse les modifier.

Pour un usage unique rapide sans fichiers : echo 'a -> b' | d2 - out.svg.

Syntaxe en un écran

direction: right                    # up | down | right | left (racine seulement ; seul TALA permet par conteneur)

# formes : clé, étiquette facultative, attributs facultatifs
web: App web {shape: rectangle}     # clé `web`, étiquette "App web"
db: Postgres {shape: cylinder}
user: Client {shape: person}

# connexions : -> <- <-> --  (référencez toujours les CLÉS, jamais les étiquettes)
user -> web: utilise
web -> db: SQL {style.stroke-dash: 3}
web -> cache: lit              # les clés non déclarées sont créées à la volée

# conteneurs : points ou cartes imbriquées
backend: {
  api -> worker: file
  worker -> _.db: écrit         # _ = portée parent
}
web -> backend.api: HTTPS

# le style vit dans les attributs
db.style.fill: "#e6f2ff"         # mettez entre guillemets tout ce qui commence par #
(web -> db)[0].style.stroke: red # style d'une connexion par index

# réutilisation : classes, variables, globs
classes: {
  store: {shape: cylinder; style.fill: "#e6f2ff"}
}
cache.class: store
vars: {env: prod}
note: Exécution dans ${env}
*.style.border-radius: 8

Les points-virgules séparent les éléments sur une même ligne. # commence un commentaire, """ ... """ est un commentaire bloc. Les clés sont insensibles à la casse et les déclarations répétées fusionnent (API, api et Api: Passerelle sont une seule forme étiquetée "Passerelle").

Guillemets : la source numéro un des erreurs

Les chaînes non guillemetées sont pratiques, mais plusieurs caractères ont une signification. Mettez toute l'étiquette entre guillemets ("..." ou '...') chaque fois qu'elle contient l'un de ces caractères, sinon le compilateur soit génère une erreur, soit, pire, tronque silencieusement l'étiquette :

Caractère	Ce qui se passe sans guillemets	Correction exemple
# n'importe où	le reste de la ligne devient un commentaire : a: Langage C# génère "C"	a: "Langage C#"
[ au début	analysé comme un tableau : a: [JSON/HTTPS] génère juste "a"	a: "[JSON/HTTPS]"
. dans une clé	crée un conteneur : svc v1.2 devient svc v1 > 2	"svc v1.2"
& ou [ ] dans une clé	erreur d'analyse (& est le marqueur de filtre glob)	"R&D", "svc[0]"
$ suivi de tout sauf {	"les substitutions doivent commencer par {"	guillemets simples : 'coûte $5'
{ } `	` au début d'une étiquette	ouvre une carte ou une chaîne bloc
mots réservés comme clés de forme (label, link, class, top, style, shape, icon, near, direction, vars ...)	"les mots-clés réservés sont interdits dans les arêtes"	"link" -> b, ou choisissez une clé différente
-> ou : dans une étiquette d'arête	fonctionne en pratique (a -> b: Temps : 10 s fonctionne)	pas besoin de guillemets
ponctuation non ASCII comme ： (deux-points pleine largeur)	non reconnue comme deux-points	utilisez les deux-points ASCII : ; .

Les couleurs hexadécimales doivent être guillemetées ("#fff") car # commence un commentaire. Les guillemets simples désactivent également la substitution ${...}.

Nouvelles lignes dans les étiquettes : \n dans une étiquette guillemetée ou non guillemetée, ou une chaîne bloc |md ... | pour le texte enrichi.

Pièges (à lire avant de déboguer)

• Dagre, le moteur de disposition par défaut, ne peut pas dessiner une connexion entre un conteneur et son propre descendant (a -> a.b), ne peut pas dimensionner les conteneurs (width/height), et ne peut pas utiliser near: <object>. Il génère une erreur à la compilation. Passez à --layout=elk (ou vars.d2-config.layout-engine: elk) au lieu de réécrire le diagramme.
• Les mots réservés sont comparés sans tenir compte de la casse. Une forme ou une classe UML nommée Shape, Label, Class, Style, Link, Icon... entre en collision avec le mot-clé (reserved field shape does not accept composite). Renommez-la.
• Connectez les clés, pas les étiquettes. Après be: Backend, Backend -> x crée une nouvelle forme nommée Backend. Utilisez be -> x.
• Les connexions répétées ne fusionnent pas ; a -> b deux fois dessine deux flèches. Adressez-les comme (a -> b)[0], (a -> b)[1].
• d2-legend est une variable, pas une forme : mettez-la à l'intérieur de vars: { d2-legend: { ... } }. Une d2-legend: "" au niveau racine est juste une forme ordinaire nommée "d2-legend".
• Diagrammes de séquence : l'ordre de déclaration est l'ordre à l'écran, les acteurs doivent être déclarés en premier, et à l'intérieur des groupes, vous ne pouvez référencer que les acteurs qui existent au niveau supérieur.
• Tables SQL et classes UML : connectez les lignes (orders.user_id -> users.id), et utilisez ELK ou TALA pour que les arêtes arrivent exactement sur la ligne.
• Les formes de pointe de flèche ne s'affichent que sur une extrémité qui a une flèche : A -> B avec source-arrowhead.shape: diamond ne dessine rien à A (et -- ne dessine aucune forme). Inversez l'arête pour que la forme soit sur la cible, ou utilisez <->.
• d2 fmt réécrit les étiquettes de mots réservés (lnk: Link devient lnk: link), et scripts/d2check.sh exécute fmt sur votre fichier en place. Mettez ces étiquettes entre guillemets (lnk: "Link").
• Les chaînes bloc |md ... | se terminent au | suivant. Un tube littéral à l'intérieur nécessite un délimiteur plus long : |md ... | ou ||md ... ||.
• Les plages de styles numériques sont appliquées : stroke-width 0-15, opacity 0-1, font-size 8-100. text-transform prend none|uppercase|lowercase|capitalize (le site web dit title ; le compilateur le rejette). 3d fonctionne uniquement sur rectangle, square et hexagon.
• N'ajoutez pas animated: true ou dark-theme-id sauf demande explicite. L'animation implique un flux de données en temps réel ; un thème sombre change silencieusement les couleurs pour les spectateurs dont le système d'exploitation est en mode sombre.
• Les couleurs de remplissage sur les formes remplacent le thème. Préférez le thème et quelques classes ; n'utilisez des couleurs explicites que lorsque la couleur a une signification (et ajoutez alors une légende).
• Les rendus PNG/PDF/PPTX/GIF se font sans navigateur en v0.9+. Les versions plus anciennes (<0.8) nécessitent Playwright/Chromium, qui se télécharge lors de la première utilisation. Vérifiez d2 --version.
• TALA est intégré dans v0.9 (--layout=tala) mais non déterministe : un petit changement d'étiquette peut remanier la disposition. Figez-le avec data.tala-seeds si la reproductibilité est importante.
• Les fichiers multi-tableaux (layers/scenarios/steps) exportent SVG et PNG sous forme de répertoires (x/index.svg, x/layers/a.svg), et le rendu PNG vers le même nom remplace le répertoire SVG. Gardez les formats dans des dossiers séparés (le script le fait). Pour une livraison avec exploration, utilisez PDF (une page par tableau, link: layers.x cliquable) et ne dessinez pas de formes "Retour" à la main : l'exportateur ajoute une barre de navigation automatiquement. Voir references/composition.md.
• L'existence d'un fichier de sortie ne signifie pas succès. D2 peut écrire un rendu partiel en cas d'erreur. Vérifiez le code de sortie (le script le fait).

Choix de la disposition, de la direction, du thème

• Moteur de disposition : dagre (par défaut, rapide, bords courbes) -> elk (routage orthogonal, meilleur pour l'architecture, les tables SQL, les arêtes conteneur-à-conteneur) -> tala (symétrie, direction par conteneur, near: objet, top/left verrouillés). Utilisez par défaut ELK pour tout ce qui a des conteneurs ou des tables.
• Direction : right pour les pipelines, les flux de requêtes et les écrans larges ; down pour les hiérarchies et les organigrammes. Choisissez-en une pour l'ensemble du tableau.
• Thème : theme-id: 0 par défaut ; 4 Cool classics et 3 Flagship Terrastruct ont un aspect moderne ; 1 gris neutre pour les documents sobres ; 8 est adapté aux daltoniens ; 300/301 terminal ; 303 C4 ; 200/201 sombre. Tableau complet dans references/cli-and-rendering.md.
• Mettez les paramètres de rendu dans le fichier pour qu'ils voyagent avec lui :

vars: {
  d2-config: {
    layout-engine: elk
    theme-id: 4
    pad: 40
  }
}

(Les drapeaux CLI et les variables d'environnement D2_* remplacent ce bloc.)

Conseils de conception

• 3 à 12 formes par tableau. Au-delà, divisez avec layers (zoom avant), scenarios (variantes) ou steps (construction progressive), ou utilisez des conteneurs pour regrouper.
• Nommez par clé, étiquetez pour les humains : clés courtes et stables (pg, auth), étiquettes lisibles (pg: PostgreSQL).
• Les étiquettes d'arête sont des verbes ou des protocoles (lit, public, HTTPS), pas des phrases ni le nom de la cible.
• Faites correspondre la forme à la signification : cylinder stockage, queue, person, cloud externe, diamond décision, hexagon service, document/page, package, step. Ne laissez pas tout être un rectangle.
• La couleur encode une signification ou rien. Au maximum ~5 catégories, appliquées via classes, avec une d2-legend uniquement lorsque les couleurs transportent des informations que les étiquettes n'ont pas.
• Un niveau d'abstraction par tableau.
• D2 est destiné à documenter les logiciels et les systèmes à l'échelle d'un tableau blanc (jusqu'à quelques centaines de formes). Il n'a délibérément pas de diagrammes de Gantt, de cartes mentales, de diagrammes de Venn, de Sankey, de diagrammes circulaires/à barres ou de cartes géographiques, et un objet ne peut pas se trouver dans deux conteneurs. Dites-le et suggérez un autre outil plutôt que de déformer D2.

Carte de référence

Lisez uniquement ce dont la tâche a besoin.

Tâche	Lire
Tout doute de syntaxe : clés, étiquettes, connexions, conteneurs, chaînes, échappement, commentaires, mots-clés réservés	references/language.md
Formes, chaque clé de style et sa plage, pointes de flèche, texte/markdown/LaTeX/code, icônes, positionnement near, tailles, thèmes	references/shapes-and-styling.md
Diagrammes de séquence, tables SQL (ERD), classes UML, grilles, légendes, infobulles/liens, C4	references/diagram-types.md
Classes, variables, globs et filtres, remplacements et null, importations, modèles suspend	references/reuse-and-globs.md
Couches, scénarios, étapes, tableaux de liaison, importations pour grands diagrammes, export multi-tableaux	references/composition.md
Drapeaux CLI, moteurs de disposition, tableau des thèmes, formats d'exportation, d2-config, intégration dans docs/CI, D2.js	references/cli-and-rendering.md
Modèles prêts à l'emploi par famille de diagrammes (architecture, organigramme, état, ERD, C4, organigramme...)	references/recipes.md + assets/templates/*.d2
Conversion depuis Mermaid / PlantUML / Graphviz	references/recipes.md (section conversion)
Un message d'erreur ou un diagramme qui s'affiche mal	references/troubleshooting.md

En cas d'échec de la compilation

Exécutez scripts/d2check.sh file.d2. Les erreurs se présentent sous la forme file:DROITE:COL: message. Recherchez le message dans references/troubleshooting.md ; les coupables habituels sont les guillemets (ci-dessus), une limite du moteur de disposition (passez à ELK), une forme inconnue ou un style hors limites, et l'indentation des chaînes bloc. Corrigez une erreur à la fois et réexécutez : les erreurs ultérieures sont souvent des conséquences de la première.