AstroでMermaidから図をレンダリングする

Mermaid

Mermaidは、プレーンテキストの定義からフローチャート、シーケンス図、クラス図などをレンダリングするよく使われてるライブラリです。プレビューはMermaid Live Editorが見やすいです。

rehype-mermaidを使う

このブログでは、rehype-mermaidを使ってレンダリングをしています。MarkdownからHTMLに変換する途中でMermaidを検出し、レンダリングされた図（SVGまたは画像）に置き換えるrehypeプラグインです。

```mermaid コードブロック、またはHTML内の <pre class="mermaid"> を検出します。

インストール

npm install rehype-mermaid @astrojs/markdown-remark

Node.jsで実行する場合、rehype-mermaidは内部的にPlaywrightを使用して図をレンダリングするため、Playwrightとブラウザ(Chromium)が必要です。

npm install playwright
npx playwright install --with-deps chromium

設定

astro.config.mjsにrehype-mermaidを追加します。ダークモードに対応したスタイルを使いたかったのでimg-svgオプションを使います。strategyオプションの説明については後述します。

// astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import rehypeMermaid from "rehype-mermaid";

export default defineConfig({
  markdown: {
    processor: unified({
      gfm: true,
      rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],
    }),
  },
});

Markdownでの書き方

実際の記事のコードブロックでMermaid記法を使って書きます。図をあえて出したくない時はmermaidを指定しません。

フローチャートの例

flowchart LR
  A[Start] --> B[process]
  B --> C[end]

Github Actions

Cloudflare Pagesにデプロイする GitHub Actions ワークフローを定義しています。mainブランチにプッシュすると発火します。

ワークフローのステップは以下の通りです

Checkout — actions/checkout でソースを取得します
Node.jsのセットアップ — pnpm/action-setup と actions/setup-node でNode.js 24とpnpm 11を設定します
依存関係のインストール — pnpm ci
Chromiumのインストール — pnpm exec playwright install --with-deps chromium を実行し、rehype-mermaidが図をレンダリングするために必要な環境を整えます
ビルド — Mermaid図がSVGとしてレンダリングされ、data URLを持つ<img>としてHTMLに埋め込まれます
デプロイ — Cloudflare Pages にアップロードします

# .github/workflows/deploy-pages.yml
name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: cloudflare pages

    steps:
      - uses: actions/checkout@v6

      - uses: pnpm/action-setup@v6
        with:
          version: 11

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: pnpm

      - run: pnpm ci

      - run: pnpm exec playwright install --with-deps chromium

      - run: pnpm build
        env:
          NODE_ENV: production

      - uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=tadayou

本番にリリースされる際にはレンダリング済みの図がHTMLに含まれており、ランタイムでMermaidのJavaScriptを読み込む必要はありません。

レンダリングパターン

rehype-mermaidは出力形式を制御する strategy オプションがあります。それぞれ使いどころがあるようです。

strategy	説明	嬉しいところ	`dark` オプション
`'inline-svg'`	インラインの `<svg>` を出力	CSSで色やサイズを調整しやすく、JSなしで表示可能	❌ 非対応
`'img-svg'`	SVGデータURLの `<img>` を出力	DOMを汚さず、ページ側CSSとの干渉を避けやすい	✅ 対応
`'img-png'`	PNGデータURLの `<img>` を出力	見た目を完全に固定でき、SVG非対応環境でも扱いやすい	✅ 対応
`'pre-mermaid'`	`<pre class="mermaid">` を残し、クライアント側で描画	実行時にテーマや内容を動的に変えられる	❌ 非対応

まとめ

rehype-mermaidを使うとカンタンにMermaid図を表示することができる
strategyのオプションによってはダークモード対応してないものがある

ドキュメントやブログでMermaidを使いたい場合は、rehype-mermaidをぜひ試してみてください。