Obsidian Excalidraw キャンバスビルダー
Obsidian Excalidraw プラグインで正しく開く .excalidraw.md ファイルを生成します。手書きの LaTeX ブロック、バインドされた矢印、テーマに沿った色を含みます。
使用するタイミング
- ボールト内にナレッジマップ/決定木/数式ボードを Excalidraw キャンバスとして作成する
- Markdown のアウトラインやノートを視覚的なキャンバスに変換する
- 画像が壊れて表示される、テキストが透明、数式が巨大、背景が白または黒になるなどの問題があるキャンバスを修正する
- 新しいキャンバスを、同じボールト内の既存キャンバスのビジュアル言語に一致させる
スタンドアロンの .excalidraw JSON（Web アプリ用）や PNG/SVG のレンダリングには使用しないでください。その区別が必要な場合は references/when-not-to-use.md を参照してください。
黄金のルール（苦労して学んだ教訓）
- LaTeX はテキストではない。数式は
type: "image"の要素であり、そのソースは## Embedded Filesセクションに<40-hex-id>: $$tex$$として存在します。対応する Embedded Files エントリがない画像要素は、壊れた画像としてレンダリングされます。references/latex.mdを参照してください。 - このプラグインでは、テキスト要素内に手動で
$$...$$を書かないでください。生のソースが表示されます。プラグインは Embedded Files に存在する数式のみをレンダリングします。 - シーンのテーマは信頼できない。プラグインは
appState.themeをアプリレベルのテーマで上書きします。したがって、キャンバスの色はviewBackgroundColorから決まりますが、ライトテーマは関係なく白で塗りつぶします。references/theme-and-color.mdを参照してください。 - 色をでっち上げる前に、同じボールト内の既存のキャンバスからパレットをコピーする。
scripts/inspect_canvas.mjsでキャンバスを解凍し、そのストローク色とフォントファミリーを読み取り、それらを再利用します。 - 数式の高さを揃え、幅は長さに基づいて決める。固定の大きな幅は短い数式を巨大に引き伸ばします。
references/layout.mdを参照してください。 - プラグインは
compressed-json(LZString base64、約120文字ごとに折り返し) として再保存する。保存されたファイルをパッチする代わりに、ジェネレータースクリプトからキャンバスを再生成してください。読み取りには解凍が必要です。scripts/inspect_canvas.mjsがそれを行います。 - 成功を主張する前に検証する。インスペクトスクリプトを実行し、確認してください：数式の数が画像の数と一致すること、ダングリングバインディングがないこと、テーマ/背景が意図通りであること。
- 「見た目が良い」は測定可能である。コンテナ比率 ≤ 30%、フォントサイズ ≤ 4種類、数式の高さの分散 0、重なり数 0。
scripts/inspect_canvas.mjsはこれらをaesthetic warningsとして表示するようになりました。すべての警告を欠陥として扱い、好みの問題として無視しないでください。references/design-metrics.mdを参照してください。 - 最初に削除してから、安定した ID で一度だけ書き込む。要素 ID はコンテンツ（テキスト/TeX/ラベルのハッシュ）から派生させる必要があり、ランダムであってはなりません。そして、対象ファイルを書き込む前にリンクを解除してください。この両方を行わないと、Obsidian で現在開いているキャンバスを再生成すると、新しい要素がライブシーンにマージされ、すべてが二重になり、プラグインが二重になったシーンを自動保存してしまいます。
references/troubleshooting.mdの「要素が二重/三重になる」を参照してください。 - 提供する前にレンダリングする。
scripts/render_preview.mjsはファイルをヘッドレス（Node、ブラウザ不要）でラスタライズします。PNG を見てください。JSON の監査は構造をチェックしますが、「間隔がおかしい」と判断できるのはピクセルだけです。そのプレビューでは LaTeX は空白になります（MathJax は Obsidian プラグイン内にあり、レンダラーにはありません）。したがって、レイアウトは PNG で、数式の正しさは## Embedded Filesで判断してください。 $$レイヤーは一つだけ。データモデル内の TeX は裸です (A=\int…)；デリミタは## Embedded Filesの行を出力するときだけ追加されます。生成されたファイル内の$$$は二重ラップのバグであり、リテラルのドル記号としてレンダリングされます。
二つのレイアウト流派 — 描画開始前に選択する
| 表格派 (Column grid) | 结构派 (Lines as structure) | |
|---|---|---|
| 形状 | 列ボックス + 行区切り線 | 幹線 + ドロップライン + 自由浮動テキスト |
| コンテナ比率 | 高い（列ごとにボックス） | ほぼ 0 |
| 読み味 | 検索表、厳密 | 講義ボード、軽量 |
| 最も適している場面 | セルごとに確認する多数の同レベル行 | 分岐、または相互に派生する列 |
| 失敗モード | 「スライドテンプレートのようだ」 | 枝が多すぎる → 線が交差する |
経験則: 兄弟列 → 表格派；ある列が他の列から派生する → 结构派。 どちらの例も design-metrics.md に同じ内容（第十講のキャンバス）で存在するので、選択前に比較できます。
ワークフロー
- 対象ボールトの規約を読む。ユーザーが気に入っている既存の
.excalidraw.mdを見つけ、node scripts/inspect_canvas.mjs <ファイル>を実行し、以下を記録する：テーマ、viewBackgroundColor、支配的なストローク色、fontFamily、roughness、典型的なフォントサイズ。 - 内容を列または行として設計する（
references/layout.md参照）— 数量/ステップのファミリーごとに1列、数式ごとに1行、そして実際に同じ数量のものだけをグループ化する。上の表に従ってレイアウト流派（表格派 vs 结构派）を選択する。 scripts/gen_canvas.mjsをモデルにジェネレータースクリプトを書く：そのCONFIGブロック（タイトル、列、行）を編集して実行する。30 kB の JSON を手動編集しない。スクリプトに付属する二つの安全機構（コンテンツ由来の ID、writeFileSyncの前のrmSync）を維持する。- 結果を
scripts/inspect_canvas.mjsで検査する、数/色/バインディングを修正する。また、ファイル内に$$$がないこと、要素数がジェネレーターが出力した数と一致することを確認する（倍数ならマージバグが発生している）。次に、scripts/render_preview.mjsでレンダリングし、実際に PNG を確認する。報告前に間隔/重なり/短い線を修正する。 - ユーザーが Obsidian で何をすべきかを報告する（ファイルを閉じて開き直す、または「現在の Excalidraw ファイルを解凍」コマンドを使用する）— プラグインはファイルが再度開かれたときだけ再読み込みします。
リファレンスマップ
| ファイル | 内容 |
|---|---|
references/file-format.md | 正確な .excalidraw.md の骨格、両方のエンコーディング、セクション順序、ヘッダーコメント |
references/element-schema.md | 要素タイプごとの必須フィールド、バインドテキスト、矢印バインディング、index 順序 |
references/latex.md | Embedded Files の契約、\color、サイジング、テスト済みの3つのレンダリングバリアント、失敗の兆候 |
references/theme-and-color.md | キャンバスが白く開く理由、matchThemeAlways、パレット抽出、このボールトで確立された色 |
references/layout.md | 列/行のジオメトリ、数式サイジングのヒューリスティック、キャンバスが未完成に見える理由 |
references/script-engine.md | プラグイン内の JS スクリプトエンジン：スクリプトの配置場所、何ができるか、ExcalidrawAutomate API、テーブルの作成可否、ファイルレベル生成とのトレードオフ |
references/design-metrics.md | 定量化された美学：コンテナ比率、フォントレベルの数、数式の分散、余白、意味的な色；二つのレイアウト流派；レンダラーなしでの検証方法 |
references/troubleshooting.md | これまでに見られたすべての失敗に対する症状 → 原因 → 修正の表 |
scripts/gen_canvas.mjs | 設定駆動のキャンバスジェネレーター（テキスト、ラテックス、矩形、水平線、矢印） |
scripts/inspect_canvas.mjs | 解凍 + 監査：テーマ、カウント、数式/画像の一致、バインディング、フォント、美的メトリクス。--describe はコンパクトな ID/位置/ラベル/接続のインベントリを出力；--dump は生のシーン JSON を出力 |
scripts/render_preview.mjs | mcp-excalidraw-server render によるヘッドレス PNG プレビュー（ブラウザ不要）。LaTeX は空白でレンダリングされる — レイアウトのみ |
evals/evals.json | 回帰プロンプト：実際に発生した失敗モードごとに1つ |
examples/ea-table.md | 矩形とテキストからテーブルを構築する、実行可能なアプリ内スクリプト |
既存のキャンバスの編集
- 解凍して現在の状態を理解する（
inspect_canvas.mjs --dump <ファイル>がシーン JSON を出力します）。 - ジェネレータースクリプトからの再生成を優先する。ユーザーが保存したい手動編集を行っている場合は、キャンバス全体を書き換えるのではなく、スコープ付き変換（シーンの読み取り → 特定の要素の変更 → 非圧縮での再シリアライズ）を記述する。
- キャンバスを中途半端な状態のままにしない：すべての画像に数式が対応しているか、まったくないかのいずれか。
このボールトのサイズとタイポグラフィのデフォルト
- ボディテキスト
fontFamily: 6、roughness: 0、strokeWidth: 1。 - タイトル 28–30 px、列ヘッダー 19–22 px、行ラベル 15–16 px、数式画像の高さ 50–52 px。
- 行間隔 116–130 px；列幅 320–340 px；ギャップ 28–40 px。
- キャンバス背景
#ffffff；インク#1e1e1e；ミュート#868e96；ヘアライン#e9ecef。