blog.dopana

戻る

ブログ記事に ````mermaid` 構文でアーキテクチャ図を埋め込んだとき、読者がページを開くと本文はすぐ表示されるのに、図の部分だけ空白のまま待たされることがあります。そして数秒後、数メガバイトの JavaScript バンドルがダウンロード・実行されて突然図画が挿入され、画面全体がガタッと下にズレる(Cumulative Layout Shift:レイアウトシフト)現象を経験したことがあるかもしれません。

これは astro-mermaid など、ブラウザ側(クライアントサイド)で Mermaid を動的描画する仕組み特有の課題です。本記事では、astro-mermaid を完全に卒業し、Pele を用いてビルド時(SSG)に Mermaid を完全な静的 SVG に変換することで、クライアント側の JavaScript を 0KB に削減する方法を解説します。

課題:クライアントサイド描画のオーバーヘッド#

従来の astro-mermaid インテグレーションは、以下のようなクライアント依存の仕組みで動いていました:

  1. ビルド時:Astro は ````mermaidを単なる
    ` HTML タグとして出力。
  2. ページ読み込み時:ブラウザが重厚な mermaid.js(展開後 2MB〜3MB 以上)をまるごとダウンロード。
  3. 実行:クライアントの CPU で複雑なレイアウト計算(Dagre や D3、Elk)を実行して SVG を生成・挿入。
  4. ダークモード切り替え時:テーマが切り替わるたびに、JavaScript がすべての図を再パースして再描画。
新しい方式: remark-pele従来の方式: astro-mermaidMarkdown (.md)Astro Buildpre.mermaid を含む HTMLブラウザが HTML を読み込みmermaid.js バンドル (~2-3MB)をダウンロードクライアント JS が図を計算して描画(レイアウトシフト発生、低速)Markdown (.md)Astro Build + Pele静的 SVG が埋め込まれたHTMLブラウザが即座に図を表示(0KB JS, レイアウトシフトなし)

[!WARNING] 読者が JavaScript を無効化している場合や、モバイル回線の電波が不安定な環境では、クライアント側の図は描画に失敗し、読みにくい生のコードがそのまま残ってしまいます。

Pele とは? 10歳でもわかる解説(ELI5)#

家具の購入に例えてみましょう:

  • クライアントサイド描画は、100本のネジと組み立て説明書が入った「組み立て式家具(フラットパック)」が届くようなものです。読者(客)のブラウザが食事をする前に、まず自分でテーブルを組み立てなければなりません。
  • Pele は、職人が工場で完全に組み立て・研磨した完成品のテーブルが届くようなものです。箱を開けた瞬間から、読者は何の手間もかけずにテーブルを使うことができます。

Pele ↗ は、Obsidian の CEO である kepano 氏によって開発された超軽量の Mermaid レンダラーです。

  • 同期的(Synchronous)な静的生成:ヘッドレスブラウザ(Puppeteer など)を一切起動せず、Node.js や Bun の中で瞬時に Mermaid 構文を SVG 文字列へ変換します。
  • CSS 変数による動的テーマ適応:生成された SVG は --pele-bg や --pele-fg、--pele-surface、--pele-border などの標準 CSS 変数を使用します。ライト/ダークモードの切り替え時も、JavaScript による再描画なしで CSS のみで即座に色が反映されます。
  • 高い構文互換性:フローチャート、シーケンス図、クラス図、状態遷移図、ER図、Git グラフ、マインドマップ、タイムラインなど主要な図に対応しています。

実装ステップ:Pele を Astro に組み込む#

ステップ 1: Pele のインストール#

プロジェクトに pele を追加します:

bun add pele
# または npm: npm install pele
# または pnpm: pnpm add pele
bash

ステップ 2: Remark プラグイン remark-pele.ts の作成#

src/plugins/remark-pele.ts を新規作成します。このプラグインは Markdown の構文木(MDAST)を走査し、mermaid 言語指定されたコードブロックを Pele で SVG に変換して HTML ノードへ置き換えます:

[!TIP] idPrefix: pele-${diagramIndex}- を指定することで、同一ページ内に複数の図がある場合でも、矢印マーカーやグラデーションなどの SVG 内部 ID が衝突する事故を防ぎます。

ステップ 3: astro.config.ts の設定#

設定ファイル astro.config.ts で astroMermaid を削除し、remarkPlugins に remarkPele を登録します:

ステップ 4: CSS 変数によるテーマ設定#

グローバルスタイルシートで Pele 用のカラー変数をサイトのデザインシステムと紐付けます:

モバイル端末で横幅が収まりきらない図画をスムーズにスクロールできるようスタイルを定義します:

ステップ 5: 不要コードの削除とパッケージのアンインストール#

レイアウト(BaseLayout.astro など)に含まれていた mermaid.run() や MutationObserver 関連のクライアントスクリプトをまるごと削除します。

最後に、不要になった依存パッケージを削除します:

bun remove astro-mermaid mermaid
bash

移行前後の比較#

項目移行前 (astro-mermaid)移行後 (pele)改善効果
クライアント JS 容量約 2.5 MB (mermaid バンドル)0 KB100% 削減
レイアウトシフト (CLS)描画完了時に大きく発生0 (一切ズレない)完全解消
JS 無効時の表示エラー/生の文字が表示問題なく表示完全な堅牢性
テーマ切り替えの応答性JS 計算待ちによる遅延CSS のみで即座に反映極めて滑らか
ビルド所要時間N/A845枚の図を約1.5秒で変換圧倒的高速

まとめ#

Mermaid の描画をクライアント側から Pele によるビルド時静的 SVG 生成に移行することで、ページの表示速度を極限まで高め、レイアウトシフトを撲滅し、モバイルユーザーの通信量とバッテリー消費を大幅に削減することができました。

参考文献#