ハクソク

世界を動かす技術を、日本語で。

ブログの図を管理するために「Excalidraw」を使っています

56日前原文(blog.lysk.tech)

概要

  • Excalidraw を使い、フレームで要素を囲み自動的にSVGを生成する方法の導入
  • 手動エクスポートの煩雑さを GitHub Actions やVSCode拡張で自動化
  • ローカルプレビュー で即時反映、ブログ執筆体験の向上
  • 問題点と改善案、今後の展望についての考察
  • 他ユーザーへの共有と拡張利用の可能性

ExcalidrawによるSVG自動エクスポートの工夫

  • Excalidraw で技術的な課題分解やアーキテクチャ説明、ブログ用図解作成
  • 図とテキストの相互調整による作業効率化の重要性
  • 手動エクスポートでは1つの変更ごとに 9クリック 必要、約45秒消費
  • フレームで要素を囲み、export_プレフィックスでフレーム名を設定する運用
  • 自作Excalidraw拡張 でフレームごとにlight/dark両モードのSVG自動生成

GitHub Actionsによる自動化アプローチ

  • 変更された.excalidrawファイル を検知し、フレームを抽出

  • 各フレームを light/darkモード でSVGとしてエクスポート

  • 生成SVGをリポジトリへ自動コミットし、バージョン管理

  • 使用ライブラリ： JonRC/excalirender （bashスクリプトで制御）

  • GitHub Actionsワークフローで全工程を自動化

    • 変更ファイルの検出
    • 必要なツールのインストール
    • フレームごとのSVG出力（ファイル名自動調整）
    • コミット＆プッシュ

GitHub Actions方式の課題

  • excalirender ライブラリの描画バグ（ラベル表示等）
  • x86ベースDocker 依存でARM Macでは動作困難
  • ローカルでの即時確認不可、 GitHub経由での反映待ち が必要
  • ブログ記事のローカルプレビューで 画像が古いまま になる問題

VSCode拡張によるローカル自動エクスポート

  • VSCode用Excalidraw拡張 に自動エクスポート機能を追加
  • 開いている.excalidrawファイルの変更を監視
  • export_で始まるフレーム名を検出し、 2種類のSVG （light/dark）を自動生成
    • ファイル名例：${image_name}.light.exp.svg、${image_name}.dark.exp.svg
    • Excalidrawファイルと同じディレクトリに出力
  • ローカルプレビュー が即時反映、エディタで画像確認・補完が可能

結論と今後の展望

  • 作業効率と執筆体験の大幅向上 を実感
  • 数時間でツール導入・記事執筆が完了、実用性の高さに満足
  • 今後も SQLite on Git などの記事で積極活用予定
  • オリジナル拡張へのPRは見送り、 Issueでアイデア共有 を検討
  • GitHubリリース で拡張配布、他ユーザーの活用・フィードバックに期待

まとめ

  • Excalidrawの フレーム名運用＋自動エクスポート は、技術記事やドキュメント作成の生産性を大幅改善
  • GitHub Actions 方式と VSCode拡張 方式の比較・使い分け
  • コミュニティへの還元と、他開発者による発展の可能性

Hackerたちの意見

LLMを使って初期スキーマをブートストラップすることもできるよ、excalidraw MCPの「アプリ」でね。[0] でも、MCPの「アプリ」はまだ新しくて、あんまりサポートされてないんだ。[0] -- https://github.com/excalidraw/excalidraw-mcp [1] -- https://modelcontextprotocol.io/extensions/apps/overview

└

excalidraw-mcpが出たばかりのときは、あんまり良い体験ができなかったな。Claudeが生成した図はちょっと生っぽくて、洗練されてなかった。今はmermaidを使ってるけど、他の人がexcalidraw-mcpをどう使ってるのか聞いてみたいな。

Claude Codeを導入してから、うちの会社ではExcalidrawがかなり広まったよ。デフォルトのフォントがダサくて子供っぽくて使いにくいのが残念。

└

ホワイトボードの手書きって子供っぽいの？

いいね、私も先週似たようなことをしたよ。Payload CMSのカスタムブロックを作って、CMS内でexcalidrawの図を作成・更新できるようにしたんだ。ダークモードとライトモードの切り替えができて、インラインで表示したり外部SVGとしてレンダリングしたりもできる。先週末にはMCPサーバーをOAuthで追加して、図を生成・更新してClaudeから投稿の下書きに追加できるようにしたよ。APIの課金モデルを使わなくて済むし、カスタムUIを作る必要もないから便利だと思う。ここに例の投稿があるよ: https://www.janhouse.lv/blog/network/self-hosting-tailscale-... 元々はObsidianから投稿を同期したかったんだけど、画像処理があんまり良くなくて、時々必要な追加メタデータも必要だったから、いくつかの投稿を非表示にしたりパスワード保護したりnoindexにしたりできなかったんだ。

図を描くのが大好きなんだけど、どうしてみんなあんな変なツールを使えるのか本当に理解できない。なんか変だし、自分で使いやすくて見た目も良いものを作らなきゃいけなかった。[1] https://grafly.io

└

あの変な手書き風のスタイルが好きだな。図を使うときって、100%正確じゃなくて、むしろハイレベルなイラストとして使うことが多いから、合ってると思う。あのスタイルは、提示された概念の大体の精度を伝えてる気がする。それに、個人的には可愛いと思う。

└

Excalidrawでは、要素のプロパティで「雑さ」を減らしたり、完全に取り除いたりできるよ。

└

これ、めっちゃきれいだね。いい仕事してる！ほとんどのダイアグラムツールで同じような問題に直面してきたけど、見た目がイマイチか、価格が高すぎるかのどっちかなんだよね。手動で描く代わりに、Mermaidを使ってコードでダイアグラムを作る方法に切り替えたよ。[1] https://graphlet.xyz

└

背景の形がフォーカスされると、前面に出てきて、その上にある形を覆ってしまうんだ。

└

Excalidrawには1クリックで「雑さ」を変える機能があるよ。ドラフトやアイデア出しは「フル雑」モードでやって、読者にこれはまだ完全に考えられてない、または最終的な決定じゃないってことを示してる。議論や分析が終わったら、最終的なダイアグラムは「雑じゃない」ように変更して、フォントも手書きからサンセリフ体に変えるんだ。これで「これはコンセプトだよ」ってすぐに伝わるから、結構効果的だよ。多くの人がダイアグラムを見てすぐに結論に飛びつくからね。書いてあったら、もう完成してる/修正済み/正式なものだと思っちゃう。

└

自分の製品を広める一番の方法は、他の人の愛情のこもった労力を貶めないことだよ。ちょっとしたプロのヒント。

└

質問があります：1. ソースコードを公開する予定はありますか？ 2. SCM用のJSONをエクスポートして、更新やメンテナンスのために再インポートする方法は？

└

Whimsicalはホワイトボード/ダイアグラムアプリで、結構いい感じだと思う。あなたのアプリともあまり変わらないし。

└

「AIを使って図を生成するには、ツールバーのAIボタンをクリックしてGraflyフォーマットのリファレンスをコピーします。それをLLM（Claude、ChatGPT、Gemini…）に図の説明と一緒に貼り付けてください。LLMが返すJSONをコピーします。ツールバーのインポートJSONボタン()をクリックして、それを貼り付けます。」これ、超ユーザーフレンドリーだね！使い方の説明すら理解できないけど。

それは、すべてがリポジトリにあるべきだという考えにぴったり合ってるね。やっと、自分で画像を更新しなくて済むようになった。ありがとう！

└

お花ありがとう！

https://github.com/mermaid-js/mermaidの大ファンだよ。見た目はあんまりだけど、欲しいものには十分応えてくれる。

└

ここにいる著者だけど、私もmermaidをよく使ってる。プロセスフローやインタラクションのモデル化には、excalidrawより優れてると思う。必要なところではそれを使うつもりだけど、全体を視覚化するにはexcalidrawの方がずっといいね。

うわー、Excalidrawが「インポート」できるなんて知らなかった！これはすごいね。LLMにマーメイドを生成させられるし、そっちが得意なんだよね。それから、図を編集できるのもいい！

面白いアプローチだね。私はMermaidを多用していて、ちょっとした変更を加えたり、他の場所に公開するために一括生成・コピーするのが楽なんだ。でも、図を更新して自動的に出力ファイルを生成できるのはいいハイブリッドだね。

└

私もMermaidを使ってるけど、やっぱりClaudeで生成する方が簡単だからかな。大きなログファイルがあって、トレースの図が必要な時にはめっちゃ便利だよね。ブログで共有しなくても役立つし。

かなりクールだね。ライトモードとダークモードをサポートしてるのが素晴らしいと思う。ちなみに、私もExcalidrawの大ファンなんだ。ちょっと聞きたいんだけど、ライトモードとダークモードで別々のSVGファイルを使う理由ってあるの？ CSSを使った単一のSVGファイルなら、ユーザーの好みに応じて色を変えられるよ。ここに例があるよ：http://alejo.ch/3jj - この3つのプロットはあなたのモードを尊重するはずだよ（生成コードはここに置いてあるよ：https://github.com/alefore/mini_svg）。別々のファイルを使う理由があれば、ぜひ教えてほしいな（私がやってることにも当てはまるかもしれないから）。

└

俺の目標は、GitHubでもブログでもレンダリングできることなんだ。GitHubはCSSベースのダークモードをサポートしてないと思うけど。

俺はここでグラフビズを使って、まるで原始人みたいだよ。