beautiful-mermaid 実装 skill

検証バージョン: beautiful-mermaid@1.1.3 検証日: 2026-05-09 対象: Mermaid 記法の図を build 時 / runtime で SVG 化したい実装作業

beautiful-mermaid は Mermaid 記法 → SVG/ASCII を 同期 + ゼロ依存 + DOM 非依存で render できるライブラリ。公式 mermaid と違い、Node / Bun / Deno / browser のどこでも動く。Astro の build 時にそのまま図に変換できる。

まず詰まる 3 点

公式 mermaid パッケージとは別物。検索で混ざる。
対応図種は限定的(v1 系):flowchart / sequence / class / ER は OK。gantt / mindmap / journey は未サポート or 制限あり
テーマ / 色のカスタマイズは v1 系では限定的(%%{init: {...}}%% ディレクティブは未対応)

最小サンプル

import { renderMermaidSVG } from "beautiful-mermaid";

const code = `graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Path A]
  B -->|No| D[Path B]`;

const svg = renderMermaidSVG(code);    // SVG string
const ascii = render(code, { format: "ascii" }); // ASCII art string

render() は同期関数。文字列を返すだけなので、Node / browser のどちらでも追加 setup 不要。

Astro コンポーネント(build 時 SVG)

---
import { renderMermaidSVG } from "beautiful-mermaid";

interface Props {
  code: string;
  caption?: string;
  maxWidth?: string;
}
const { code, caption, maxWidth = "100%" } = Astro.props;

let svg = "";
let error: string | null = null;
try {
  svg = renderMermaidSVG(code);
} catch (e) {
  error = (e as Error).message;
}
---

<figure>
  <div style={`max-width: ${maxWidth}; overflow-x: auto`}>
    {error ? <pre>{error}</pre> : <div set:html={svg} />}
  </div>
  {caption && <figcaption>{caption}</figcaption>}
</figure>

<style>
  figure :global(svg) {
    max-width: 100%;
    height: auto;
    display: block;
  }
</style>

MDX から <Mermaid code={...} /> で呼び出せる。

React Island(runtime インタラクティブエディタ)

import { useMemo, useRef, useEffect, useState } from "react";
import { renderMermaidSVG } from "beautiful-mermaid";

export function MermaidEditor() {
  const [code, setCode] = useState("graph TD\n  A --> B");
  const containerRef = useRef<HTMLDivElement>(null);

  const svg = useMemo(() => {
    try { return renderMermaidSVG(code); } catch { return ""; }
  }, [code]);

  useEffect(() => {
    if (containerRef.current) containerRef.current.innerHTML = svg;
  }, [svg]);

  return (
    <div className="grid md:grid-cols-2">
      <textarea value={code} onChange={(e) => setCode(e.target.value)} />
      <div ref={containerRef} />
    </div>
  );
}

Astro 側では <MermaidEditor client:load /> で hydrate(MDX に直接埋め込める)。

表示の調整

方向(TD / LR / TB / RL)

graph TD    # Top-Down
graph LR    # Left-Right(横長な図に向く)
graph BT    # Bottom-Top
graph RL    # Right-Left

Subgraph(クラスタリング)

graph TD
  subgraph Public
    A[/articles/]
    B[/skills/]
  end
  subgraph Private
    C[(editorial-skills)]
  end
  A -.-> C

ノード形状(ラベル囲み記号)

記法	形	用途
`A[文字]`	角丸長方形	一般的なステップ
`A(文字)`	楕円	開始 / 終了
`A{文字}`	ひし形	条件分岐
`A[(文字)]`	DB / シリンダ	データストア
`A>文字]`	旗	出力 / 報告

エッジの種類

A --> B    # 矢印
A -.-> B   # 点線矢印
A ==> B    # 太矢印
A -- ラベル --> B

対応図種(v1 系)

種別	対応	備考
flowchart(`graph`)	✅	TD / LR 等の方向、subgraph、各種ノード形状
sequenceDiagram	✅	participant, ->>, —>>, activate/deactivate
classDiagram	✅	クラス + 関係(*—、—、..>、<\|—)
erDiagram	✅	エンティティ + リレーション(\|\|—o{ 等)
stateDiagram	⚠	限定対応
gantt	❌	未サポート(v1.1.x 時点)
mindmap	❌	同上
journey	❌	同上

公式 mermaid パッケージなら全てサポート、ただし bundle / runtime コストは大きい。

よく詰まる落とし穴

テンプレート文字列(` `)で渡すのが安全 — JSX の { } と Mermaid の {} が混じる場合は文字列リテラル化必須
< を含むラベル(<ISBN> など)はそのままで OK — beautiful-mermaid 側でエスケープされる
render() が throw したらどうするか — try/catch で囲み、エラー時は文字列のまま <pre> 表示にする(編集中の構文ミスをユーザーに見せる)
大きい図で build が遅くなる — 5 ノード × 10 図ぐらいまで快適、それ以上は分割
SVG のサイズ調整は CSS 側で — svg { max-width: 100%; height: auto } を CSS で当てる
ダークモード対応 — SVG 内部色は固定なので、CSS の filter: invert(1) hue-rotate(180deg) 等で疑似対応 or 公式 mermaid の theme 機能を使う

図種の選び方

何を表現するか	推奨図種
プロセス / 業務フロー / 条件分岐	flowchart(graph)
API 呼び出しの順序 / 通信プロトコル	sequenceDiagram
ドメインモデル / クラス階層	classDiagram
データベーススキーマ / エンティティ関係	erDiagram
状態遷移	stateDiagram(限定対応)

迷ったら flowchart から始めて、抽象度が合わなければ別図種に切り替える。

向く / 向かないケース

向く: 静的サイト(Astro / Next.js)の記事への図埋め込み、Node スクリプトでの SVG 生成、AI agent の図出力(LLM の chain-of-thought 可視化など)
向かない: gantt / mindmap / journey が必要な場面 → 公式 mermaid を browser ロード
向かない: テーマ / フォントの厳密なブランド統制 → SVG 後処理 or 別ダイアグラムライブラリ

参考

npm: beautiful-mermaid
GitHub: https://github.com/lukilabs/beautiful-mermaid
Mermaid 記法本体: https://mermaid.js.org(beautiful-mermaid は記法のサブセットを実装)

beautiful-mermaid-render-recipes