👋
MkDocs内のSVGをPNGに変換するプラグインをリリースしました
mkdocs-svg-to-png
これは、MkDocsでMarkdown内のSVGコードブロックやローカルSVGファイル参照をPlaywrightでPNGへ変換するプラグインです。
mkdocs-to-pdfでPDFを作る際に背景色やテーマ適用が抜け、図が正しく描画されない（とくにdraw.io生成のSVGで顕著）問題を回避するために、SVGを一度PNGに変換してからPDFへ含めます。
主な機能
- Markdownの
```svgコードブロックとローカル*.svgファイル参照を自動検出しPNG化 - PlaywrightベースのレンダリングでSVGの背景色や塗りつぶしを忠実に反映
-
enabled_if_envで環境変数がセットされたときだけ動作させる条件付き有効化 -
mkdocs serve時は自動的に変換をスキップし、編集時の待ち時間をゼロに維持 -
preserve_originalで変換後のPNGと元のSVGを併記可能（テーマ崩れの比較に便利） - ビルド後に生成PNGを削除する
cleanup_generated_imagesを備え、CIの一時ファイルを整理
動作要件
- Python 3.9+
- MkDocs 1.4.0以上、MkDocs Material 8.0.0以上
- Playwright 1.40.0以上（レンダリング用ブラウザのダウンロードが必要）
インストール
pipの場合:
pip install mkdocs-svg-to-png
python -m playwright install
uvを使う場合（開発向け推奨）:
uv add mkdocs-svg-to-png
uv run python -m playwright install
python -m playwright installでPlaywrightが使うブラウザを取得しないと、変換は失敗します。
クイックスタート
mkdocs.ymlでプラグインを登録します。enabled_if_envは有効化に使う環境変数名です。
plugins:
- search
- svg-to-png:
enabled_if_env: ENABLE_PDF_EXPORT
Mermaid → SVG → PNG → PDFをローカルで完結させる構成例:
plugins:
- search
- mermaid-to-svg:
enabled_if_env: ENABLE_PDF_EXPORT
- svg-to-png:
enabled_if_env: ENABLE_PDF_EXPORT
- to-pdf:
enabled_if_env: ENABLE_PDF_EXPORT
ENABLE_PDF_EXPORT と運用の考え方
PNG変換やPDF生成はPlaywright実行が入るため重い処理です。執筆中の高速なプレビューは維持しつつ、成果物生成はCIでのみ実行できるように環境変数で制御します。
- 日常の執筆:
mkdocs serveはプラグインが自動でスキップされるため、そのまま高速プレビュー - ローカル確認:
mkdocs build（環境変数なし）で通常の静的サイトだけを生成 - PDF/PNGを含むビルド:
ENABLE_PDF_EXPORT=1 mkdocs buildまたは
ENABLE_PDF_EXPORT=1 make buildをCIで実行する
この切り替えにより、作者は軽いプレビューを保ちつつ、CIでは完全なPDF付き成果物を得られます。
使い方
インラインSVG
```svg
<svg width="120" height="120">
<rect x="10" y="10" width="100" height="100"
stroke="black" stroke-width="3" fill="white" />
</svg>
検出されたブロックはPNGを生成し、対応する`<img>`参照に置き換わります。
### SVGファイル参照
ローカルファイル参照（HTTP経由は対象外）もPNG化されます。
```markdown
生成ファイルはdocs/assets/images/（output_dirのデフォルト）以下に配置され、サイトに
組み込まれます。
設定
| 設定項目 | デフォルト | 説明 |
|---|---|---|
enabled_if_env |
null |
指定した環境変数がセットされたときのみプラグインを有効化。未設定なら常に有効。 |
output_dir |
assets/images |
生成PNGの保存先。docs/からの相対パス。 |
preserve_original |
false |
PNG参照の下に元のSVGを残します。テーマ崩れ確認や差分比較に便利。 |
error_on_fail |
false |
変換失敗時にビルドを停止するかどうか。trueなら例外で中断。 |
log_level |
INFO |
プラグインのログレベル。ルートロガーがDEBUGの場合は自動的にDEBUGを採用。 |
cleanup_generated_images |
false |
ビルド完了後に生成PNGを削除します。CIのワークスペース掃除に有効。 |
PDF向け利用のポイント
-
mkdocs-mermaid-to-svgでMermaidをSVG化 - 本プラグインでSVGをPNG化し、背景・塗りつぶしを確実に残す
-
mkdocs-to-pdfでPDFを生成し、draw.ioを含む図も崩れず出力
トラブルシューティング
- Playwrightが見つからないエラー:
python -m playwright installを実行 - 生成先の権限エラー:
output_dirの書き込み権限とディスク容量を確認 - 変換結果を比較したい:
preserve_original: trueとlog_level: DEBUGで原因を切り分け - CIで失敗を検出したい:
error_on_fail: trueで変換エラー時にビルドを落とす
開発・メンテナンス
- 依存関係のセットアップ:
make install-dev - テスト:
make test（カバレッジ付きはmake test-cov） - 静的解析:
make format/make lint/make typecheck - ドキュメントビルド:
make build（PDF付きはENABLE_PDF_EXPORT=1 make build-pdf）
ライセンスと関連プロジェクト
- ライセンス: MIT
- 関連: mkdocs-mermaid-to-svg /
mkdocs-to-pdf
Discussion