Astro ブログで Mermaid 図を使う

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

Mermaid とは

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

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

フローチャート

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

シーケンス図

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

クラス図

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

Git グラフ

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

状態遷移図

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

円グラフ

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

アーキテクチャ図

複数のサブグラフを使えば、システム全体の構成を一枚の図にまとめられます。このサイトの SSG ビルドからデプロイまでの流れを例に、大きめのダイアグラムを描いてみます。

実装方法

このサイトでの Mermaid 対応は、ビルド時に SVG へプリレンダリングする方式を採用しています。クライアント側で Mermaid ライブラリを読み込む必要がないため、バンドルサイズに影響しません。

全体の流れ

1. Markdown に ```mermaid ブロックを書く
2. rehype-mermaid プラグインがビルド時に検出
3. Playwright（ヘッドレス Chromium）で Mermaid を実行し SVG を生成
4. ライト / ダーク 2 種類の SVG を <picture> 要素として HTML に埋め込む
5. MermaidZoom コンポーネントがブラウザ上でズーム・パン操作を付与

使用パッケージ

パッケージ	役割
rehype-mermaid	rehype プラグイン。Mermaid コードブロックを SVG 画像に変換
playwright	rehype-mermaid が内部で使うヘッドレスブラウザ

Astro の設定

astro.config.mjs で rehype-mermaid を登録し、img-svg ストラテジーを指定しています。img-svg はレスポンシブな <picture> 要素を出力し、ダークモード用の SVG も同時に生成してくれます。

// astro.config.mjs（抜粋）
export default defineConfig({
  markdown: {
    rehypePlugins: [
      [rehypeMermaid, {
        strategy: 'img-svg',
        mermaidConfig: {
          theme: 'base',
          themeVariables: { /* ライトモード用の配色 */ },
        },
        dark: {
          mermaidConfig: {
            theme: 'base',
            darkMode: true,
            themeVariables: { /* ダークモード用の配色 */ },
          },
        },
      }],
    ],
  },
});

strategy: 'img-svg' を使うと、rehype-mermaid は次のような <picture> 要素を生成します。

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="data:image/svg+xml;...">
  <img src="data:image/svg+xml;..." alt="...">
</picture>

<source> の media 属性でダーク版とライト版を切り替える仕組みです。このサイトでは CSS クラスでテーマを制御しているため、テーマ切り替え時に JavaScript で media 属性を書き換えて同期させています。

Docker でのビルド環境

rehype-mermaid はビルド時にヘッドレス Chromium を起動するため、Docker 環境では Playwright のセットアップが必要です。

# ワークスペース設定をコピー（pnpm が playwright を解決するために必要）
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY apps/web/package.json apps/web/

# 依存をインストールした後に Playwright を実行
COPY --from=deps /app/node_modules ./node_modules
COPY --from=deps /app/apps/web/node_modules ./apps/web/node_modules
RUN pnpm --filter @shingolab/web exec playwright install --with-deps chromium

ポイントは、pnpm install の後に playwright install を実行することです。npm レジストリ上の最新 Playwright と pnpm-lock.yaml で固定されたバージョンではブラウザのリビジョンが異なるため、必ずプロジェクトの node_modules にある Playwright を使う必要があります。

MermaidZoom コンポーネント

ビルド時に生成された SVG 画像はそのままでは静的な画像です。大きなアーキテクチャ図などは細部が見づらくなるため、MermaidZoom コンポーネントでインタラクティブなズーム・パン機能を追加しています。

• ダブルクリックで 1.8 倍にズーム
• ドラッグで図をパン移動
• マウスホイールやピンチ操作でスケール調整（1〜5 倍）
• ツールバーで拡大・縮小・リセット
• テーマ切り替え時にライト / ダーク版 SVG を即座に切り替え

SVG のデータ URI をデコードしてインラインで描画し、viewBox を操作することで拡大してもシャープな表示を維持しています。

まとめ

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

ビルド時レンダリングのおかげで、ページを開いた瞬間から図が表示され、クライアント側に Mermaid ライブラリを読み込む必要もありません。

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