shenwuyue841/obsidian-excalidraw

Générateur de Canvas Excalidraw pour Obsidian

Générez des fichiers .excalidraw.md qui s'ouvrent correctement dans le plugin Excalidraw d'Obsidian, incluant des blocs LaTeX manuscrits, des flèches liées et des couleurs adaptées au thème.

Quand l'utiliser

• Construire une carte de connaissances / un arbre de décision / un tableau de formules sous forme de canvas Excalidraw dans un coffre
• Convertir un plan Markdown ou une note en un canvas visuel
• Réparer un canvas qui s'affiche avec des images cassées, du texte invisible, des formules énormes, ou un fond blanc/foncé inattendu
• Harmoniser un nouveau canvas avec le langage visuel d'un canvas existant dans le même coffre

Ne PAS utiliser pour des fichiers .excalidraw JSON autonomes destinés à l'application web, ni pour générer des PNG/SVG — voir references/when-not-to-use.md si cette distinction compte.

Règles d'or (acquises à la dure)

1. LaTeX n'est pas du texte. Les formules sont des éléments de type "image" dont la source se trouve dans la section ## Embedded Files sous la forme <code hexa sur 40 caractères>: $$tex$$. Un élément image sans entrée correspondante dans Embedded Files s'affiche comme une image cassée. Voir references/latex.md.
2. N'écrivez jamais $$...$$ directement dans un élément texte pour ce plugin — cela affiche le code source brut. Le plugin ne rend que les équations présentes dans Embedded Files.
3. Le thème de la scène n'est pas autoritaire. Le plugin écrase appState.theme avec le thème de l'application. La couleur du canvas provient donc de viewBackgroundColor, mais un thème clair applique du blanc quoi qu'il arrive. Voir references/theme-and-color.md.
4. Copiez la palette d'un canvas existant dans le même coffre avant d'inventer des couleurs. Décompressez-en un avec scripts/inspect_canvas.mjs, lisez ses couleurs de trait et sa famille de polices, réutilisez-les.
5. Hauteur de formule uniforme, largeur basée sur la longueur. Une grande largeur fixe étire les formules courtes en géants. Voir references/layout.md.
6. Le plugin ré-enregistre sous forme de compressed-json (LZString base64, enveloppé toutes les ~120 caractères). Régénérez le canvas depuis votre script générateur plutôt que de patcher le fichier sauvegardé. Le lire nécessite une décompression — scripts/inspect_canvas.mjs le fait.
7. Vérifiez avant d'annoncer le succès. Exécutez le script d'inspection et vérifiez : le nombre d'équations est égal au nombre d'images, pas de liaisons orphelines, thème/fond comme souhaité.
8. « Ça a l'air bien » est mesurable. Ratio de conteneurs ≤ 30 %, ≤ 4 tailles de police, variance de hauteur de formule égale à 0, nombre de chevauchements égal à 0. scripts/inspect_canvas.mjs affiche désormais ces aesthetic warnings ; traitez tout avertissement comme un défaut, pas une préférence. Voir references/design-metrics.md.
9. Écrivez une seule fois, avec des identifiants stables, en supprimant d'abord. Les identifiants des éléments doivent être dérivés du contenu (hash du texte / TeX / étiquette), jamais aléatoires. Et dissociez le fichier cible avant de l'écrire. Sans ces deux précautions, la régénération d'un canvas actuellement ouvert dans Obsidian fusionne les nouveaux éléments dans la scène active : tout double, et le plugin enregistre automatiquement la scène doublée sur le disque. Voir references/troubleshooting.md → « Les éléments doublent / triplent ».
10. Rendez avant de livrer. scripts/render_preview.mjs rastérise le fichier sans tête (Node, pas de navigateur). Regardez le PNG — les audits JSON détectent la structure, seuls les pixels détectent « l'espacement est mauvais ». Le LaTeX s'affiche vide dans cet aperçu (MathJax vit dans le plugin Obsidian, pas dans le moteur de rendu), jugez donc la mise en page là et l'exactitude des formules à partir de ## Embedded Files.
11. Un seul niveau $$. Le TeX dans le modèle de données est nu (A=\int…) ; les délimiteurs ne sont ajoutés que lors de l'émission de la ligne ## Embedded Files. Tout $$$ dans un fichier généré est un bogue de double encapsulation qui affiche des signes dollar littéraux.

Deux écoles de mise en page — choisissez-en une avant de dessiner

	Grille de colonnes (表格派)	Lignes comme structure (结构派)
Forme	boîtes de colonnes + séparateurs de lignes	ligne principale + lignes de dérivation + texte flottant
Ratio de conteneurs	élevé (une boîte par colonne)	proche de 0
Lecture	comme un tableau de référence, rigoureux	comme un tableau blanc, léger
Idéal pour	plusieurs lignes de même niveau que l'on vérifie case par case	branchement, ou colonnes qui dérivent les unes des autres
Mode d'échec	« ressemble à un modèle de diapositive »	trop de branches → lignes qui se croisent

Règle empirique : colonnes sœurs → grille de colonnes ; une colonne dérivée des autres → lignes de structure. Les deux exemples existent dans design-metrics.md avec un contenu identique (le canvas 第十讲), vous pouvez donc comparer avant de choisir.

Workflow

1. Lisez les conventions du coffre cible. Trouvez un fichier .excalidraw.md existant que l'utilisateur apprécie, exécutez node scripts/inspect_canvas.mjs <fichier> et notez : thème, viewBackgroundColor, couleurs de trait dominantes, fontFamily, roughness, tailles de police typiques.
2. Concevez le contenu en colonnes ou en lignes (voir references/layout.md) — une colonne par famille de quantité/étape, une ligne par formule, et ne regroupez que les choses qui sont réellement de la même quantité. Choisissez l'école de mise en page (grille de colonnes vs lignes de structure) selon le tableau ci-dessus.
3. Écrivez un script générateur modelé sur scripts/gen_canvas.mjs : modifiez son bloc CONFIG (titre, colonnes, lignes) et exécutez-le. Ne modifiez pas à la main le JSON de 30 ko. Conservez les deux mécanismes de sécurité qu'il embarque : les identifiants dérivés du contenu et rmSync avant writeFileSync.
4. Inspectez le résultat avec scripts/inspect_canvas.mjs, corrigez les comptes/couleurs/liaisons. Vérifiez également l'absence de $$$ dans le fichier et que le nombre d'éléments est égal à ce que le générateur a affiché (un multiple signifie que le bogue de fusion a frappé). Ensuite rendez-le avec scripts/render_preview.mjs et regardez réellement le PNG ; corrigez l'espacement/les chevauchements/les lignes courtes avant de faire rapport.
5. Rapportez ce que l'utilisateur doit faire dans Obsidian (fermer et rouvrir le fichier, ou utiliser la commande « Decompress current Excalidraw file ») — le plugin ne relit un fichier que lorsqu'il est rouvert.

Carte de référence

Fichier	Contenu
references/file-format.md	Squelette exact du .excalidraw.md, les deux encodages, ordre des sections, commentaire d'en-tête
references/element-schema.md	Champs obligatoires par type d'élément, texte lié, liaisons de flèches, ordre index
references/latex.md	Contrat Embedded Files, \color, dimensionnement, les trois variantes de rendu testées, signatures d'échec
references/theme-and-color.md	Pourquoi les canvas s'ouvrent en blanc, matchThemeAlways, extraction de palette, couleurs établies de ce coffre
references/layout.md	Géométrie colonne/ligne, heuristiques de dimensionnement des formules, ce qui rend un canvas inachevé
references/script-engine.md	Moteur de scripts JS dans le plugin : où placer les scripts, ce qu'ils peuvent faire, l'API ExcalidrawAutomate, capacité à faire des tableaux, compromis avec la génération au niveau fichier
references/design-metrics.md	Esthétique quantifiée : ratio de conteneurs, nombre de niveaux de police, variance de formule, espace blanc, couleur sémantique ; deux écoles de mise en page ; comment valider sans moteur de rendu
references/troubleshooting.md	Tableau symptôme → cause → correction pour chaque échec rencontré jusqu'à présent
scripts/gen_canvas.mjs	Générateur de canvas piloté par configuration (texte, latex, rectangle, ligne horizontale, flèche)
scripts/inspect_canvas.mjs	Décompression + audit : thème, comptes, correspondance équation/image, liaisons, polices, métriques esthétiques. --describe affiche un inventaire compact id/position/étiquette/connexion ; --dump affiche le JSON brut de la scène
scripts/render_preview.mjs	Aperçu PNG sans tête via mcp-excalidraw-server render (pas de navigateur). Le LaTeX s'affiche vide — mise en page uniquement
evals/evals.json	Prompts de régression : un par mode d'échec qui s'est réellement produit
examples/ea-table.md	Un script exécutable dans l'application qui construit un tableau à partir de rectangles + texte

Édition d'un canvas existant

1. Décompressez-le pour comprendre l'état actuel (inspect_canvas.mjs --dump <fichier> affiche le JSON de la scène).
2. Préférez la régénération à partir du script générateur. Si l'utilisateur a apporté des modifications manuelles qui méritent d'être conservées, écrivez une transformation ciblée (lire la scène → modifier des éléments spécifiques → resérialiser non compressé) plutôt que de réécrire tout le canvas.
3. Ne laissez jamais un canvas à moitié migré : soit chaque image a son équation, soit aucune.

Valeurs par défaut de dimensionnement et typographie pour ce coffre

• Texte du corps fontFamily: 6, roughness: 0, strokeWidth: 1.
• Titre 28–30 px, en-tête de colonne 19–22 px, étiquette de ligne 15–16 px, hauteur d'image de formule 50–52 px.
• Pas de ligne 116–130 px ; largeur de colonne 320–340 px ; espacement 28–40 px.
• Fond du canvas #ffffff ; encre #1e1e1e ; atténué #868e96 ; trait fin #e9ecef.