Mermaid.js入門：JavaScriptで簡単にダイアグラムを作成する方法【WordPress対応】│JScriptKatana

1 1. Mermaidとは何か
- 1.1 Mermaidの概要と特徴
- 1.2 Mermaidの主な用途とメリット
  - 1.2.1 用途
  - 1.2.2 メリット
2 2. Mermaidの基本的な使い方
3 3. Mermaid.jsを使用したダイアグラムの作成
4 4. WordPressでのMermaidの活用方法
5 5. Mermaidを活用する際のベストプラクティス
6 6. まとめ

1. Mermaidとは何か

Mermaidの概要と特徴

Mermaidは、テキストベースでダイアグラムやチャートを作成できるJavaScriptライブラリです。このツールを使用することで、コードを記述するだけで視覚的な図を簡単に生成できます。フローチャート、シーケンス図、ガントチャートなどの図表を手軽に作成できるため、ソフトウェア開発者やプロジェクトマネージャーなどに広く利用されています。

Mermaidの最大の特徴は、コードのみでダイアグラムを定義できる点にあります。これにより、GUIを使わずに簡単に編集や管理が可能です。また、GitHubやNotionなどのプラットフォームにも統合されており、さまざまな場面で利用できる柔軟性を備えています。

Mermaidの主な用途とメリット

用途

ソフトウェア開発におけるフローチャートやシーケンス図の作成。
プロジェクト計画時のガントチャートの作成。
マークダウンファイルやWikiドキュメントでの視覚的表現。

メリット

シンプルな記法: プログラムを書くように記述できるため、初心者でも簡単に扱えます。
コードによる管理: コード管理ツール（例：Git）を利用してバージョン管理が可能です。
高速な作成と修正: コードを修正するだけで図の変更が即座に反映されます。
拡張性とカスタマイズ性: CSSでデザインをカスタマイズできるほか、JavaScriptによる機能拡張も可能です。

2. Mermaidの基本的な使い方

インストール方法

Mermaid.jsは、CDNリンクを利用する方法とnpmを使う方法の2通りでインストールできます。

1. CDNリンクを使用する方法

HTMLファイルに以下のスクリプトタグを追加します。

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8" />
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <div class="mermaid">
    graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
  </div>
</body>
</html>

2. npmを使用する方法

Node.jsの環境が整っている場合は、以下のコマンドでインストールできます。

npm install mermaid

この方法では、JavaScriptプロジェクトの一部として組み込むことができます。

基本的な記法と構文

Mermaid.jsでは、直感的なテキスト記法を用いて図を作成できます。ここでは代表的な例を紹介します。

1. フローチャート

以下はフローチャートの記述例です。

graph TD;
  A[開始] --> B[処理1]
  B --> C[処理2]
  C --> D[終了]

2. シーケンス図

システムの動作フローを示すためのシーケンス図は次のように記述します。

sequenceDiagram
  participant A as ユーザー
  participant B as サーバー
  A->>B: リクエスト送信
  B-->>A: 応答を返す

3. ガントチャート

プロジェクト管理に便利なガントチャートは以下のように記述できます。

gantt
  title プロジェクト計画
  dateFormat YYYY-MM-DD
  section 計画
  タスクA :a1, 2024-01-01, 10d
  タスクB :a2, after a1, 7d
  タスクC :a3, after a2, 5d

対応しているダイアグラムの種類

Mermaid.jsは以下の図表に対応しています。

フローチャート: プロセスの流れを示す。
シーケンス図: 通信プロトコルや手順の可視化。
ガントチャート: プロジェクト管理やスケジュール計画。
クラス図: オブジェクト指向設計に利用。
ステート図: 状態遷移を表す。
パイチャート: データの割合を視覚化。

3. Mermaid.jsを使用したダイアグラムの作成

HTMLへの組み込み方法

Mermaid.jsはHTMLに簡単に組み込むことができます。以下の手順に従ってダイアグラムを作成してみましょう。

1. HTMLの基本構成

以下のコードは、Mermaid.jsをHTMLで使用する最小構成の例です。

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8" />
  <title>Mermaidダイアグラム</title>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <h1>フローチャート例</h1>
  <div class="mermaid">
    graph TD;
      A[開始] --> B[処理1]
      B --> C[処理2]
      C --> D[終了]
  </div>
</body>
</html>

2. 複数のダイアグラムを表示する

複数のダイアグラムを表示したい場合は、次のようにHTML内に複数のdivタグを記述します。

<div class="mermaid">
  graph TD;
    A --> B;
    B --> C;
</div>
<div class="mermaid">
  sequenceDiagram
    participant A as ユーザー
    participant B as サーバー
    A->>B: リクエスト送信
    B-->>A: 応答を返す
</div>

JavaScriptによる初期化と設定

1. 初期化設定

以下のコードでは、Mermaid.jsをプログラムから初期化します。

mermaid.initialize({
  startOnLoad: true,
  theme: 'forest',
  flowchart: { curve: 'basis' },
});

この設定では、テーマを「forest」に変更し、フローチャートの線を曲線にカスタマイズしています。

2. 動的にダイアグラムを追加

次のコードは、JavaScriptを使って動的にダイアグラムを生成する例です。

const code = `
graph LR;
  X[スタート] --> Y[次へ進む];
  Y --> Z[終了];
`;
const element = document.querySelector('#dynamicChart');
element.innerHTML = code;
mermaid.init(undefined, element);

実際のコード例とその解説

例1: シーケンス図の作成

<div class="mermaid">
  sequenceDiagram
    participant User as ユーザー
    participant Server as サーバー
    User->>Server: データリクエスト
    Server-->>User: データレスポンス
</div>

例2: ガントチャートの作成

<div class="mermaid">
  gantt
    title プロジェクトスケジュール
    dateFormat YYYY-MM-DD
    section 開発フェーズ
      設計 :done, 2024-01-01, 2024-01-07
      実装 :active, 2024-01-08, 2024-01-20
      テスト :2024-01-21, 2024-01-30
</div>

4. WordPressでのMermaidの活用方法

プラグインの紹介と設定方法

WordPressでMermaid.jsを利用する場合、専用のプラグインをインストールするのが最も簡単です。ここでは、代表的なプラグインを紹介します。

1. Mermaid専用プラグイン – 「Mermaid Markdown Syntax Highlighting」

このプラグインはMermaid記法を直接記事内で使用できるようにします。

インストール手順

WordPressの管理画面にログインします。
メニューから「プラグイン」→「新規追加」をクリックします。
検索ボックスに「Mermaid Markdown Syntax Highlighting」と入力します。
プラグインをインストールし、有効化します。

設定手順

有効化後、設定画面から基本的なオプションを調整できます。
「テーマ」や「開始時に自動読み込み」などの設定をカスタマイズします。

記事内でのダイアグラム表示手順

プラグインをインストールしたら、記事内に以下のようなショートコードを使ってダイアグラムを表示できます。

例: フローチャートの挿入

[mermaid]
graph TD;
  A[開始] --> B[処理1]
  B --> C[処理2]
  C --> D[終了]
[/mermaid]

例: シーケンス図の挿入

[mermaid]
sequenceDiagram
  participant ユーザー
  participant サーバー
  ユーザー->>サーバー: リクエスト送信
  サーバー-->>ユーザー: レスポンス返却
[/mermaid]

例: ガントチャートの挿入

[mermaid]
gantt
  title プロジェクト計画
  dateFormat YYYY-MM-DD
  section 開発
    設計 :done, 2024-01-01, 2024-01-07
    実装 :active, 2024-01-08, 2024-01-20
    テスト :2024-01-21, 2024-01-30
[/mermaid]

注意点とトラブルシューティング

1. 表示されない場合の対処法

原因1: プラグインが正しく有効化されていない。
→ プラグインの設定を再確認して有効化します。
原因2: Mermaid.jsのスクリプトがロードされていない。
→ テーマや他のプラグインと競合している可能性があるため、プラグインを無効化して順番に確認します。

2. プラグインなしで手動設定する場合

プラグインを使わずに、以下のコードをテーマのfunctions.phpに追加することで、手動でMermaid.jsを組み込むことも可能です。

function add_mermaid_script() {
    echo '<script type="module">
        import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
        mermaid.initialize({ startOnLoad: true });
    </script>';
}
add_action('wp_footer', 'add_mermaid_script');

5. Mermaidを活用する際のベストプラクティス

複雑な図の管理方法

1. コードの分割と整理

複雑なダイアグラムを作成する際は、以下のポイントに注意してコードを整理しましょう。

セクションごとにコメントを追加する

%% フローチャートの開始部分
graph TD;
    A[開始] --> B[処理1]
%% 分岐処理
    B --> C[処理2]
    B --> D[処理3]

テンプレートを作成して再利用する
大規模なプロジェクトではテンプレートを用意し、複数の図で統一感を持たせることが重要です。

2. 外部ファイルで管理する

ダイアグラムのコードをHTMLファイルやMarkdownファイルに直接埋め込まず、外部ファイルに保存して管理することでメンテナンス性が向上します。

例: Mermaidコードを「diagram.mmd」に保存し、HTMLから読み込む。

<div id="diagram-container"></div>
<script>
  fetch('diagram.mmd')
    .then(response => response.text())
    .then((text) => {
      const container = document.getElementById('diagram-container');
      container.innerHTML = text;
      mermaid.init(undefined, container);
    });
</script>

カスタマイズとテーマ設定

1. テーマの適用

Mermaid.jsでは複数のテーマが用意されており、視覚的に魅力的なデザインを簡単に切り替えることができます。

テーマ一覧

デフォルト
ダーク
フォレスト
ネオン

設定例

mermaid.initialize({
  theme: 'dark',
});

2. カスタムCSSの適用

より細かなデザイン調整を行う場合は、CSSでスタイルを定義できます。

.mermaid text {
  font-family: Arial, sans-serif;
  fill: #333;
}

パフォーマンスへの配慮

1. 初期化タイミングを調整する

ページ読み込み時ではなく、ユーザーが必要なタイミングでダイアグラムを初期化することで、処理負荷を軽減できます。

const config = {
  startOnLoad: false,
};

mermaid.initialize(config);

// 必要なタイミングで描画
document.getElementById('render-btn').addEventListener('click', () => {
  mermaid.init();
});

2. 静的イメージへの変換

パフォーマンスが特に重要な場合は、Mermaid.jsで生成した図を画像ファイルとしてエクスポートし、静的画像として利用する方法もあります。これにより、ブラウザへの負荷を最小限に抑えられます。

6. まとめ

Mermaid.jsの魅力と利便性

Mermaid.jsは、コードベースでダイアグラムを作成できる強力なJavaScriptライブラリです。フローチャートやシーケンス図、ガントチャートなど、さまざまな種類の図を簡単に描画できるため、開発者やプロジェクトマネージャーにとって非常に便利なツールです。

このライブラリの最大の特徴は、シンプルな記法によって複雑な図表を効率的に作成できる点にあります。また、WordPressなどのCMSとも連携可能で、ブログ記事や技術資料内で視覚的な情報を提供する手段として優れています。

各セクションの振り返り

Mermaidとは何か
Mermaid.jsの基本概要や用途、導入メリットについて解説しました。
Mermaidの基本的な使い方
インストール方法から基本的な記法まで、実際に使用するための基礎を紹介しました。
Mermaid.jsを使用したダイアグラムの作成
HTMLやJavaScriptを活用して具体的にダイアグラムを作成する手順を詳しく説明しました。
WordPressでのMermaidの活用方法
WordPressとの連携方法やプラグインの使用手順を紹介し、記事内での活用事例を示しました。
Mermaidを活用する際のベストプラクティス
コード管理やパフォーマンス最適化、デザインのカスタマイズ方法について具体的なアドバイスを提供しました。

Mermaid.jsの今後の活用可能性

Mermaid.jsはオープンソースのプロジェクトであり、今後も新機能や対応形式が追加される可能性があります。また、GitHubやNotion、WordPressなど多くのプラットフォームへの対応が進んでおり、活用シーンはますます広がると考えられます。

ビジネス資料やプレゼン資料、プロジェクト管理ツールの強化など、さまざまな用途に応用できるため、学習と実践を重ねることでさらに効果的に活用できるようになるでしょう。

最後に

この記事では、Mermaid.jsの基本から応用までを幅広く解説しました。初心者でも始めやすく、プロフェッショナルな資料作成にも役立つこのツールをぜひ活用してみてください。

必要に応じて本記事を参照しながら、実際のプロジェクトや記事制作でMermaid.jsを取り入れてみましょう。

Mermaid.js入門：JavaScriptで簡単にダイアグラムを作成する方法【WordPress対応】