Astro ブログで Mermaid 図を使う

技術ブログを書いていると、文章だけでは伝えにくい「構造」や「フロー」を図で示したくなる場面があります。この記事では、Markdown のコードブロックから Mermaid ダイアグラムを描画できるようにした仕組みと、実際の使い方を紹介します。

Mermaid とは

Mermaid は、テキストベースの記法で図を描けるライブラリです。GitHub や Notion でもサポートされていて、馴染みのある方も多いのではないでしょうか。

コードブロックに mermaid と指定するだけで、SVG のダイアグラムに変換されます。

フローチャート

処理の流れを示す最も基本的な図です。

シーケンス図

API コールの流れなど、時系列のやり取りを表現するのに便利です。

クラス図

オブジェクトの関係を整理するときに使います。

Git グラフ

ブランチ戦略を視覚的に説明できます。

状態遷移図

テーマ切り替えのような状態管理の説明にも使えます。

円グラフ

簡単な割合の表示にも対応しています。

実装方法

このサイトでの Mermaid 対応は、以下の流れで動作しています。

1. Markdown の ```mermaid ブロックを Shiki が <code class="language-mermaid"> として HTML に変換
2. MermaidRenderer コンポーネントがページ読み込み時に該当ブロックを検出
3. Mermaid ライブラリを動的 import して SVG に置換

// mermaid ブロックがある場合のみライブラリを読み込む
const blocks = document.querySelectorAll('code.language-mermaid');
if (blocks.length === 0) return;

const { default: mermaid } = await import("mermaid");

ポイントは 動的 import です。Mermaid はバンドルサイズが大きいため、図を含まない記事ではライブラリ自体を読み込みません。

まとめ

Mermaid を使えば、図をわざわざ画像ツールで作る必要がなくなります。テキストで管理できるので Git との相性も良く、記事の更新時に図だけ古いまま……という問題も起きません。

対応している図の種類は他にもあるので、詳しくは Mermaid 公式ドキュメント を参照してください。