Markdown でドキュメントを書いていると、ブロック図が崩れて見にくいな……に悩まされたので、draw.io + Python でどうにかしたときのメモです。
Mermaid や PlantUML でシーケンス図や簡単なフローを書くのはチョー便利なんですが、ちょっと複雑な構成図になると途端にレイアウトが崩れたり、矢印が重なったりして「もういいや」ってなりますよねｗ
かといって draw.io で PNG を書き出して貼ると、後からちょっと直したいときに元の .drawio ファイルを探し回るハメになる。
draw.io の .drawio.png フォーマットを使えばこれが解消できて、PNG 1ファイルに図の XML が丸ごと入っているので後から draw.io で開いて編集できます。 しかも IBM Bob（IBM の AI コーディングエージェント、以下 Bob）に「この図を作って」と頼むと .drawio XML まで自動生成してくれる——そこに make-drawio-png というライブラリを組み合わせると、Bob が図を生成→PNG 化→Markdown 埋め込みまで全部やってくれます。なお汎用的に作ってあるので Claude Code からも同じ手順で使えます。
draw.io の .drawio.png ってなに
ファイル → エクスポート → PNG で「図のコピーを含める」のチェックを外して書き出した PNG は「ただの画像」なので、draw.io で再度開いても編集できません。
一方、ファイル → 名前を付けて保存 で形式に「編集可能なビットマップ画像 (.png)」を選ぶ（またはエクスポート時に「図のコピーを含める」にチェックを入れる）と、中身が違うファイルになります：
- PNG として普通に表示できる — ブラウザでも画像ビューアでも OK
- draw.io で開くと元の図が完全復元 — XML がそのまま入っているので
仕組みは PNG の tEXt チャンクに keyword=mxfile で XML を URL-encode して詰め込んでいるだけです。draw.io はこのチャンクを読んで復元し、画像ビューアはピクセルデータだけを見るので互いに干渉しません。
PNG シグネチャ (8 bytes)
IHDR チャンク (25 bytes)
tEXt チャンク ← ここに mxfile XML が URL-encoded で入っている
IDAT チャンク (圧縮ピクセルデータ)
IEND チャンク
図にするとこんな感じです（この画像自体も make-drawio-png で作った .drawio.png なので、GitHub から元ファイルを落として draw.io で開くとそのまま編集できます）：
ライブラリのインストール
この仕組みを Python から扱えるようにしたのが make-drawio-png です（自作の OSS です、技量不足のため粗いですがｗ）。
$ pip install make-drawio-png
Windows の注意:
pip install後にmake-drawio-pngコマンドが見つからない場合、Scripts ディレクトリが PATH に入っていない可能性があります。python -m make_drawio_pngを使えば PATH 不要で動きます。詳細は README の PATH ガイドを参照。
レンダリング（見た目のある PNG にする）には draw.io デスクトップが必要です：
# Windows
$ winget install JGraph.Draw
# macOS
$ brew install --cask drawio
# Linux
$ snap install drawio
インストールすれば自動検出されます。
使い方（3パターン）
パターン① 埋め込みのみ（draw.io 不要）
$ python -m make_drawio_png architecture.drawio
draw.io なしで動きます。生成される PNG は 1×1 の白いプレースホルダ画像ですが、draw.io で開けば元の図に戻ります。CI/CD 環境などでとりあえず再編集可能にしておきたいときに。
パターン② レンダリング + 埋め込み（推奨）
$ python -m make_drawio_png --render architecture.drawio
# → architecture.drawio.png (見た目あり + 再編集可能)
draw.io CLI でレンダリングした PNG に XML を埋め込むので、ビジュアルとして綺麗かつ再編集可能 なファイルができます。
パターン③ Python API から
from make_drawio_png import drawio_export, drawio_to_png
# 推奨: レンダリング + 埋め込み
drawio_export("architecture.drawio")
# → architecture.drawio.png
# 依存なし: 埋め込みのみ
drawio_to_png("architecture.drawio")
# → architecture.drawio.png (1×1 プレースホルダ)
Bob から使う
ここからが本題です。Bob の execute_command ツールから呼び出せます（Claude Code でも同じ手順で動きます）。
Bob に頼む基本プロンプトはこんな感じ：
システム構成図を draw.io で作成してください。
- ファイルは docs/architecture.drawio として保存
- python -m make_drawio_png --render で docs/architecture.drawio.png も生成
- README.md の「アーキテクチャ」セクションに画像を埋め込む
Bob が内部でやること：
-
.drawioXML を生成・保存（XML を直接書いてくれる） - draw.io CLI でレンダリング + XML 埋め込み：
python3 -m make_drawio_png --render docs/architecture.drawio - 生成した PNG を
read_fileで読み込んで内容確認（崩れていないかチェック） - Markdown に
を挿入
※ --render を付け忘れると read_file で真っ白な 1×1 画像が返ってくるので、Bob が「あ、render 忘れてる」と自分で気づいてくれます。これに何度助けられたことかｗ
Bob shell での注意点
Bob の shell は Bob を起動したプロセスの PATH を引き継ぎます。Windows スタートメニューや GUI から起動した場合、Scripts ディレクトリが PATH にないことが多いです。
# NG になりがち（PATH に Scripts がない場合）
$ make-drawio-png --render file.drawio
# OK（常に動く）
$ python3 -m make_drawio_png --render file.drawio
python -m 形式を使えば PATH の問題を完全に回避できます。
使い分けまとめ
| シーン | コマンド | draw.io 必要 |
|---|---|---|
| Bob が図を生成してプレビュー | python -m make_drawio_png --render file.drawio |
✅ |
| CI/CD・draw.io なし環境 | python -m make_drawio_png file.drawio |
❌ |
| Python スクリプトから（推奨） | drawio_export("file.drawio") |
✅ |
| Python スクリプトから（依存なし） | drawio_to_png("file.drawio") |
❌ |
さいごに
「Markdown の図が崩れる問題」、.drawio.png で解消されました。PNG として Markdown に貼れるし、draw.io で開けば後から直せるし、Bob に頼めば図ごと自動生成してくれるし——「1ファイルで完結する図」がこんなに楽とは思いませんでしたｗ。
Bob のカスタムインストラクションに「作図は必ず .drawio.png 形式」と書いておくと、毎回指示しなくてもよくなって地味に便利です。
ライブラリは MIT ライセンスで公開しています：https://github.com/phssakaigawa/make-drawio-png