AI

Mermaidでドキュメント管理を自動化する【フローチャート・ER図・シーケンス図をコードで管理】

Mermaidでドキュメント管理を自動化する【フローチャート・ER図・シーケンス図をコードで管理】

ソフトウェア開発において、ドキュメントの維持管理は重要な課題です。特に、システムの設計図やプロセスの流れを示す図は、開発者間の共通認識を形成し、プロジェクトの品質を高めます。しかし、これらの図を最新の状態に保つことは容易ではありません。

手作業で図を更新するたびに、以下の問題に直面することがあります。

  • 更新の手間: 図形ツールの操作に時間がかかり、変更が頻繁だと負担が増大します。
  • バージョン管理の困難さ: 図のバイナリファイルは差分が確認しづらく、Gitでの管理が困難です。
  • テキストとの同期不足: コードやドキュメントの変更に、図の更新が追いつかないことがあります。
  • 閲覧環境の限定: 特定のツールがないと図が開けず、共有や閲覧に手間がかかります。

これらの悩みは、Mermaidを使えば解決できます。Mermaidは、Markdownのようなシンプルなテキスト記述から、フローチャート、ER図、シーケンス図などを自動生成するツールです。テキストベースで図を管理するため、コードと同じようにバージョン管理が可能になり、ドキュメントの鮮度を保ちやすくなります。

この記事では、Mermaidを活用してドキュメント管理を自動化するワークフローを紹介します。GitHubのREADMEにER図を埋め込んだり、Notionでフロー図を共有したり、CI/CDで図を自動生成してPNG画像として出力したりする実践例を通じて、Mermaidの強力な機能と手軽さを体感してください。

全体像：Mermaidを中心としたドキュメント管理ワークフロー

Mermaidを使ったドキュメント管理ワークフローは、以下のツールと連携して機能します。

  • Mermaid: テキストから図を生成するコアエンジンです。
  • Mermaid CLI (@mermaid-js/mermaid-cli): MermaidのテキストファイルをPNGなどの画像形式に変換するコマンドラインツールです。CI/CD環境での自動生成に活用します。
  • VS Code拡張機能 (Mermaid Preview): VS Code上でMermaidのテキストをリアルタイムでプレビューし、編集をサポートします。
  • GitHub: Markdownファイル（例: README.md）内のMermaidコードブロックを自動的にレンダリングし、図として表示します。
  • Notion: コードブロックやMermaidブロックとしてテキストを埋め込み、図を直接表示できます。
  • CI/CDツール (例: GitHub Actions): 特定のイベント（例: プッシュ時）をトリガーにMermaid CLIを実行し、図の画像を自動生成・更新します。

このワークフローを導入することで、開発者はテキストエディタで図を記述し、その変更が自動的にドキュメントや画像に反映されるようになります。

+-------------------+      +-----------------+      +---------------------+
|   Mermaid Text    |----->|     Mermaid     |----->|   Rendered Diagram  |
| (.mmd, .md files) |      |   (Core Engine) |      | (SVG, PNG, In-app)  |
+-------------------+      +-----------------+      +---------------------+
          |                          ^                         ^
          |                          |                         |
          v                          |                         |
+-------------------+      +-----------------+      +---------------------+
|   VS Code Ext.    |----->|   Mermaid CLI   |----->|    GitHub/Notion    |
| (Live Preview)    |<-----| (Image Export)  |      |  (Markdown Support) |
+-------------------+      +-----------------+      +---------------------+
          ^                          ^                         ^
          |                          |                         |
          +--------------------------+-------------------------+
                    CI/CD (e.g., GitHub Actions)

セットアップ手順

Mermaidを使ったワークフローを始めるには、いくつかのツールをセットアップする必要があります。ここでは、Node.js、Mermaid CLI、VS Code拡張機能のインストール手順を解説します。

1. Node.jsのインストール

Mermaid CLIはNode.js上で動作します。まだNode.jsがインストールされていない場合は、先にインストールしてください。Node.jsの公式ウェブサイトからインストーラーをダウンロードするか、バージョン管理ツール（例: nvm）を使用するのが一般的です。

例えば、macOSでHomebrewを使う場合は以下のコマンドでインストールできます。

# Node.jsをインストール
brew install node

Windowsの場合は、公式ウェブサイトからインストーラーをダウンロードし、指示に従ってインストールしてください。

インストール後、以下のコマンドでバージョンを確認し、正しくインストールされたことを確認します。

# Node.jsのバージョンを確認
node -v

# npmのバージョンを確認
npm -v

2. Mermaid CLIのインストール

Mermaid CLIは、Mermaidのテキストから画像ファイルを生成するために使用します。グローバルインストールすることで、どのディレクトリからでもコマンドを実行できるようになります。

# Mermaid CLIをグローバルインストール
npm install -g @mermaid-js/mermaid-cli

インストール後、以下のコマンドでバージョンを確認します。

# Mermaid CLIのバージョンを確認
mmdc -v

mmdcというコマンドがMermaid CLIの実行コマンドです。

3. VS Code拡張機能のインストール

VS Codeを使用している場合、「Mermaid Preview」拡張機能をインストールすると、Mermaidのテキストをリアルタイムでプレビューしながら編集できます。これにより、意図した通りの図が生成されるかを確認しながら作業を進められます。

  1. VS Codeを開きます。
  2. 左側のアクティビティバーにある「拡張機能」アイコンをクリックします（または Ctrl+Shift+X / Cmd+Shift+X）。
  3. 検索バーに「Mermaid Preview」と入力します。
  4. 「Mermaid Preview」という名前の拡張機能を見つけ、「インストール」ボタンをクリックします。

これで基本的なセットアップは完了です。Mermaidを使った図の作成と管理を始める準備が整いました。

実際の使い方：3つのシナリオ

Mermaidの強力な機能を具体的なシナリオを通じて見ていきましょう。ここでは、GitHubのREADMEにER図を埋め込む、Notionにフロー図を貼る、CIでPNG画像を出力する例を紹介します。

シナリオ1: GitHubのREADMEにER図を埋め込む

GitHubはMarkdownファイル内のMermaidコードブロックをネイティブでサポートしています。これにより、プロジェクトのREADME.mdにデータベースのER図などを手軽に埋め込み、常に最新の設計情報を共有できます。

1-1. ER図のMermaidコードを作成する

例えば、ECサイトのシンプルなデータベース構造を表すER図を作成します。example-er.mmdというファイル名で以下の内容を保存します。.mmdはMermaidのファイル拡張子です。

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT }|--o{ LINE_ITEM : part_of

    CUSTOMER {
        string customerId PK "顧客ID"
        string name "顧客名"
        string email "メールアドレス"
    }
    ORDER {
        string orderId PK "注文ID"
        string customerId FK "顧客ID"
        date orderDate "注文日"
        string status "注文ステータス"
    }
    LINE_ITEM {
        string lineItemId PK "注文明細ID"
        string orderId FK "注文ID"
        string productId FK "商品ID"
        int quantity "数量"
        float price "単価"
    }
    PRODUCT {
        string productId PK "商品ID"
        string name "商品名"
        float unitPrice "単価"
    }

このコードでは、erDiagramでER図の開始を宣言し、CUSTOMER、ORDER、LINE_ITEM、PRODUCTというエンティティ（テーブル）とその属性（カラム）を定義しています。PKは主キー、FKは外部キーを示します。||--o{のような記号は、リレーションシップ（関連）を表します。

1-2. README.mdに埋め込む

作成したMermaidコードをREADME.mdファイルに埋め込みます。Markdownのコードブロックとして、言語指定にmermaidを使用します。

# My Awesome Project

このプロジェクトは、Mermaidを使用してドキュメントを管理しています。

## データベースER図

以下は、このプロジェクトのデータベーススキーマを示すER図です。

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT }|--o{ LINE_ITEM : part_of

    CUSTOMER {
        string customerId PK "顧客ID"
        string name "顧客名"
        string email "メールアドレス"
    }
    ORDER {
        string orderId PK "注文ID"
        string customerId FK "顧客ID"
        date orderDate "注文日"
        string status "注文ステータス"
    }
    LINE_ITEM {
        string lineItemId PK "注文明細ID"
        string orderId FK "注文ID"
        string productId FK "商品ID"
        int quantity "数量"
        float price "単価"
    }
    PRODUCT {
        string productId PK "商品ID"
        string name "商品名"
        float unitPrice "単価"
    }

プロジェクトの概要

[プロジェクトの詳しい説明...]


この`README.md`をGitHubのリポジトリにプッシュすると、GitHubが自動的にMermaidコードをレンダリングし、ブラウザ上でER図として表示します。これにより、開発者は常に最新のデータベース設計図をGitHub上で確認できるようになります。

### シナリオ2: Notionにフロー図を貼る

NotionもMermaidの記述をサポートしており、ドキュメントやタスク管理の中に動的な図を埋め込めます。これにより、複雑なワークフローやプロセスを図解して、チームメンバーとの理解を深められます。

#### 2-1. フロー図のMermaidコードを作成する

ユーザーがウェブサイトにアクセスする際の認証フローを表すフロー図を作成します。

```mermaid
graph TD
    A[ユーザーアクセス] --> B{ログイン済み？};
    B -- はい --> C[ダッシュボード表示];
    B -- いいえ --> D[ログイン画面表示];
    D --> E{認証成功？};
    E -- はい --> C;
    E -- いいえ --> D;
    C --> F[ログアウト];

このコードでは、graph TDで上から下へのフロー図を宣言し、角括弧[]で処理、波括弧{}で条件分岐を定義しています。-->で処理の流れを示します。

2-2. Notionページに埋め込む

Notionページにこのフロー図を埋め込む方法はいくつかあります。

方法1: コードブロックとして貼り付ける

  1. Notionページを開きます。
  2. /codeと入力し、コードブロックを挿入します。
  3. コードブロックの言語を「Mermaid」に設定します。
  4. 上記で作成したMermaidコードを貼り付けます。

Notionは自動的にMermaidコードを解釈し、図として表示します。

方法2: Mermaidブロックを使用する（一部のワークスペースで利用可能）

NotionはMermaidブロックをネイティブでサポートしている場合があります。

  1. Notionページを開きます。
  2. /mermaidと入力し、Mermaidブロックを挿入します。
  3. Mermaidブロック内にコードを直接入力または貼り付けます。

どちらの方法でも、Notion上でフロー図がインタラクティブに表示され、ページの視覚的な理解度が向上します。

シナリオ3: CIでPNG出力する実践例

Mermaid CLI (mmdc) を使用すると、MermaidのテキストファイルからPNGやSVGなどの画像ファイルを自動生成できます。これをCI/CDパイプラインに組み込むことで、ドキュメントの図を常に最新の画像ファイルとして管理し、さまざまな場所で利用できます。

ここでは、GitHub Actionsを使って.mmdファイルからPNG画像を生成し、成果物としてアップロードするワークフローの例を示します。

3-1. Mermaidテキストファイルを準備する

例えば、システムの主要な処理を示すシーケンス図を作成し、main-sequence.mmdとして保存します。

sequenceDiagram
    participant User as ユーザー
    participant Frontend as フロントエンド
    participant Backend as バックエンド
    participant Database as データベース

    User->>Frontend: 商品検索リクエスト
    Frontend->>Backend: GET /products?q=keyword
    Backend->>Database: SELECT * FROM products WHERE name LIKE '%keyword%'
    Database-->>Backend: 検索結果データ
    Backend-->>Frontend: 検索結果JSON
    Frontend-->>User: 検索結果表示

3-2. GitHub Actionsのワークフローを設定する

.github/workflows/generate-diagrams.ymlというファイル名で、以下のGitHub Actionsワークフローを作成します。

name: Generate Mermaid Diagrams

on:
  push:
    branches:
      - main
    paths:
      - '**.mmd' # .mmdファイルが変更された場合にトリガー
  workflow_dispatch: # 手動実行も可能にする

jobs:
  generate_diagrams:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18' # Node.jsのバージョンを指定

      - name: Install Mermaid CLI
        run: npm install -g @mermaid-js/mermaid-cli

      - name: Generate PNG from main-sequence.mmd
        run: mmdc -i main-sequence.mmd -o diagrams/main-sequence.png -b transparent --width 1200 --height 800

      - name: Upload diagrams as artifact
        uses: actions/upload-artifact@v4
        with:
          name: mermaid-diagrams
          path: diagrams/

このワークフローは以下の処理を行います。

  • mainブランチへのプッシュで.mmdファイルが変更された場合、または手動で実行された場合にトリガーされます。
  • Node.jsとMermaid CLIをセットアップします。
  • mmdcコマンドを使ってmain-sequence.mmdからdiagrams/main-sequence.pngを生成します。
    • -i: 入力ファイル
    • -o: 出力ファイル
    • -b transparent: 背景を透過にします
    • --width, --height: 出力画像のサイズを指定します

  • 生成されたPNGファイルをGitHub Actionsの成果物としてアップロードします。

    • このワークフローが実行されると、GitHub Actionsの「Actions」タブから生成されたPNGファイルをダウンロードできるようになります。これにより、README以外のドキュメントやプレゼンテーション資料など、さまざまな用途で最新の図を利用できます。

    カスタマイズ例：テーマとスタイルの適用

    Mermaidは、図の外観をカスタマイズするためのオプションを豊富に提供しています。テーマの変更やCSSの適用により、プロジェクトのブランドガイドラインに合わせた図を作成できます。

    1. テーマの変更

    Mermaidにはいくつかの組み込みテーマがあります。default、forest、dark、neutral、baseなどです。Mermaid CLIを使用する場合、-tオプションでテーマを指定できます。

    例えば、main-sequence.mmdをダークテーマでPNG出力するには、以下のコマンドを実行します。

    # ダークテーマでPNGを出力
mmdc -i main-sequence.mmd -o diagrams/main-sequence-dark.png -t dark --width 1200 --height 800

    GitHubやNotionなどの統合環境では、環境設定に応じて自動的にテーマが適用されることもあります。例えば、GitHubのダークモード設定ではMermaid図もダークテーマで表示されます。

    2. カスタムCSSの適用

    より詳細なスタイル変更を行いたい場合は、カスタムCSSファイルを適用できます。Mermaid CLIでは--cssFileオプションを使用します。

    例えば、custom-styles.cssというファイルに以下のスタイルを定義します。

    /* custom-styles.css */
.node rect {
    fill: #e8f5e9 !important; /* ノードの背景色を変更 */
    stroke: #4caf50 !important; /* ノードの境界線色を変更 */
}
.node text {
    fill: #1b5e20 !important; /* ノードのテキスト色を変更 */
    font-weight: bold !important; /* テキストを太字にする */
}
.edgePath .path {
    stroke: #3f51b5 !important; /* エッジの線の色を変更 */
    stroke-width: 2px !important; /* エッジの線の太さを変更 */
}

    このCSSファイルを適用してPNGを出力します。

    # カスタムCSSを適用してPNGを出力
mmdc -i main-sequence.mmd -o diagrams/main-sequence-custom.png --cssFile custom-styles.css --width 1200 --height 800

    これにより、Mermaidが生成する図の要素に対して、細かくスタイルを調整できます。プロジェクトの標準デザインに合わせる際に非常に役立ちます。

    3. 設定ファイル（mermaid.json）の利用

    Mermaidのレンダリング設定は、mermaid.jsonというファイルにまとめて定義することも可能です。このファイルはMermaid CLIの実行時に自動的に読み込まれるか、明示的に指定できます。

    // mermaid.json
{
  "theme": "dark",
  "themeVariables": {
    "primaryColor": "#2196f3",
    "primaryTextColor": "#fff",
    "lineColor": "#64b5f6"
  },
  "flowchart": {
    "nodeSpacing": 100,
    "rankSpacing": 80
  },
  "er": {
    "diagramPadding": 20,
    "layoutDirection": "LR"
  },
  "sequence": {
    "boxMargin": 10,
    "messageFontWeight": "bold"
  }
}

    このmermaid.jsonファイルをプロジェクトのルートディレクトリに配置すると、mmdcコマンド実行時にこれらの設定が自動的に適用されます。mmdcコマンドで-cオプションを使って明示的に設定ファイルを指定することも可能です。

    # 設定ファイルを指定してPNGを出力
mmdc -i main-sequence.mmd -o diagrams/main-sequence-config.png -c mermaid.json

    設定ファイルを活用することで、チーム全体で図のスタイルを統一し、管理を容易にできます。

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

    Mermaidを使ったドキュメント管理の自動化は、以下の3ステップで今日から始められます。

    ステップ1: 必要なツールをインストールする

    まずは、Mermaidを利用するための環境を整えましょう。

    • Node.jsのインストール: 公式サイトからインストーラーをダウンロードするか、Homebrewなどのパッケージマネージャーを使用します。
    • Mermaid CLIのインストール: ターミナルで npm install -g @mermaid-js/mermaid-cli を実行します。
    • VS Code拡張機能のインストール: VS Codeの拡張機能マーケットプレイスで「Mermaid Preview」を検索し、インストールします。

    これらのツールを準備することで、Mermaidの記述とプレビュー、画像出力が可能になります。

    ステップ2: 最初の図を作成し、プレビューする

    簡単なMermaid図を作成し、その手軽さを体験してみましょう。

    1. プロジェクトのREADME.mdファイルを開くか、新しく.mmdファイルを作成します。
    2. 以下のいずれかのMermaidコードをファイルに貼り付けます。
      • フロー図の例:
        graph TD
    A[開始] --> B{条件？};
    B -- Yes --> C[処理A];
    B -- No --> D[処理B];
    C --> E[終了];
    D --> E;
      • シーケンス図の例:
        sequenceDiagram
    participant User
    participant System
    User->>System: リクエスト
    System-->>User: レスポンス
    3. VS Codeを使用している場合、Mermaidコードブロック内で Ctrl+Shift+V (または Cmd+Shift+V) を押すと、プレビューが表示されます。

    このステップで、Mermaidの基本的な記述方法と、リアルタイムプレビューの便利さを実感できます。

    ステップ3: CIでの自動生成を試す

    Mermaid図の管理を自動化するために、CI/CDパイプラインへの組み込みを試します。

    1. GitHub Actionsを使用している場合、.github/workflows/ ディレクトリ内に新しいYAMLファイルを作成します（例: generate-diagrams.yml）。
    2. この記事の「シナリオ3: CIでPNG出力する実践例」で紹介したGitHub Actionsのワークフローコードを貼り付け、ご自身のプロジェクトに合わせて.mmdファイルのパスなどを調整します。
    3. .mmdファイルとgenerate-diagrams.ymlをコミットし、GitHubリポジトリにプッシュします。

    ワークフローが自動的に実行され、Mermaid図がPNG画像として生成され、GitHub Actionsの成果物としてアップロードされることを確認してください。これにより、図の更新が自動化され、常に最新の図が手元にある状態を実現できます。

    これらのステップを踏むことで、Mermaidを使ったドキュメント管理の自動化をスムーズに導入できます。

    関連ページ

    参考文献

    広告

    -AI