T-CREATOR

エンジニア必見！Mermaid × Markdownでテキストベース図表作成を始めよう

エンジニア必見！Mermaid × Markdownでテキストベース図表作成を始めよう

現代の情報社会では、複雑な概念やプロセスを視覚的に伝える能力がますます重要になっています。しかし、従来のダイアグラム作成ツールは習得に時間がかかり、ファイル管理も煩雑でした。そんな課題を解決する革新的なソリューションが Mermaid です。

Mermaid は、シンプルなテキスト記法で美しいダイアグラムを作成できる JavaScript ライブラリです。フローチャート、シーケンス図、ガントチャート、クラス図など、様々な種類の図表を Markdown ファイル内に直接記述できるため、エンジニアからビジネスパーソンまで幅広い方々の業務効率化に貢献しています。

本記事では、Mermaid の基本的な使い方から、最も重要なフローチャートの作成方法まで、実践的なサンプルコードと共に詳しく解説いたします。読み終える頃には、あなたもテキストベースで美しく機能的なダイアグラムを作成できるようになることでしょう。

Mermaid とは：テキストベースでダイアグラムを描く革新的ツール

Mermaid の特徴と革新性

Mermaid は 2014 年に Knut Sveidqvist によって開発されたオープンソースのダイアグラム生成ツールです。最大の特徴は、テキストベースの記法でダイアグラムを作成できることです。

従来のツールとの比較：

項目従来のツールMermaid
学習コスト高（UI 操作を覚える必要）低（シンプルな記法）
ファイル管理複雑（専用ファイル形式）簡単（テキストファイル）
バージョン管理困難容易（Git で管理可能）
チーム共有有料プランが必要な場合が多い無料（オープンソース）
保守性低（ツール依存）高（テキストベース）

なぜ Mermaid を選ぶべきか

1. 高い生産性 コードを書くようにダイアグラムを作成できるため、一度慣れてしまえば圧倒的に速く図表を作成できます。

2. 優れた保守性 テキストファイルなので、差分管理やバージョン管理が容易です。GitHub や GitLab での変更履歴も一目瞭然です。

3. 豊富な対応プラットフォーム GitHub、GitLab、Notion、Obsidian、VS Code など、多くのプラットフォームでネイティブサポートされています。

4. 拡張性とカスタマイズ性 CSS スタイルや JavaScript を用いた高度なカスタマイズが可能です。

Markdown との組み合わせがもたらす文書作成の効率化

ドキュメント作成革命

Markdown と Mermaid の組み合わせは、技術文書作成に革命をもたらしました。以下のような統合的な文書作成が可能になります：

mermaidflowchart TD
    A[ユーザーリクエスト] --> B{認証確認}
    B -->|認証OK| C[データ処理]
    B -->|認証NG| D[エラー応答]
    C --> E[レスポンス生成]
    E --> F[ユーザーに応答]
    D --> F

Mermaid の基本セットアップ

主要エディタ・プラットフォームでの有効化方法

Mermaid を利用するための環境設定は、使用するプラットフォームによって異なります。以下、主要な環境での設定方法をご紹介します。

GitHub / GitLab での利用

GitHub GitHub では 2022 年 2 月から Mermaid が標準サポートされています。特別な設定は不要で、以下のように記述するだけで自動的にダイアグラムが表示されます：

mermaidgraph TD
    A[開始] --> B[処理]
    B --> C[終了]

GitLab GitLab でも同様に、Mermaid ブロックが自動認識されます。GitLab CI でのドキュメント生成時にも対応しています。

VS Code での設定

1. 拡張機能のインストール

推奨拡張機能：

  • Markdown Preview Mermaid Support by Matt Bierner
  • Mermaid Editor by tomoyukim
bash# コマンドパレットから
Ctrl+Shift+P (Cmd+Shift+P) > "Extensions: Install Extensions"
# "Mermaid" で検索してインストール

2. settings.json の設定

json{
  "markdown.mermaid.enabledLanguageIds": [
    "markdown",
    "mermaid"
  ],
  "mermaidEditor.generate.theme": "default",
  "mermaidEditor.generate.backgroundColor": "white"
}

3. プレビューでの確認

mermaidsequenceDiagram
    participant A as アリス
    participant B as ボブ

    A->>B: こんにちは
    B-->>A: こんにちは！

    Note over A,B: 会話の開始

    A->>B: 元気ですか？
    B-->>A: とても元気です

Obsidian での設定

Obsidian では、コアプラグインとして Mermaid がサポートされています。

1. プラグインの有効化

設定 > コアプラグイン > Mermaid を有効化

2. 記法例

mermaidgraph TB
    subgraph "フロントエンド"
        A[React App]
        B[State Management]
    end

    subgraph "バックエンド"
        C[Node.js API]
        D[PostgreSQL]
    end

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

3. カスタム CSS（オプション）

css/* .obsidian/snippets/mermaid-custom.css */
.mermaid {
  background-color: var(--background-primary);
  border-radius: 8px;
  padding: 16px;
}

.mermaid .node rect {
  fill: var(--interactive-accent);
  stroke: var(--interactive-accent);
}

GitHubPages、Notion、VS Code、Obsidian での設定

Notion での利用

Notion では 2021 年から Mermaid ダイアグラムがサポートされています。

1. コードブロックの作成

bash/code > 言語に "Mermaid" を選択

2. 基本的な使用例

mermaidpie title プロジェクト進捗
    "完了" : 70
    "進行中" : 20
    "未着手" : 10

3. Notion での制限事項

  • 一部の新しいダイアグラムタイプは未対応
  • カスタムスタイルには制限あり
  • 印刷時のレイアウトに注意が必要

Jekyll (GitHub Pages) での設定

GitHub Pages で静的サイトを構築する際の Mermaid 設定方法：

1. _config.yml の設定

yaml# _config.yml
markdown: kramdown
kramdown:
  syntax_highlighter: rouge

plugins:
  - jekyll-mermaid

2. Gemfile の更新

ruby# Gemfile
gem 'jekyll-mermaid'

3. レイアウトファイルの更新

html<!-- _layouts/default.html -->
<!DOCTYPE html>
<html>
  <head>
    <!-- 他のhead要素 -->
    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
    <script>
      mermaid.initialize({ startOnLoad: true });
    </script>
  </head>
  <body>
    {{ content }}
  </body>
</html>

4. 記事での使用

markdown---
layout: default
---

# 記事タイトル

<div class="mermaid">
graph TD
    A[記事作成] --> B[Git Push]
    B --> C[GitHub Actions]
    C --> D[サイト更新]
</div>

オンラインエディタとローカル環境の使い分け

オンラインエディタの活用

Mermaid Live Editor

  • URL: https://mermaid.live/
  • 特徴：公式のオンラインエディタ
  • 用途：クイックプロトタイピング、学習
mermaidsequenceDiagram
    participant A as アリス
    participant B as ボブ

    A->>B: こんにちは
    B-->>A: こんにちは！

    Note over A,B: 会話の開始

    A->>B: 元気ですか？
    B-->>A: とても元気です

その他のオンラインツール

  • Diagrams.net (旧 Draw.io) - Mermaid インポート機能
  • CodePen - HTML プレビューでの確認
  • JSFiddle - JavaScript と組み合わせたテスト

ローカル環境での開発

Node.js プロジェクトでの統合

bash# Mermaidのインストール
yarn add mermaid

# 開発用ツールのインストール
yarn add --dev @mermaid-js/mermaid-cli

javascript// mermaid-config.js
import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: true,
  theme: 'dark',
  themeVariables: {
    primaryColor: '#ff6b6b',
    primaryTextColor: '#fff',
    primaryBorderColor: '#ff4757',
    lineColor: '#7bed9f',
    secondaryColor: '#70a1ff',
    tertiaryColor: '#5352ed',
  },
});

CLI ツールでの画像生成

bash# SVG形式で出力
yarn mmdc -i input.mmd -o output.svg

# PNG形式で出力
yarn mmdc -i input.mmd -o output.png

# 複数ファイルの一括変換
yarn mmdc -i 'diagrams/*.mmd' -o 'images/'

Docker 環境での活用

dockerfile# Dockerfile
FROM node:18-alpine

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

WORKDIR /workspace

COPY package*.json ./
RUN npm install

COPY . .

CMD ["npm", "start"]

yaml# docker-compose.yml
version: '3.8'
services:
  mermaid-generator:
    build: .
    volumes:
      - ./src:/workspace/src
      - ./output:/workspace/output
    command: mmdc -i src/ -o output/

フローチャート（Flowchart）完全マスター

フローチャートは、プロセスや意思決定の流れを視覚的に表現する最も基本的で重要なダイアグラムです。Mermaid では、直感的な記法で複雑なフローチャートを作成できます。

基本的なノードとエッジの記法

ノード（節点）の種類

Mermaid では、様々な形状のノードを使用できます：

mermaidflowchart TD
    A[長方形ノード]
    B(丸角長方形ノード)
    C([スタジアム型ノード])
    D[[サブルーチンノード]]
    E[(データベースノード)]
    F((円形ノード))
    G{ダイヤモンドノード}
    H{{六角形ノード}}
    I[/平行四辺形ノード/]
    J[\逆平行四辺形ノード\]
    K[/台形ノード\]
    L[\逆台形ノード/]

エッジ（矢印）の種類

mermaidflowchart TD
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I --o J
    K --x L
    M o--o N
    O <--> P
    Q -.・R
    S == T

矢印の意味：

記法意味用途
-->実線矢印通常のフロー
---実線（矢印なし）関連を示す
-.->点線矢印条件付きフロー
==>太い矢印重要なフロー
--o円付き矢印集約
--xX 付き矢印例外・エラー

分岐・判定・ループの表現方法

基本的な分岐構造

mermaidflowchart TD
    A[開始] --> B{条件判定}
    B -->|Yes| C[処理A実行]
    B -->|No| D[処理B実行]
    C --> E[終了]
    D --> E

複数分岐の表現

mermaidflowchart TD
    A[ユーザー入力] --> B{入力値チェック}
    B -->|有効| C[データ保存]
    B -->|無効| D[エラー表示]
    B -->|空| E[デフォルト値設定]
    C --> F[成功メッセージ]
    D --> G[再入力要求]
    E --> C
    F --> H[終了]
    G --> A

ループ構造の表現

mermaidflowchart TD
    A[開始] --> B[カウンター初期化]
    B --> C{条件確認}
    C -->|継続| D[処理実行]
    D --> E[カウンター更新]
    E --> C
    C -->|終了| F[結果出力]
    F --> G[終了]

複雑なビジネスプロセスの図解例

注文処理システムのフローチャート

mermaidflowchart TD
    A[注文受付] --> B{在庫確認}
    B -->|在庫あり| C[在庫引当]
    B -->|在庫なし| D[バックオーダー]
    C --> E{支払確認}
    E -->|支払済み| F[出荷準備]
    E -->|未払い| G[請求書発行]
    G --> H{支払期限}
    H -->|期限内| I[支払確認]
    H -->|期限切れ| J[催促通知]
    I --> F
    J --> K{再催促}
    K -->|継続| L[再催促送信]
    K -->|キャンセル| M[注文キャンセル]
    L --> H
    F --> N[配送手配]
    N --> O[配送完了]
    D --> P[入荷待ち]
    P --> Q{入荷確認}
    Q -->|入荷| C
    Q -->|未入荷| R[入荷予定通知]
    R --> P
    O --> S[注文完了]
    M --> T[キャンセル処理完了]

ソフトウェア開発のレビュープロセス

mermaidflowchart TD
    A[コード作成] --> B[セルフレビュー]
    B --> C{基本チェック}
    C -->|NG| D[修正作業]
    D --> B
    C -->|OK| E[プルリクエスト作成]
    E --> F[レビュー依頼]
    F --> G[チームレビュー]
    G --> H{レビュー結果}
    H -->|承認| I[マージ]
    H -->|要修正| J[修正指示]
    H -->|追加調査| K[調査・議論]
    J --> L[修正実施]
    L --> M[修正完了報告]
    M --> G
    K --> N[調査結果報告]
    N --> O{継続判定}
    O -->|継続| P[追加開発]
    O -->|中止| Q[開発中止]
    P --> A
    I --> R[CI/CD実行]
    R --> S{テスト結果}
    S -->|成功| T[本番デプロイ]
    S -->|失敗| U[ロールバック]
    U --> V[原因調査]
    V --> W[緊急修正]
    W --> R
    T --> X[デプロイ完了]

スタイリングとテーマの適用

基本的なスタイリング

mermaidflowchart TD
    A[開始] --> B[処理]
    B --> C[終了]

    classDef startEnd fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef process fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

    class A,C startEnd
    class B process

カスタムテーマの適用

mermaid%%{init: {"theme": "dark", "themeVariables": {"primaryColor": "#ff6b6b", "primaryTextColor": "#ffffff", "primaryBorderColor": "#ff4757", "lineColor": "#7bed9f", "secondaryColor": "#70a1ff", "tertiaryColor": "#5352ed"}}}%%
flowchart TD
    A[Dark Theme] --> B[Custom Colors]
    B --> C[Professional Look]
    C --> D[Enhanced Readability]

まとめ

この記事では、Mermaid の基本的な概念から環境セットアップ、そして最も重要なフローチャートの作成方法まで詳しく解説いたしました。

Mermaid の 3 つの革新性

  1. テキストベースによる効率性 - シンプルな記法で複雑なダイアグラムを高速作成
  2. 優れた保守性 - バージョン管理との完全統合とツール非依存性
  3. 豊富な対応環境 - GitHub、VS Code、Obsidian、Notion など主要プラットフォームでのネイティブサポート

実践で習得した主要スキル

  • Markdown との統合による文書作成の効率化
  • 各種エディタでの環境セットアップ
  • フローチャートによる業務プロセスとシステムフローの可視化
  • ノード、エッジ、分岐構造を活用した複雑な処理の表現
  • CSS スタイリングによる美しく機能的なダイアグラム作成

Mermaid を活用することで、従来の図表作成ツールでは難しかった 高速で保守性の高いダイアグラム作成 が可能になります。特にフローチャートは、ビジネスプロセスやシステムの処理フローを可視化する上で欠かせないツールです。

関連リンク

ブログBlog

もっと見る

書籍レビューReview

もっと見る