Documentation Astro

Astroプロジェクトにダイアグラムを簡単に追加できるMermaidを導入する方法を解説します。Mermaidを使えば、フローチャート、シーケンス図、ガントチャートなどの視覚的な表現を簡単に作成できます。プロジェクトをよりビジュアルで魅力的にするために、さっそく導入方法を確認していきましょう。

この記事で学べること

  • Mermaidのインストールと基本設定
  • Astro用Mermaidコンポーネントの作成方法
  • 各種ダイアグラムの作成方法（フローチャート、シーケンス図、ガントチャートなど）
  • テーマのカスタマイズとスタイリング
  • ダークモード対応の実装

Mermaidとは

Mermaidは、テキストベースの記法でダイアグラムを作成できるJavaScriptライブラリです。コードを書くようにダイアグラムを定義でき、バージョン管理も容易です。

対応するダイアグラムの種類

ダイアグラム用途記法の開始
フローチャートプロセスの流れを表現graph TD / flowchart TD
シーケンス図オブジェクト間のやり取りsequenceDiagram
クラス図クラス構造の表現classDiagram
状態図状態遷移の表現stateDiagram-v2
ER図データベース設計erDiagram
ガントチャートプロジェクト管理gantt
パイチャート割合の可視化pie
マインドマップアイデアの整理mindmap

Mermaidのインストール

まず、Mermaidをプロジェクトにインストールします。以下のコマンドを使用して、npmを使ってインストールしましょう。

# npmの場合
npm install mermaid

# pnpmの場合
pnpm add mermaid

# yarnの場合
yarn add mermaid

MermaidChartコンポーネントの作成

次に、src/components/MermaidChart.astroというファイルを作成し、Mermaidチャートをレンダリングするコンポーネントを作成します。

基本的なコンポーネント

---
// src/components/MermaidChart.astro
interface Props {
  chart: string;
  theme?: 'default' | 'forest' | 'dark' | 'neutral' | 'base';
}

const { chart, theme = 'default' } = Astro.props;
const themedChart = `%%{init: {'theme':'${theme}'}}%%\n${chart}`;
---

<div class="mermaid">
  {themedChart}
</div>

<script>
  import mermaid from 'mermaid';

  // Mermaidの初期化設定
  mermaid.initialize({
    startOnLoad: true,
    securityLevel: 'loose',
    theme: 'default',
  });
</script>

<style>
  .mermaid {
    margin: 1.5rem auto;
    text-align: center;
  }

  .mermaid svg {
    max-width: 100%;
    height: auto;
  }
</style>

このコンポーネントは、渡されたchartを受け取り、Mermaidを使ってその内容をレンダリングします。themeプロパティでテーマを指定することもできます。

高度なコンポーネント（View Transitions対応）

Astroの View Transitions を使用している場合は、ページ遷移時にも正しく動作するように以下のように改良します。

---
// src/components/MermaidChart.astro
interface Props {
  chart: string;
  theme?: 'default' | 'forest' | 'dark' | 'neutral' | 'base';
  id?: string;
}

const { chart, theme = 'default', id } = Astro.props;
const themedChart = `%%{init: {'theme':'${theme}'}}%%\n${chart}`;
const uniqueId = id || `mermaid-${Math.random().toString(36).substr(2, 9)}`;
---

<div class="mermaid-container" id={uniqueId}>
  <div class="mermaid">
    {themedChart}
  </div>
</div>

<script>
  import mermaid from 'mermaid';

  // 初期化関数
  const initMermaid = () => {
    mermaid.initialize({
      startOnLoad: false,
      securityLevel: 'loose',
      theme: 'default',
    });

    // 全てのMermaid要素をレンダリング
    mermaid.run({
      querySelector: '.mermaid',
    });
  };

  // 初回ロード時
  initMermaid();

  // View Transitions対応
  document.addEventListener('astro:after-swap', initMermaid);
</script>

<style>
  .mermaid-container {
    margin: 1.5rem 0;
    overflow-x: auto;
  }

  .mermaid {
    display: flex;
    justify-content: center;
  }

  .mermaid svg {
    max-width: 100%;
    height: auto;
  }
</style>

テーマの適用

Mermaidには複数のテーマが用意されています。デフォルトのテーマを適用することもできますが、プロジェクトのスタイルに合わせてテーマをカスタマイズすることが可能です。

利用可能なテーマ

  • default - デフォルトテーマ

    %%{init: {'theme':'neutral'}}%% %%{init: {'theme':'default'}}%% graph TD A[開始] --> B{条件分岐} B -->|はい| C[処理1] B -->|いいえ| D[処理2] C --> E[終了] D --> E

  • forest - 緑基調のテーマ

    %%{init: {'theme':'neutral'}}%% %%{init: {'theme':'forest'}}%% graph TD A[開始] --> B{条件分岐} B -->|はい| C[処理1] B -->|いいえ| D[処理2] C --> E[終了] D --> E

  • dark - ダークテーマ

    %%{init: {'theme':'neutral'}}%% %%{init: {'theme':'dark'}}%% graph TD A[開始] --> B{条件分岐} B -->|はい| C[処理1] B -->|いいえ| D[処理2] C --> E[終了] D --> E

  • neutral - ニュートラルテーマ

    %%{init: {'theme':'neutral'}}%% %%{init: {'theme':'neutral'}}%% graph TD A[開始] --> B{条件分岐} B -->|はい| C[処理1] B -->|いいえ| D[処理2] C --> E[終了] D --> E

  • base - ベーステーマ（カスタマイズ用）

    %%{init: {'theme':'neutral'}}%% %%{init: {'theme':'base'}}%% graph TD A[開始] --> B{条件分岐} B -->|はい| C[処理1] B -->|いいえ| D[処理2] C --> E[終了] D --> E

コンポーネントの使用方法

作成したMermaidChartコンポーネントは、以下のように簡単に使用できます。

基本的な使い方

---
import MermaidChart from '../components/MermaidChart.astro';
---

<MermaidChart chart={`
  graph TD
    A[開始] --> B{条件分岐}
    B -->|はい| C[処理1]
    B -->|いいえ| D[処理2]
    C --> E[終了]
    D --> E
`} />

表示結果

%%{init: {'theme':'neutral'}}%% %%{init: {'theme':'default'}}%% graph TD A[開始] --> B{条件分岐} B -->|はい| C[処理1] B -->|いいえ| D[処理2] C --> E[終了] D --> E

様々なダイアグラムの作成例

フローチャート（詳細版）

フローチャートでは様々なノード形状やリンクスタイルが使えます。

graph TD
    A[四角形] --> B(角丸四角形)
    B --> C{ひし形}
    C -->|条件1| D[[サブルーチン]]
    C -->|条件2| E[(データベース)]
    D --> F((円形))
    E --> F
    F --> G>旗形]
ノード形状記法用途
四角形[テキスト]一般的な処理
角丸(テキスト)開始・終了
ひし形{テキスト}条件分岐
円形((テキスト))接続点
サブルーチン[[テキスト]]関数呼び出し
データベース[(テキスト)]データストア

シーケンス図

オブジェクト間のやり取りを時系列で表現します。

<MermaidChart chart={`
  sequenceDiagram
    participant U as ユーザー
    participant F as フロントエンド
    participant A as API
    participant D as データベース

    U->>F: ログインボタンクリック
    F->>A: POST /api/login
    A->>D: ユーザー検索
    D-->>A: ユーザー情報
    A-->>F: JWT トークン
    F-->>U: ダッシュボードへ遷移
`} />

ガントチャート

プロジェクトのスケジュール管理に使用します。

<MermaidChart chart={`
  gantt
    title プロジェクトスケジュール
    dateFormat YYYY-MM-DD
    section 企画
      要件定義     :a1, 2024-01-01, 7d
      設計        :a2, after a1, 5d
    section 開発
      フロントエンド :b1, after a2, 14d
      バックエンド   :b2, after a2, 14d
    section テスト
      単体テスト    :c1, after b1, 5d
      結合テスト    :c2, after c1, 5d
`} />

クラス図

オブジェクト指向設計の表現に使用します。

<MermaidChart chart={`
  classDiagram
    class User {
      +String id
      +String name
      +String email
      +login()
      +logout()
    }
    class Post {
      +String id
      +String title
      +String content
      +Date createdAt
      +publish()
    }
    class Comment {
      +String id
      +String body
      +Date createdAt
    }

    User "1" --> "*" Post : creates
    Post "1" --> "*" Comment : has
    User "1" --> "*" Comment : writes
`} />

ER図

データベース設計に使用します。

<MermaidChart chart={`
  erDiagram
    USER ||--o{ POST : creates
    USER ||--o{ COMMENT : writes
    POST ||--o{ COMMENT : has

    USER {
      string id PK
      string name
      string email UK
      datetime created_at
    }
    POST {
      string id PK
      string user_id FK
      string title
      text content
      datetime published_at
    }
    COMMENT {
      string id PK
      string post_id FK
      string user_id FK
      text body
      datetime created_at
    }
`} />

状態図

状態遷移を表現します。

<MermaidChart chart={`
  stateDiagram-v2
    [*] --> 下書き
    下書き --> レビュー中 : 提出
    レビュー中 --> 修正中 : 差し戻し
    レビュー中 --> 承認済み : 承認
    修正中 --> レビュー中 : 再提出
    承認済み --> 公開済み : 公開
    公開済み --> [*]
`} />

カスタマイズとスタイリング

Mermaidのスタイリングは、CSSを使ってさらにカスタマイズすることが可能です。

基本的なスタイリング

.mermaid {
  margin-top: 1rem;
  margin-bottom: 1rem;
}

.mermaid svg {
  margin-left: auto;
  margin-right: auto;
  display: block;
}

.mermaid .node rect {
  fill: white;
  stroke: #d1d5db;
}

.mermaid .edgePath .path {
  stroke: #9ca3af;
}

.mermaid .label {
  font-family: sans-serif;
  font-size: 0.875rem;
  color: #374151;
}

ダークモード対応

/* ダークモード対応 */
.dark .mermaid .node rect {
  fill: #374151;
  stroke: #6b7280;
}

.dark .mermaid .edgePath .path {
  stroke: #d1d5db;
}

.dark .mermaid .label {
  color: #e5e7eb;
}

/* ダークモードでのテーマ変数カスタマイズ */
.dark .mermaid {
  --mermaid-font-family: 'sans-serif';
  --mermaid-primary-color: #60a5fa;
  --mermaid-primary-text-color: #f3f4f6;
  --mermaid-line-color: #9ca3af;
}

カスタムテーマの定義

Mermaidのinitディレクティブを使って、細かくカスタマイズできます。

<MermaidChart chart={`
  %%{init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#3b82f6',
      'primaryTextColor': '#ffffff',
      'primaryBorderColor': '#2563eb',
      'lineColor': '#6b7280',
      'secondaryColor': '#f3f4f6',
      'tertiaryColor': '#fef3c7'
    }
  }}%%
  graph TD
    A[開始] --> B{判定}
    B -->|Yes| C[処理A]
    B -->|No| D[処理B]
    C --> E[終了]
    D --> E
`} />

トラブルシューティング

よくある問題と解決方法

問題原因解決方法
図が表示されないMermaidの初期化前にDOMが描画されたmermaid.run()を明示的に呼び出す
テーマが適用されないディレクティブの記法ミス%%{init: {'theme':'dark'}}%%の形式を確認
ページ遷移後に表示されないView Transitionsとの競合astro:after-swapイベントで再初期化
日本語が文字化けするフォント設定の問題CSSでfont-familyを明示的に指定

デバッグ用設定

mermaid.initialize({
  startOnLoad: true,
  securityLevel: 'loose',
  logLevel: 'debug', // デバッグログを有効化
});

まとめ

これで、AstroプロジェクトにMermaidを導入し、ダイアグラムを簡単に作成できるようになりました。

ポイントの振り返り

  • インストール: npm install mermaidで簡単に導入
  • コンポーネント化: 再利用可能なAstroコンポーネントを作成
  • 多様なダイアグラム: フローチャート、シーケンス図、ガントチャートなど対応
  • テーマ: 5種類の組み込みテーマ + カスタムテーマ
  • スタイリング: CSSでダークモード対応も可能

Mermaidを使うことで、複雑なフローチャートやシーケンス図、ガントチャートなどを視覚的に表現でき、プロジェクトのドキュメントやプレゼンテーション資料などにも活用できるでしょう。

参考文献

Mermaid

Mermaid

Create diagrams and visualizations using text and code.

mermaid.js.org
円