mermaid-graph-renderer

Mermaid グラフレンダラー

Web とオフラインの両方で、Mermaid 図を本番品質の SVG、PNG、PDF にレンダリングします。遅延読み込みによるクライアントサイドレンダリングから、最大 1000 倍高速なネイティブ Rust による一括エクスポートまで、幅広くカバーします。

主な制約

Mermaid.js はテキストの寸法計算にブラウザー API（document.createElement、SVGTextElement.getBBox()）を必要とします。ブラウザー以外でレンダリングするには、ヘッドレスブラウザーを組み込むか、レンダラーを一から再実装する必要があります。この制約が、以下のすべての判断に影響します。

---

使用する場面

✅ 以下に使用します：

• Web ページ上で Mermaid 図をレンダリングする（パフォーマンス最適化）
• 図を SVG、PNG、PDF にエクスポートする（オフライン／CLI）
• 図の画像を生成する CI/CD パイプラインを設定する
• プロジェクトで使用するレンダリングライブラリを選択する
• ドキュメントサイトで Mermaid の読み込み時間を最適化する

❌ 以下には使用しません：

• Mermaid 構文を記述する（mermaid-graph-writer を使用してください）
• Mermaid 以外の形式をレンダリングする（PlantUML、GraphViz — Kroki を参照）
• 一般的な画像処理や編集

---

レンダリングの判断ツリー

flowchart TD
  A{Where are you rendering?} -->|Browser| B{Performance matters?}
  A -->|CLI / CI| C{Volume?}
  A -->|Server-side| D{Must avoid client JS?}

  B -->|Yes| E[Lazy-load mermaid.js]
  B -->|No| F[CDN script tag]

  C -->|1-10 diagrams| G[mermaid-cli]
  C -->|10-100 diagrams| H{Need multiple formats?}
  C -->|100+ diagrams| I[mmdr Rust renderer]

  H -->|Mermaid only| G
  H -->|Multiple languages| J[Kroki]

  D -->|Yes, zero JS| K[Build-time with Puppeteer]
  D -->|Some JS OK| E
  K -->|Slow builds warning| L[rehype-mermaid + Playwright]

---

Web レンダリング

オプション 1：遅延読み込みの mermaid.js（推奨）

一部のページだけに図があるドキュメントサイト、ブログ、アプリに最適です。

仕組み：ライブラリを読み込む前に .mermaid 要素があるか確認します。約 480 KB のコストが発生するのは、実際に必要なページだけです。

// Lazy load pattern — only loads mermaid.js when diagrams exist
function initMermaid() {
  const diagrams = document.querySelectorAll('.mermaid');
  if (diagrams.length === 0) return;

  const script = document.createElement('script');
  script.src = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
  script.onload = () => {
    mermaid.initialize({ startOnLoad: false, theme: 'neutral' });
    mermaid.run({ nodes: diagrams });
  };
  document.head.appendChild(script);
}

// Handle initial load + SPA navigation
document.addEventListener('DOMContentLoaded', initMermaid);
// For SPA route changes: call initMermaid() after navigation

重要な点：新しい図のコンテンツが表示されたときに mermaid.run() を再実行し、初回のページ読み込みとクライアントサイドナビゲーション（SPA のルート変更）の両方に対応してください。

項目	値
バンドルサイズ	約 480 KB（コア + 遅延読み込みされる図のチャンク）
レンダリング時間	図 1 つあたり約 50～200 ms（クライアント）
図の対応範囲	全範囲（Mermaid の全タイプ）
最適な用途	ドキュメントサイト、ブログ、図をたまに使用するアプリ

オプション 2：@mermaid-js/tiny

CDN 利用向けに事前バンドルされたサブセットです。すべての図タイプを最初から含み、図のチャンクは遅延読み込みされません。合計サイズは小さめですが、即時に読み込まれます。

使用する場面：必要な図タイプが 1～2 種類とはっきりしており、単一ファイルのインポートを使いたい場合です。

オプション 3：ビルド時 SSR（通常は割に合いません）

Puppeteer／Playwright を使ってビルド時に SVG をレンダリングします。一見魅力的ですが、実際には扱いが大変です。

コスト：

• node_modules が約 280 MB 増加します（Puppeteer + Chromium）
• 起動してレンダリングするまで、図 1 つあたり約 2～3 秒かかります
• 5 秒のビルドが、図を約 30 個処理すると 45 秒になります
• Docker／CI の問題が発生します（Chrome のインストールが必要です）

実際に価値がある場合：JavaScript を完全にゼロにする厳格な要件がある場合、またはクライアントサイドレンダリングを完全に排除したいほど図が多数あるサイトの場合です。

ツール：rehype-mermaid（Playwright を使用）、rehype-mermaid-cli（公式 CLI をラップ）。

結論：JavaScript を完全にゼロにする厳格な要件がなければ、遅延読み込みによるクライアントサイドレンダリングのほうが、トレードオフとして優れています。

---

オフライン／CLI レンダリング

オプション 1：mermaid-cli（公式）

標準となる CLI ツールです。ヘッドレス Chromium を起動してレンダリングし、出力を取得します。

# Install
npm install -g @mermaid-js/mermaid-cli

# Basic usage
mmdc -i input.mmd -o output.svg
mmdc -i input.mmd -o output.png -b transparent
mmdc -i input.mmd -o output.pdf

# With config
mmdc -i input.mmd -o output.svg -t dark --configFile mermaid.config.json

# Batch: process Markdown with embedded diagrams
mmdc -i document.md -o document-with-images.md

# Docker
docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.svg

項目	値
速度	図 1 つあたり約 3000 ms（Chromium のオーバーヘッド）
出力	SVG、PNG、PDF
サイズ	約 280 MB（Puppeteer + Chromium）
対応範囲	全範囲（Mermaid の全タイプ、100% の互換性）
最適な用途	図が 1～50 個で、精度を最優先する場合

SVG の注意点：出力された SVG には <foreignObject> 要素が含まれ、Inkscape と rsvg-convert で問題が発生します。対処法：設定で "htmlLabels": false を指定するか、PNG にエクスポートしてください。

オプション 2：Kroki（マルチフォーマットゲートウェイ）

図のソースを適切なレンダリングエンジンに振り分ける、統一 HTTP API です。25 以上の言語に対応しています（Mermaid、PlantUML、GraphViz、D2、Excalidraw など）。

# Render via HTTP (self-hosted or kroki.io)
curl -X POST https://kroki.io/mermaid/svg \
  -H 'Content-Type: text/plain' \
  -d 'flowchart LR
    A --> B --> C' \
  -o diagram.svg

# Self-host via Docker Compose
# docker-compose.yml needs: yuzutech/kroki + yuzutech/kroki-mermaid

項目	値
速度	約 500～2000 ms（ネットワーク + レンダリング）
出力	SVG、PNG、PDF、JPEG
言語	25 以上（Mermaid、PlantUML、GraphViz、D2 など）
最適な用途	複数言語のパイプライン、CI/CD、ドキュメント生成ツール

Kroki が優れている場合：1 つのパイプラインで複数の図の言語を使う必要がある場合です。 向いていない場合：「Mermaid 図を 1 つレンダリングする」だけの場合は、過剰な構成です。

オプション 3：mmdr（ネイティブ Rust — 最速）

ネイティブ Rust による再実装です。ブラウザーも Node.js も不要です。mermaid-cli より約 1000 倍高速です。

# Install (Rust toolchain required)
cargo install mmdr

# Usage
mmdr input.mmd -o output.svg
mmdr input.mmd -o output.png  # via resvg, no browser

項目	値
速度	図あたり約 3 ms（1000 倍高速）
出力	SVG（ネイティブ）、PNG（resvg 経由）
サイズ	約 5～10 MB のバイナリ
対応範囲	13 種類の図（部分的な互換性）
最適な用途	100 個以上の図のバッチ処理、CI/CD の高速化

トレードオフ：Mermaid のすべての機能に対応しているわけではありません。フローチャートとシーケンス図は成熟していますが、その他の種類は対応状況に差があります。速度を優先して不完全さを許容するか、特殊なケースでは mermaid-cli に切り替えてください。

<foreignObject> の問題はありません：ネイティブ SVG テキストを使用するため、出力は Inkscape やその他の SVG ツールで利用できます。

---

比較表

基準	mermaid.js CDN	mermaid-cli	Kroki	mmdr（Rust）
実行環境	ブラウザー	Node + Puppeteer	Docker	ネイティブバイナリ
速度／図	約 100 ms	約 3000 ms	約 1000 ms	約 3 ms
SVG の品質	優秀	優秀	優秀	良好（改善中）
PNG の品質	該当なし	良好	良好	良好（resvg）
PDF エクスポート	該当なし	対応	対応	未対応
インストールサイズ	約 480 KB	約 280 MB	約 1 GB（Docker）	約 5～10 MB
図の対応範囲	全種類	全種類	全種類	13 種類
CI/CD との適合性	低い	中程度	良好	優秀
複数言語対応	なし	なし	あり（25 以上）	なし

---

用途別の推奨事項

用途	推奨事項	理由
図を時々使うドキュメントサイト	遅延読み込みする mermaid.js	必要なページでのみ読み込まれます
Next.js／SSR アプリ	動的インポート、ssr: false	ビルド時のレンダリングにこだわらないでください
静的ドキュメントを生成する CI/CD（Mermaid のみ）	速度重視なら mmdr、正確性重視なら mermaid-cli	1000 倍の高速化と、100％ の機能互換性のどちらを取るか
複数の図の言語を使う CI/CD	Kroki	PlantUML、Mermaid、GraphViz を 1 つの API で利用できます
印刷／PDF 用の一括エクスポート（図 100 個以上）	mmdr ＋ mermaid-cli のフォールバック	ほとんどの図は高速に処理し、特殊なケースは正確に処理できます
デスクトップアプリ（Electron／Obsidian／VS Code）	組み込みの mermaid.js	Chromium がすでに組み込まれています

---

避けるべきパターン

SSR へのこだわり

誤り：クライアント側の JS 480 KB を避けるために、CI で Puppeteer を設定するのに 3 日を費やすこと。 正解：mermaid.js を遅延読み込みします。480 KB は図のあるページでのみ取得されます。ほとんどのユーザーは気づきません。

foreignObject の落とし穴

誤り：mermaid-cli から SVG をエクスポートし、Inkscape で開けない理由に困惑すること。 正解：設定で "htmlLabels": false を指定するか、PNG に直接エクスポートします。

何でも 1 つのツールで済ませる

誤り：CI で 500 個の図に mermaid-cli を使うこと（ビルド時間が 25 分）。 正解：一括処理には mmdr を使い、完全な互換性が必要な少数の図には mermaid-cli を使います。