shenwuyue841/obsidian-excalidraw

Obsidian Excalidraw Canvas Builder

Generiere .excalidraw.md-Dateien, die korrekt im Obsidian Excalidraw-Plugin geöffnet werden, einschließlich handgeschriebener LaTeX-Blöcke, gebundener Pfeile und themengerechter Farben.

Wann verwenden

• Erstellen einer Wissenslandkarte / eines Entscheidungsbaums / einer Formeltafel als Excalidraw-Canvas in einem Vault
• Konvertieren einer Markdown-Gliederung oder -Notiz in eine visuelle Canvas
• Reparieren einer Canvas, die mit defekten Bildern, unsichtbarem Text, riesigen Formeln oder einem unerwarteten weißen/dunklen Hintergrund rendert
• Anpassen einer neuen Canvas an die visuelle Sprache einer vorhandenen Canvas im selben Vault

NICHT verwenden für eigenständige .excalidraw-JSON-Dateien für die Web-App oder zum Rendern von PNG/SVG – siehe references/when-not-to-use.md, falls diese Unterscheidung wichtig ist.

Goldene Regeln (auf die harte Tour gelernt)

1. LaTeX ist kein Text. Formeln sind type: "image"-Elemente, deren Quelle im Abschnitt ## Embedded Files als <40-hex-id>: $$tex$$ liegt. Ein Bildelement ohne passenden Embedded Files-Eintrag wird als defektes Bild gerendert. Siehe references/latex.md.
2. Schreibe niemals $$...$$ von Hand in ein Textelement für dieses Plugin – es zeigt den rohen Quelltext an. Das Plugin rendert nur Gleichungen, die in Embedded Files vorhanden sind.
3. Das Szenen-Thema ist nicht maßgeblich. Das Plugin überschreibt appState.theme mit dem App-Thema. Die Canvas-Farbe kommt daher von viewBackgroundColor, aber ein helles Thema zeichnet trotzdem weiß. Siehe references/theme-and-color.md.
4. Kopiere die Palette aus einer vorhandenen Canvas im selben Vault, bevor du Farben erfindest. Dekomprimiere eine mit scripts/inspect_canvas.mjs, lies ihre Strichfarben und Schriftfamilie, verwende sie wieder.
5. Einheitliche Formelhöhe, längenbasierte Breite. Eine feste große Breite dehnt kurze Formeln zu Giganten. Siehe references/layout.md.
6. Das Plugin speichert als compressed-json (LZString base64, etwa alle ~120 Zeichen umbrochen). Generiere die Canvas aus deinem Generator-Skript neu, anstatt die gespeicherte Datei zu patchen. Das Lesen erfordert Dekomprimierung – scripts/inspect_canvas.mjs macht das.
7. Überprüfe, bevor du Erfolg meldest. Führe das Inspektionsskript aus und prüfe: Gleichungsanzahl entspricht Bildanzahl, keine losen Bindungen, Thema/Hintergrund wie beabsichtigt.
8. „Sieht gut aus" ist messbar. Container-Verhältnis ≤ 30%, ≤ 4 Schriftgrößen, Formelhöhenvarianz 0, Überlappungsanzahl 0. scripts/inspect_canvas.mjs gibt diese jetzt als aesthetic warnings aus; behandle jede Warnung als Fehler, nicht als Präferenz. Siehe references/design-metrics.md.
9. Einmal schreiben, mit stabilen IDs, durch vorheriges Löschen. Element-IDs müssen aus dem Inhalt abgeleitet werden (Hash des Textes / TeX / Labels), niemals zufällig. Und entferne die Zieldatei vor dem Schreiben. Ohne beides führt das Neugenerieren einer Canvas, die derzeit in Obsidian geöffnet ist, dazu, dass die neuen Elemente in die Live-Szene eingefügt werden: Alles verdoppelt sich, und das Plugin speichert die verdoppelte Szene automatisch zurück auf die Festplatte. Siehe references/troubleshooting.md → „Elemente verdoppeln / verdreifachen".
10. Rendere vor der Auslieferung. scripts/render_preview.mjs rastet die Datei headlos ein (Node, kein Browser). Schau dir das PNG an – JSON-Prüfungen erkennen die Struktur, nur Pixel erkennen „der Abstand sieht falsch aus". LaTeX erscheint in dieser Vorschau leer (MathJax lebt im Obsidian-Plugin, nicht im Renderer), beurteile also das Layout dort und die Formelkorrektheit anhand von ## Embedded Files.
11. Nur eine $$-Ebene. TeX im Datenmodell ist nackt (A=\int…); die Begrenzer werden nur beim Ausgeben der ## Embedded Files-Zeile hinzugefügt. Jedes $$$ in einer generierten Datei ist ein Doppel-Wrapping-Fehler, der literal Dollarzeichen rendert.

Zwei Layout-Schulen – wähle eine vor dem Zeichnen

	Spaltengitter (表格派)	Linien als Struktur (结构派)
Form	Spaltenboxen + Zeilenteiler	Stammlinie + Abzweigungen + freischwebender Text
Container-Verhältnis	hoch (eine Box pro Spalte)	nahe 0
Liest sich wie	eine Nachschlagetabelle, streng	Tafel, leicht
Am besten für	viele gleichrangige Zeilen, die du Zelle für Zelle prüfst	Verzweigungen oder Spalten, die voneinander abgeleitet sind
Fehlermodus	„sieht aus wie eine Folienvorlage"	zu viele Verzweigungen → sich kreuzende Linien

Faustregel: Geschwisterspalten → Spaltengitter; eine Spalte von den anderen abgeleitet → Strukturlinien. Beide Beispiele existieren in design-metrics.md mit identischem Inhalt (der 第十讲 Canvas), sodass du vor der Wahl vergleichen kannst.

Arbeitsablauf

1. Lies die Konventionen des Ziel-Vaults. Finde eine vorhandene .excalidraw.md, die dem Benutzer gefällt, führe node scripts/inspect_canvas.mjs <datei> aus und notiere: Thema, viewBackgroundColor, dominante Strichfarben, fontFamily, roughness, typische Schriftgrößen.
2. Gestalte den Inhalt als Spalten oder Zeilen (siehe references/layout.md) – eine Spalte pro Mengen-/Schrittfamilie, eine Zeile pro Formel, und gruppiere nur Dinge, die tatsächlich dieselbe Größe sind. Wähle die Layout-Schule (Spaltengitter vs. Strukturlinien) gemäß der Tabelle oben.
3. Schreibe ein Generator-Skript nach dem Vorbild von scripts/gen_canvas.mjs: bearbeite seinen CONFIG-Block (Titel, Spalten, Zeilen) und führe es aus. Bearbeite das 30 kB JSON nicht von Hand. Behalte die beiden Sicherheitsmechanismen bei, die es mitbringt: inhaltsabgeleitete IDs und rmSync vor writeFileSync.
4. Überprüfe das Ergebnis mit scripts/inspect_canvas.mjs, korrigiere Anzahlen/Farben/Bindungen. Bestätige auch kein $$$ in der Datei und dass die Elementanzahl dem entspricht, was der Generator ausgegeben hat (ein Vielfaches davon bedeutet, dass der Merge-Fehler zugeschlagen hat). Dann rendere es mit scripts/render_preview.mjs und schau dir das PNG tatsächlich an; korrigiere Abstände/Überlappungen/kurze Zeilen, bevor du Bericht erstattest.
5. Berichte, was der Benutzer in Obsidian tun muss (Datei schließen und wieder öffnen oder den Befehl „Aktuelle Excalidraw-Datei dekomprimieren" verwenden) – das Plugin liest eine Datei nur beim erneuten Öffnen neu ein.

Referenzkarte

Datei	Inhalt
references/file-format.md	Exaktes .excalidraw.md-Grundgerüst, beide Kodierungen, Abschnittsreihenfolge, Header-Kommentar
references/element-schema.md	Erforderliche Felder pro Elementtyp, gebundener Text, Pfeilbindungen, index-Reihenfolge
references/latex.md	Embedded Files-Vertrag, \color, Größenanpassung, die drei getesteten Rendervarianten, Fehlersignaturen
references/theme-and-color.md	Warum Canvases weiß öffnen, matchThemeAlways, Palettenextraktion, die etablierten Farben dieses Vaults
references/layout.md	Spalten-/Zeilengeometrie, Formelgrößenheuristiken, was eine Canvas unfertig aussehen lässt
references/script-engine.md	插件内的 JS 脚本引擎：脚本放哪、能干什么、ExcalidrawAutomate API、能不能做表格、与文件级生成的取舍
references/design-metrics.md	Quantifizierte Ästhetik: Container-Verhältnis, Schriftartenanzahl, Formelvarianz, Leerraum, semantische Farbe; zwei Layout-Schulen; wie man ohne Renderer validiert
references/troubleshooting.md	Symptom → Ursache → Behebungstabelle für jeden bisher aufgetretenen Fehler
scripts/gen_canvas.mjs	Konfigurationsgesteuerter Canvas-Generator (Text, Latex, Rechteck, hLine, Pfeil)
scripts/inspect_canvas.mjs	Dekomprimieren + Prüfung: Thema, Anzahlen, Gleichungs-/Bildübereinstimmung, Bindungen, Schriftarten, ästhetische Metriken. --describe gibt eine kompakte ID-/Positions-/Label-/Verbindungsübersicht aus; --dump gibt rohes Szenen-JSON aus
scripts/render_preview.mjs	Headless PNG-Vorschau über mcp-excalidraw-server render (kein Browser). LaTeX rendert leer – nur Layout
evals/evals.json	Regressionseingabeaufforderungen: eine pro Fehlermodus, der tatsächlich aufgetreten ist
examples/ea-table.md	Ein ausführbares In-App-Skript, das eine Tabelle aus Rechtecken + Text erstellt

Bearbeiten einer vorhandenen Canvas

1. Dekomprimiere sie, um den aktuellen Zustand zu verstehen (inspect_canvas.mjs --dump <datei> gibt Szenen-JSON aus).
2. Bevorzuge die Neugenerierung aus dem Generator-Skript. Wenn der Benutzer manuelle Bearbeitungen vorgenommen hat, die es wert sind, behalten zu werden, schreibe eine gezielte Transformation (Szene lesen → bestimmte Elemente mutieren → unkomprimiert neu serialisieren), anstatt die gesamte Canvas neu zu schreiben.
3. Lasse niemals eine Canvas halb migriert: entweder jedes Bild hat seine Gleichung, oder keines.

Größen- und Typografie-Standards für diesen Vault

• Fließtext fontFamily: 6, roughness: 0, strokeWidth: 1.
• Titel 28–30 px, Spaltenkopf 19–22 px, Zeilenlabel 15–16 px, Formelbildhöhe 50–52 px.
• Zeilenabstand 116–130 px; Spaltenbreite 320–340 px; Lücke 28–40 px.
• Canvas-Hintergrund #ffffff; Tinte #1e1e1e; gedämpft #868e96; Haarfein #e9ecef.