AI

Mermaidの使い方完全ガイド【インストールから応用まで】

Mermaidの使い方完全ガイド【インストールから応用まで】

システム開発において、ドキュメントの鮮度を保つことは常に大きな課題です。設計図やフローチャートは、プロジェクトの初期には丁寧に作成されますが、開発が進むにつれて変更が頻繁に発生します。手作業で図を更新するのは手間がかかり、やがてドキュメントは「陳腐化」していきます。

ドキュメントが古くなると、新しいメンバーはシステムの全体像を把握しにくくなります。チーム内の認識齟齬が生まれ、無駄なコミュニケーションコストが発生します。結果として、開発効率は低下し、品質にも悪影響を及ぼしかねません。

しかし、もしテキストを記述するだけで、自動的に美しい図が生成され、コードと同じようにバージョン管理できるとしたらどうでしょうか。Mermaidを使えば、そのような世界が実現します。テキストベースで図を管理し、常に最新の状態を保つことで、チームの生産性とコミュニケーションは飛躍的に向上します。

本記事では、Mermaidの基本的な使い方から、実際の開発現場で役立つ応用例、そして他のツールとの組み合わせまで、網羅的に解説します。

Mermaidとは

Mermaidは、Markdownライクなシンプルなテキスト記述から、UML図やフローチャートなどの様々な図を自動生成するJavaScriptベースのツールです。2019年には「JS Open Source Awards」の「The most exciting use of technology」部門を受賞し、その革新性が高く評価されています。

Mermaidが誕生した背景には、「Doc-Rot（ドキュメントの腐敗）」という問題意識があります。これは、ドキュメントが開発のスピードに追いつかず、すぐに古くなってしまう現象を指します。開発者は図の作成や更新に時間を取られ、その労力に見合う効果が得られないと感じがちです。

Mermaidは、このDoc-Rot問題に対する強力な解決策を提供します。テキストで図を定義するため、コードと同じように簡単に変更でき、Gitなどのバージョン管理システムで管理できます。これにより、ドキュメントの鮮度を高く保ち、開発とドキュメントの乖離を防ぎます。プログラマーだけでなく、非プログラマーでもMermaid Live Editorを使えば、手軽に高品質な図を作成できます。

インストール方法

Mermaidは様々な環境で利用できます。ここでは、Webページに直接組み込む方法と、Node.js環境で利用する方法、そしてCLIツールについて説明します。

Webページでの利用（CDN）

最も手軽な方法は、CDN（Content Delivery Network）経由でMermaidライブラリを読み込むことです。HTMLファイルに以下のスクリプトタグを追加するだけで、Mermaidの機能を利用できます。

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>Mermaidの例</title>
</head>
<body>
    <h1>Mermaidで描くフローチャート</h1>
    <pre class="mermaid">
graph TD
    A[開始] --> B{処理1?};
    B -- はい --> C[処理2];
    B -- いいえ --> D[終了];
    C --> D;
    </pre>

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

preタグにclass="mermaid"を指定し、その中にMermaidの記法で図を記述します。mermaid.initialize({ startOnLoad: true });を設定することで、ページロード時に自動的に図がレンダリングされます。

Node.js環境での利用（npm）

Node.jsプロジェクトでMermaidを利用する場合は、npm（Node Package Manager）を使ってインストールします。

macOS / Linux

npm install mermaid

Windows

npm install mermaid

インストール後、JavaScriptコード内でMermaidをインポートして利用できます。

import mermaid from 'mermaid';

async function renderMermaidDiagram() {
  const graphDefinition = `
graph TD
    A[準備] --> B(実行);
    B --> C{結果?};
    C -- 成功 --> D[完了];
    C -- 失敗 --> E[エラー処理];
    E --> D;
  `;

  // Mermaidを初期化します。
  mermaid.initialize({ startOnLoad: false });

  // 図をレンダリングします。
  const { svg, bindFunctions } = await mermaid.render('graphDiv', graphDefinition);

  // レンダリングされたSVGをDOMに挿入します。
  document.getElementById('mermaid-output').innerHTML = svg;
}

renderMermaidDiagram();

このコードは、指定されたMermaid記法からSVG画像を生成し、HTML要素に挿入する例です。

Mermaid CLIツール

Mermaid CLIは、Mermaidの図をコマンドラインから画像ファイル（SVG, PNG, JPGなど）として出力できるツールです。ドキュメント生成パイプラインに組み込む際に非常に便利です。

インストール

npm install -g @mermaid-js/mermaid-cli

基本的な使い方

Mermaid記法のファイルを指定して、画像ファイルを生成します。 例えば、flowchart.mmdというファイルに以下の内容を記述します。

graph TD
    A[ユーザー] --> B(Webサーバー);
    B --> C(データベース);
    C --> B;
    B --> A;

このファイルをPNG画像として出力するには、以下のコマンドを実行します。

mmdc -i flowchart.mmd -o flowchart.png

これにより、flowchart.pngという画像ファイルが生成されます。

基本的な使い方

Mermaidは様々な種類の図に対応しています。ここでは、特に利用頻度の高い3つの図の基本的な書き方を紹介します。

1. フローチャート (Flowchart)

処理の流れやシステムの構成を示す際に使います。graphキーワードの後に図の方向（TDは上から下、LRは左から右など）を指定し、ノードと矢印で関係を定義します。

graph TD
    A[開始] --> B(処理1);
    B --> C{条件分岐?};
    C -- はい --> D[処理2];
    C -- いいえ --> E[処理3];
    D --> F[終了];
    E --> F;

# mermaid.mmdというファイルに上記Mermaidコードを保存し、CLIでPNGを生成する例
mmdc -i mermaid.mmd -o flowchart.png

ノードの形状は、角括弧[]で四角、丸括弧()で楕円、波括弧{}でひし形、など様々な指定が可能です。

2. シーケンス図 (Sequence Diagram)

複数の参加者（オブジェクトやシステム）間のメッセージのやり取りを時系列で表現します。sequenceDiagramキーワードで始め、participantで参加者を定義し、->や-->でメッセージの流れを示します。

sequenceDiagram
    participant User as ユーザー
    participant Web as Webサーバー
    participant DB as データベース

    User->>Web: ログインリクエスト
    Web->>DB: ユーザー認証
    DB-->>Web: 認証結果
    alt 認証成功
        Web->>User: ログイン成功レスポンス
    else 認証失敗
        Web->>User: ログイン失敗レスポンス
    end

# mermaid.mmdというファイルに上記Mermaidコードを保存し、CLIでPNGを生成する例
mmdc -i mermaid.mmd -o sequence_diagram.png

alt/elseやloopなどの構造もサポートしており、複雑なロジックを表現できます。

3. クラス図 (Class Diagram)

オブジェクト指向システムのクラス構造、属性、操作、そしてクラス間の関係（継承、関連など）を表現します。classDiagramキーワードで始め、classでクラスを定義し、その中に属性やメソッドを記述します。

classDiagram
    class Animal{
        +name: string
        +age: int
        +eat()
    }
    class Dog{
        -breed: string
        +bark()
    }
    class Cat{
        -color: string
        +meow()
    }

    Animal <|-- Dog : 継承
    Animal <|-- Cat : 継承

# mermaid.mmdというファイルに上記Mermaidコードを保存し、CLIでPNGを生成する例
mmdc -i mermaid.mmd -o class_diagram.png

クラス間の関係は、<|--（継承）、--*（集約）、--o（コンポジション）、--（関連）などで表現できます。

便利な使い方・応用例 3選

Mermaidは、単に図を作成するだけでなく、実際の開発シーンで直面する具体的な課題解決に役立ちます。

1. システムアーキテクチャの可視化

複雑なシステムでは、複数のサービスやコンポーネントが連携します。これらを視覚的に整理することで、チーム全体の理解を深め、設計レビューを効率化できます。

課題: マイクロサービス間のデータフローや依存関係が複雑で、新しいメンバーが全体像を把握しにくい。ドキュメントが古く、実際のシステム構成と乖離している。

Mermaidによる解決策: フローチャートやC4モデル（簡易版）のような記法を用いて、サービス間の連携を明確にします。抽象度を一定に保つことで、全体像を素早く把握できるようにします。

コード例:

graph LR
    subgraph Frontend
        A[Web Browser]
    end

    subgraph Backend Services
        B(API Gateway)
        C[User Service]
        D[Product Service]
        E[Order Service]
    end

    subgraph Data Stores
        F[(User DB)]
        G[(Product DB)]
        H[(Order DB)]
    end

    A --> B
    B --> C
    B --> D
    B --> E

    C -- fetches --> F
    D -- fetches --> G
    E -- creates --> H

    C -. pub/sub .-> D : User Updated Event
    D -. pub/sub .-> E : Product Stock Changed Event

# mermaid.mmdに上記Mermaidコードを保存し、CLIでSVGを生成する例
mmdc -i mermaid.mmd -o architecture.svg

この図は、WebブラウザからAPI Gatewayを経由して、各バックエンドサービスがデータストアと連携する様子を示しています。サブグラフで論理的なグループ分けを行い、サービス間の非同期通信も表現できます。これにより、システムの全体像と主要なデータフローを一目で理解できるようになります。

2. プロジェクト管理と進捗共有

アジャイル開発では、スプリントやタスクの進捗をチーム全体で共有することが重要です。Mermaidのガントチャートやタスクグラフは、計画と実績を可視化し、プロジェクトの健全性を把握するのに役立ちます。

課題: プロジェクトのタスクが多く、各タスクの依存関係や進捗状況が分かりにくい。口頭での説明だけでは、認識にずれが生じやすい。

Mermaidによる解決策: ガントチャートやタスクグラフを活用し、タスクの開始日・終了日、担当者、依存関係を明確にします。これにより、プロジェクトの全体像とボトルネックを視覚的に共有できます。

コード例 (ガントチャート):

gantt
    title プロジェクトX開発スケジュール
    dateFormat  YYYY-MM-DD
    section 設計フェーズ
    要件定義      :a1, 2023-10-01, 7d
    システム設計  :a2, after a1, 10d
    DB設計        :a3, after a2, 5d
    section 開発フェーズ
    フロントエンド開発 :b1, after a3, 15d
    バックエンド開発   :b2, after a3, 20d
    API実装         :b3, after b2, 10d
    section テストフェーズ
    結合テスト    :c1, after b1, 5d
    システムテスト  :c2, after c1, 7d

# mermaid.mmdに上記Mermaidコードを保存し、CLIでPNGを生成する例
mmdc -i mermaid.mmd -o project_gantt.png

このガントチャートは、プロジェクトのフェーズと各タスクの期間、依存関係を明確に示します。afterキーワードを使うことで、タスク間の順序を簡単に定義できます。これにより、誰がいつまでに何を完了させるべきか、一目瞭然になります。

3. インシデント対応のタイムライン記録

インシデント発生時には、何が、いつ、どのように起こり、どのような対応が取られたかを正確に記録することが重要です。Mermaidのシーケンス図やフローチャートは、事象の発生から解決までの流れを時系列で可視化するのに適しています。

課題: インシデント発生時の状況や対応が複雑で、時系列での正確な記録が難しい。原因究明や再発防止策の検討時に、情報が不足しがち。

Mermaidによる解決策: シーケンス図やフローチャートを活用し、インシデントの発生から検知、対応、解決までのプロセスを詳細に記録します。注釈（note）を加えて、特定の時点での状況や判断、アクションを補足します。

コード例 (インシデント対応シーケンス):

sequenceDiagram
    autonumber
    participant Mon as 監視システム
    participant Ops as 運用チーム
    participant Dev as 開発チーム
    participant DB as データベース

    Mon->>Ops: アラート発生 (DB負荷上昇)
    Note over Mon,Ops: 2023-11-15 10:00 JST
    Ops->>Ops: アラート内容確認
    Ops->>Dev: インシデント報告
    Note over Dev: 状況把握のため調査開始
    Dev->>DB: ログ調査
    DB-->>Dev: 調査結果 (特定のクエリが原因)
    Dev->>Ops: 原因特定と対応案提示
    Ops->>Dev: 対応承認
    Dev->>DB: 問題クエリの停止/修正
    DB-->>Dev: 修正完了
    Dev->>Ops: 対応完了報告
    Ops->>Mon: 監視システム正常性確認
    Mon->>Ops: アラート解消
    Note over Mon,Ops: 2023-11-15 11:30 JST

# mermaid.mmdに上記Mermaidコードを保存し、CLIでPNGを生成する例
mmdc -i mermaid.mmd -o incident_timeline.png

このシーケンス図は、監視システムのアラートから始まり、運用チーム、開発チーム、データベースがどのように連携してインシデントを解決したかを時系列で示します。Noteを使って時間や状況を追記することで、詳細なインシデントレポートの基礎となります。これにより、インシデント発生から解決までの流れを正確に記録し、振り返りやナレッジ共有に役立てることができます。

他ツールとの組み合わせ

Mermaidは単体でも強力ですが、他のツールと組み合わせることでその真価を発揮します。

1. Markdownエディタ / GitHub

Mermaidの大きな利点は、Markdownファイル内で直接図を記述できることです。

  • VS Code: 「Markdown Preview Enhanced」や「Mermaid Preview」などの拡張機能をインストールすると、VS CodeのプレビューでMermaid図がリアルタイムにレンダリングされます。
  • GitHub: GitHubのMarkdownファイル（.md）内にMermaidコードを記述すると、GitHub上で自動的に図としてレンダリングされます。これにより、READMEファイルやWikiで視覚的な情報を簡単に共有できます。

組み合わせ方: Markdownファイル内に、バッククォート3つで囲み、言語指定としてmermaidと記述します。

```mermaid
graph TD
    A[開始] --> B[処理];
    B --> C[終了];
```

この記法は、多くのMarkdownパーサーや、VS Codeなどのエディタで認識され、図として表示されます。

2. ドキュメント生成ツール

技術ドキュメントの自動生成ツールと組み合わせることで、常に最新の図を含んだドキュメントを維持できます。

  • Sphinx: Pythonで書かれたドキュメント生成ツール。Mermaidをサポートする拡張機能があり、Mermaid記法から図を生成できます。
  • Docusaurus / MkDocs: 静的サイトジェネレーターで、技術ドキュメントサイトの構築によく使われます。これらのツールもMarkdown内のMermaid記法をレンダリングする機能を備えています。

組み合わせ方 (例: Docusaurus): Docusaurusでは、Markdownファイル内に上記GitHubと同じMermaid記法を記述するだけで、ビルド時に図がレンダリングされます。特別なプラグインの追加が必要な場合もありますが、多くは標準で対応しています。

3. Wikiシステム / コラボレーションツール

チーム内の情報共有基盤として利用されるWikiシステムやコラボレーションツールでもMermaidは活躍します。

  • Confluence: アトラシアンのConfluenceは、Mermaidマクロを提供しており、WikiページにMermaid記法で図を埋め込むことができます。
  • Notion: Notionは、コードブロック内でmermaid言語を選択することで、Mermaid図を直接レンダリングできます。
  • Jira: Jiraの課題説明やコメント欄でも、Mermaid記法をサポートするアドオンを利用することで図を表示できます。

組み合わせ方: 各ツールの提供する機能（マクロ、コードブロックの言語選択など）に従ってMermaidコードを記述します。これにより、プロジェクトの設計図やプロセスフローを、チームの共有スペースで手軽に作成・更新できます。

よくある設定・カスタマイズ

Mermaidは、図の見た目をカスタマイズするための豊富な設定オプションを提供しています。

1. テーマの変更

Mermaidにはいくつかの組み込みテーマがあり、図のスタイルを簡単に変更できます。

  • default
  • forest
  • dark
  • neutral
  • base

これらのテーマは、mermaid.initialize()メソッドのthemeオプションで指定できます。

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ 
        startOnLoad: true,
        theme: 'dark' // ここでテーマを指定
    });
</script>

または、Mermaid CLIで--themeオプションを使用します。

mmdc -i flowchart.mmd -o flowchart_dark.png --theme dark

2. 図の方向

フローチャートやグラフ図では、要素の配置方向を指定できます。

  • TD / TB: 上から下 (Top to Bottom)
  • BT: 下から上 (Bottom to Top)
  • LR: 左から右 (Left to Right)
  • RL: 右から左 (Right to Left)

これは図の定義の最初の行で指定します。

graph LR
    A[ノードA] --> B[ノードB];
    B --> C[ノードC];

3. フォントとスタイル

より詳細なカスタマイズには、CSS変数やカスタムCSSを利用します。mermaid.initialize()のthemeVariablesオプションで、色やフォントサイズなどを調整できます。

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ 
        startOnLoad: true,
        theme: 'base', // baseテーマを元にカスタマイズ
        themeVariables: {
            primaryColor: '#F0F8FF', // 背景色
            primaryTextColor: '#333', // テキスト色
            primaryBorderColor: '#007bff', // 枠線色
            lineColor: '#007bff', // 線の色
            fontFamily: 'Roboto, sans-serif' // フォント
        }
    });
</script>

Mermaid CLIでJSON設定ファイルを指定することも可能です。 例えば、mermaid-config.jsonというファイルを作成します。

{
  "theme": "neutral",
  "themeVariables": {
    "primaryColor": "#f5f5f5",
    "primaryTextColor": "#444",
    "lineColor": "#666",
    "fontSize": "16px"
  }
}

この設定ファイルをMermaid CLIで使用します。

mmdc -i flowchart.mmd -o flowchart_custom.png --configFile mermaid-config.json

これらの設定を使いこなすことで、ブランドガイドラインに合わせた図を作成したり、視認性を向上させたりできます。

今日からできる実行プラン

Mermaidの学習と活用を始めるための3ステップを紹介します。

ステップ1: Mermaid Live Editorで試す

まず、Mermaidの構文とレンダリング結果を直感的に把握するために、公式のMermaid Live Editor（https://mermaid.live/）を使ってみましょう。

  1. 上記URLにアクセスします。
  2. 左側のエディタにMermaid記法を記述します。
  3. 右側にリアルタイムで図が生成されるのを確認します。
  4. サンプルコードをロードしたり、様々な図の種類を試したりして、Mermaidの表現力を体験してください。

このステップで、Mermaidがどのように動作するかをすぐに理解できます。

ステップ2: Markdownファイルに組み込んでみる

Mermaidの基本的な使い方が分かったら、実際にMarkdownファイルに組み込んでみましょう。

  1. お好みのMarkdownエディタ（VS Codeなど）を開きます。
  2. 新規Markdownファイルを作成し、GitHubの項目で説明したMermaid記法で簡単なフローチャートやシーケンス図を記述します。
    ```mermaid
graph TD
    A[Hello] --> B[Mermaid];
```
  3. エディタのプレビュー機能や、GitHubにプッシュしてレンダリング結果を確認します。
  4. これにより、Mermaidが開発ワークフローにどのように統合できるかを体験できます。

ステップ3: 既存のドキュメントやREADMEに適用してみる

Mermaidに慣れてきたら、実際のプロジェクトで活用してみましょう。

  1. 現在作成中の、または既存のプロジェクトのREADMEファイルや技術ドキュメントを開きます。
  2. テキストの説明だけでは分かりにくい部分（システムのアーキテクチャ、処理フロー、デプロイ手順など）を探します。
  3. その部分をMermaid記法で図に置き換え、ドキュメントを更新します。
  4. チームメンバーに共有し、フィードバックを得ましょう。

このプロセスを通じて、Mermaidがドキュメントの品質向上とチームのコミュニケーション改善に貢献することを実感できるでしょう。今日からMermaidを使い始め、ドキュメントの「Doc-Rot」問題に終止符を打ちましょう。

参考文献

広告

-AI