astro-mermaid を Pele に移行:ビルド時に SVG 静的生成
astro-mermaid を Pele に置き換え、Mermaid 図をビルド時に静的 SVG として事前レンダリング。クライアント JS を 0KB に削減し高速化を実現。
ブログ記事に ````mermaid` 構文でアーキテクチャ図を埋め込んだとき、読者がページを開くと本文はすぐ表示されるのに、図の部分だけ空白のまま待たされることがあります。そして数秒後、数メガバイトの JavaScript バンドルがダウンロード・実行されて突然図画が挿入され、画面全体がガタッと下にズレる(Cumulative Layout Shift:レイアウトシフト)現象を経験したことがあるかもしれません。
これは astro-mermaid など、ブラウザ側(クライアントサイド)で Mermaid を動的描画する仕組み特有の課題です。本記事では、astro-mermaid を完全に卒業し、Pele を用いてビルド時(SSG)に Mermaid を完全な静的 SVG に変換することで、クライアント側の JavaScript を 0KB に削減する方法を解説します。
課題:クライアントサイド描画のオーバーヘッド#
従来の astro-mermaid インテグレーションは、以下のようなクライアント依存の仕組みで動いていました:
- ビルド時:Astro は ````mermaid
を単なる` HTML タグとして出力。
- ページ読み込み時:ブラウザが重厚な
mermaid.js(展開後 2MB〜3MB 以上)をまるごとダウンロード。 - 実行:クライアントの CPU で複雑なレイアウト計算(Dagre や D3、Elk)を実行して SVG を生成・挿入。
- ダークモード切り替え時:テーマが切り替わるたびに、JavaScript がすべての図を再パースして再描画。
[!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 pelebashステップ 2: Remark プラグイン remark-pele.ts の作成#
src/plugins/remark-pele.ts を新規作成します。このプラグインは Markdown の構文木(MDAST)を走査し、mermaid 言語指定されたコードブロックを Pele で SVG に変換して HTML ノードへ置き換えます:
import type { Code, Root } from 'mdast';
import { render, type RenderOptions } from 'pele';
import { visit } from 'unist-util-visit';
export interface RemarkPeleOptions {
fontSize?: number;
fontFamily?: string;
renderOptions?: RenderOptions;
}
function escapeHtml(str: string): string {
return str
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
export default function remarkPele(options: RemarkPeleOptions = {}) {
const defaultFontSize = options.fontSize ?? 14;
const defaultFontFamily = options.fontFamily ?? 'Inter, system-ui, sans-serif';
return (tree: Root) => {
let diagramIndex = 0;
visit(tree, 'code', (node: Code, index, parent) => {
if (
node.lang &&
node.lang.trim().toLowerCase() === 'mermaid' &&
parent &&
typeof index === 'number'
) {
try {
diagramIndex++;
const idPrefix = `pele-${diagramIndex}-`;
const { svg } = render(node.value, {
idPrefix,
responsive: true,
fontSize: defaultFontSize,
fontFamily: defaultFontFamily,
...options.renderOptions,
});
// コードブロックを SVG を含むコンテナに置き換える
parent.children[index] = {
type: 'html',
value: `<div class="pele-diagram my-6 flex justify-center overflow-x-auto">${svg}</div>`,
};
} catch (err: unknown) {
const error = err as Error;
console.warn(`[remark-pele] 図のレンダリングに失敗しました:`, error?.message);
parent.children[index] = {
type: 'html',
value: `<div class="pele-error my-4 rounded-lg border border-red-500/50 bg-red-500/10 p-4"><p class="mb-2 font-mono text-xs text-red-500">Mermaid Render Error: ${escapeHtml(error?.message || String(err))}</p><pre class="overflow-x-auto text-xs"><code>${escapeHtml(node.value)}</code></pre></div>`,
};
}
}
});
};
}ts[!TIP]
idPrefix: pele-${diagramIndex}-を指定することで、同一ページ内に複数の図がある場合でも、矢印マーカーやグラデーションなどの SVG 内部 ID が衝突する事故を防ぎます。
ステップ 3: astro.config.ts の設定#
設定ファイル astro.config.ts で astroMermaid を削除し、remarkPlugins に remarkPele を登録します:
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkPele from './src/plugins/remark-pele.ts';
import astroMermaid from 'astro-mermaid';
export default defineConfig({
markdown: {
processor: unified({
remarkPlugins: [
remarkMath,
remarkPele,
],
rehypePlugins: [ /* ... */ ],
}),
},
integrations: [
astroMermaid({ /* ... */ }),
AstroPureIntegration(config),
],
});tsステップ 4: CSS 変数によるテーマ設定#
グローバルスタイルシートで Pele 用のカラー変数をサイトのデザインシステムと紐付けます:
:root {
/* Pele Mermaid theme tokens (Light mode) */
--pele-font: Inter, system-ui, -apple-system, sans-serif;
--pele-font-mono: monospace;
--pele-radius: var(--radius);
--pele-bg: transparent;
--pele-fg: hsl(var(--foreground));
--pele-muted: hsl(var(--muted-foreground));
--pele-line: hsl(var(--muted-foreground));
--pele-surface: hsl(var(--muted));
--pele-surface-alt: hsl(var(--card));
--pele-border: hsl(var(--border));
--pele-accent: hsl(var(--primary));
}
.dark,
[data-theme="dark"] {
/* Pele Mermaid theme tokens (Dark mode) */
--pele-bg: transparent;
--pele-fg: hsl(var(--foreground));
--pele-muted: hsl(var(--muted-foreground));
--pele-line: hsl(var(--muted-foreground));
--pele-surface: hsl(var(--muted));
--pele-surface-alt: hsl(var(--card));
--pele-border: hsl(var(--border));
--pele-accent: hsl(var(--primary));
}cssモバイル端末で横幅が収まりきらない図画をスムーズにスクロールできるようスタイルを定義します:
.pele-diagram {
margin-block: 1.75rem;
display: flex;
justify-content: center;
align-items: center;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
border-radius: var(--radius, 0.5rem);
padding: 0.5rem;
}
.pele-diagram svg.pele {
max-width: 100%;
height: auto;
display: block;
}cssステップ 5: 不要コードの削除とパッケージのアンインストール#
レイアウト(BaseLayout.astro など)に含まれていた mermaid.run() や MutationObserver 関連のクライアントスクリプトをまるごと削除します。
最後に、不要になった依存パッケージを削除します:
bun remove astro-mermaid mermaidbash移行前後の比較#
| 項目 | 移行前 (astro-mermaid) | 移行後 (pele) | 改善効果 |
|---|---|---|---|
| クライアント JS 容量 | 約 2.5 MB (mermaid バンドル) | 0 KB | 100% 削減 |
| レイアウトシフト (CLS) | 描画完了時に大きく発生 | 0 (一切ズレない) | 完全解消 |
| JS 無効時の表示 | エラー/生の文字が表示 | 問題なく表示 | 完全な堅牢性 |
| テーマ切り替えの応答性 | JS 計算待ちによる遅延 | CSS のみで即座に反映 | 極めて滑らか |
| ビルド所要時間 | N/A | 845枚の図を約1.5秒で変換 | 圧倒的高速 |
まとめ#
Mermaid の描画をクライアント側から Pele によるビルド時静的 SVG 生成に移行することで、ページの表示速度を極限まで高め、レイアウトシフトを撲滅し、モバイルユーザーの通信量とバッテリー消費を大幅に削減することができました。