Mermaid記法超入門―最強のダイアグラム・チャート作成ツール
GitHubやAI出力結果で目にする機会が多くなったMermaid記法について、「自分で書けるようになりたいな」など漠然と思いながらも「結局調べてもイマイチよくわからん・・・」な感じだったので、公式GitHubなどを頼りにまとめてみました。
初心者でも一から理解できるよう心がけていますので、最後まで読んでいただけると幸いです。
概要
Mermaidとは
Mermaid（マーメイド）は、JavaScriptベースの、ダイアグラムやチャートを作成するツールです。
「図表作成とドキュメント作成は開発者の貴重な時間を浪費してすぐに古くなるが、図表やドキュメントがないと生産性が損なわれ、組織学習に悪影響を及ぼす」という着眼から、「ユーザーが簡単に変更できる図表を作成できるようにし、ドキュメントを開発に追いつかせることで問題に対処する」ことを目的に作られました。
使い方
Mermaidはプログラマーでなくとも、Mermaid Live Editorを通じて簡単に詳細な図を作成できます。
もちろんGitHubやVS Codeでも記述できます。
Mermaid記法について
Mermaidの記法について、簡単に箇条書きでまとめました。
Mermaid記法の基本概念
- 定義: Mermaid記法は、情報を視覚的に整理するための記法の一つで、特にデータフローや関係性を明示するために使われます。
- 目的: プログラムやシステムの設計において、複雑なデータ構造やプロセスを理解しやすくすること。
Mermaid記法の要素
- ノード: データやプロセスの集まりを表します。四角形や円などで表現されることが多いです。
- エッジ: ノード間の関係やデータの流れを示します。矢印や線で表され、方向性を持つことが一般的です。
- 属性: ノードやエッジに付随する情報。ノードの特性やエッジの重みなどを示します。
※本記事ではエッジをリンク、属性をラベルと表現する箇所が多いです。
Mermaid記法の構成要素
- データノード: 具体的なデータを表すノード。例として、ユーザー情報や製品情報など。
- プロセスノード: データを処理するアクションを表すノード。例として、データの取得や集計処理など。
- ストレージノード: データが保存される場所を示すノード。データベースやファイルシステムなど。
Mermaid記法の使用方法
- システムのスコープを定義する: どの部分をMermaid記法で表現するかを決定します。
- ノードを特定する: 表現したいデータやプロセスを洗い出し、ノードとして整理します。
- エッジを設計する: ノード間の関係を定義し、どのようにデータが流れるのかを示します。
- 視覚化する: ノードとエッジを用いて図を作成し、全体の流れを視覚的に表現します。
Mermaid記法の応用例
- データベース設計: テーブル間の関係を視覚化し、正規化やリレーションを理解するためのツールとして活用。
- システムフローの設計: プログラムやシステムの処理フローを明確にし、問題点を洗い出すために利用。
- プロジェクト管理: タスク間の依存関係を示すことで、効率的なプロジェクト進行を助ける。
Mermaid記法のメリット
- 視覚的理解: 複雑な情報を整理し、視覚的に理解しやすくする。
- コミュニケーションツール: チーム内での情報共有や議論の際に、共通の理解を持つための手助けとなる。
- 問題発見の助け: データフローやプロセスの可視化により、潜在的な問題を早期に発見できる。
使用例
Mermaidでは、フローチャート、シーケンス図、ガントチャート、クラス図、状態遷移図、ER図、円グラフ、リストといった図を作成できます。
具体的な構文解説などは後回しにして、まずはそれぞれどう書いたらどういう結果になるのかをザックリと見ていきましょう。
フローチャート
フローチャートは最も基本的な図の一つです。
用途: プロセスや手順の流れを視覚化する。
コード例
graph LR
A[開始] --> B{条件1}
B -- Yes --> C[処理1]
B -- No --> D[処理2]
C --> E[終了]
D --> E結果
シーケンス図
シーケンス図は、オブジェクト間のメッセージのやり取りを表現するのに適しています。
用途: オブジェクト間の相互作用を時系列で示す。
コード例
sequenceDiagram
participant ブラウザ
participant サーバー
participant データベース
ブラウザ->>サーバー: HTTPリクエスト
サーバー->>データベース: クエリ実行
データベース-->>サーバー: 結果返却
サーバー-->>ブラウザ: HTTPレスポンス結果
ガントチャート
ガントチャートは、プロジェクト管理によく使用されます。
用途: プロジェクトの進行状況やタスクのスケジュールを可視化する。
コード例
gantt
title プロジェクトタイムライン
dateFormat YYYY-MM-DD
section 企画
要件定義 :a1, 2023-01-01, 30d
設計 :after a1, 20d
section 開発
実装 :2023-02-20, 40d
テスト :2023-04-01, 20d
section リリース
デプロイ :2023-04-21, 10d結果
クラス図
クラス図は、クラス間の関係を表現するのに使用されます。
用途: オブジェクト指向プログラミングにおけるクラスとその関係を表現する。
コード例
classDiagram
class Animal {
+name: string
+age: int
+makeSound() void
}
class Dog {
+breed: string
+bark() void
}
class Cat {
+color: string
+meow() void
}
Animal <|-- Dog
Animal <|-- Cat結果
状態遷移図
状態遷移図は、システムの状態とその遷移を表現するのに適しています。
用途: システムやオブジェクトの状態変化を示す。
コード例
stateDiagram-v2
[*] --> 待機中
待機中 --> 処理中: タスク開始
処理中 --> 完了: タスク終了
処理中 --> エラー: エラー発生
エラー --> 待機中: リセット
完了 --> [*]結果
エンティティ関係図（ER図）
ER図は、データベースの設計に使用されます。
用途: データベースのエンティティとその間の関係を視覚化する。
コード例
erDiagram
CUSTOMER {
string name
string email
}
ORDER {
int order_id
date order_date
}
CUSTOMER ||--o{ ORDER : places結果
円グラフ
円グラフは、データの割合を視覚的に表現するのに適しています。
用途: データの割合を視覚的に示す。
コード例
pie
title 好きな果物の割合
"りんご" : 40
"バナナ" : 30
"オレンジ" : 20
"ぶどう" : 10結果
カスタマージャーニーマップ
カスタマージャーニーマップは、顧客の行動や経験を可視化できます。
用途: 顧客の行動や経験を可視化する。
コード例
journey
title 商品購入のユーザージャーニー
section 商品検索
商品を探す: 5: ユーザー
商品詳細を確認: 3: ユーザー
section 購入
カートに追加: 4: ユーザー
チェックアウト: 5: ユーザー
section 配送
配送状況確認: 3: ユーザー
商品受け取り: 5: ユーザー結果
コーディング基礎
大前提
まずは「おまじない」とコメントアウトについて見ていきます。
Mermaidの初期設定
以下は、Mermaidの初期設定を行うためのコマンドです。
先ほどまでの事例で設定されていなかったように、設定しなくても良い項目です。
Mermaid Live Editorでは（私が試した環境では）ダークテーマがデフォルト採用されていました。
%%{init: { "theme": "default" }}%%%%: これで囲まれた部分は、Mermaidの特殊な構文であり、コードの実行時に特定の設定を適用します。init: 初期設定を行うためのキーワードです。theme: テーマ設定を行うためのオプションです。ここでは「default」（デフォルトテーマ）が指定されています。他にも「forest」「dark」などのテーマがあります。
選択可能なテーマは以下の5通りです。
- default: デフォルト
- neutral: 白黒印刷に最適
- dark: 暗い色合いやダークモードに最適
- forest: 緑を貴重にしている
- base: カスタマイズ可能な唯一のテーマ
それぞれ以下のようなイメージです。
コメントアウト
Pythonで#によってコメントアウトできるように、Mermaidでは%%を使ってコメントアウトします。
%% これは1行コメントです%%: Mermaidでは、%%を使ってコメントを記述できます。コメントは、図には表示されず、コードの説明やメモとして使われます。
また、あまり見かけることはありません（そもそも非推奨らしいです）が、複数行にまたがってコメントすることも可能なようです。
%%{
複数行に渡る
コメントも可能
}%%%%{ }%%:%%{と}%%で囲むことで複数行コメントを記述することもできます。
基本構文
Mermaidで最初に覚えるべきは以下の構文です。
graph TD
A[スタート] --> B[次のステップ]graph TD: 図の種類を指定します。ここでは「上から下」（Top-Down）に図を描くことを指定しています。A[スタート]: 四角形のノードを定義し、ラベルを「スタート」としています。-->: ノード間の接続を表します。
改行に意味はありますが、インデント（字下げ）に意味はありません。
改行により、ノードやエッジを確定するようなイメージです。
graph TDの部分を書き換えることで、様々な図式を表現できます。
先ほども見たように、sequenceDiagramならシーケンス図、ganttならガントチャートになります。
2行目以下の書き方は、図式ごとに変わりますが、今回はフローチャートを基本に見ていきます。
コーディング実践
フローチャートは、ノード（幾何学的図形）とエッジ（矢印または線）で構成されます。
Mermaidコードは、ノードとエッジの作成方法を定義し、さまざまな矢印タイプ、多方向矢印、サブグラフとの間のリンクに対応します。
ノード
基本形
Nodeというタイトルで、LR（Left to Right、右から左）のフローチャートについて、idというノードが表示されます。
---
title: Node
---
graph LR
id
（注）graphに代えてflowchartも可です。
テキストを含むノード
ノードにはラベルをつけることが可能です。
この場合、"id1″がノードIDとなり、ラベルの"This is the text in the box"が表示されます。
また、定義したラベルは再利用されます。
同一IDに対して複数回ラベリングを行った場合、最後にラベリングしたテキストが使用されます。
---
title: Node with text
---
graph LR
id1[This is the text in the box]
Unicodeを含むノード
絵文字などのUnicodeテキストを囲むにはダブルクオーテーションを使用します。
graph LR
id["This ❤ Unicode"]
マークダウンフォーマット
マークダウンテキストを囲むには、二重引用符とバッククォート (“` text `") を使用します。
%%{init: {"graph": {"htmlLabels": false}} }%%
graph LR
markdown["`This **is** _Markdown_`"]
newLines["`Line1
Line 2
Line 3`"]
markdown --> newLines
方向の宣言
既にgraph TDやgraph LRを紹介していますが、TDやLR以外に以下の宣言が可能です。
- TB – 上から下（Top to bottom）
- TD – 上から下（Top-down）※TBと同じ
- BT – 下から上（Bottom to top）
- RL – 右から左（Right to left）
- LR – 左から右（Left to right）
ノードの形状
ノードの形状は四角形以外にも定義可能です。
以下によく使われるものを列挙します。
丸いエッジを持つノード（処理記号）
graph LR
id1(This is the text in the box)
スタジアム型ノード（開始/終了記号）
graph LR
id1([This is the text in the box])
サブルーチンシェイプ内のノード（定義済み処理記号）
graph LR
id1[[This is the text in the box]]
円筒形のノード（システム/データベース記号）
graph LR
id1[(Database)]
円状のノード
graph LR
id1((This is the text in the circle))
非対称形状のノード
graph LR
id1>This is the text in the box]
菱形のノード（判断記号）
graph LR
id1{This is the text in the box}
六角形のノード（準備記号）
graph LR
id1{{This is the text in the box}}
平行四辺形（データ/入出力記号）
graph TD
id1[/This is the text in the box/]
その他
これらの他にも様々なノードが用意されており、最新バージョンではExcelなどで見かけるような図形も網羅されています。
多すぎるので割愛しますが、余力があればぜひ調べてみてください。
エッジ
使用可能なリンク一覧
エッジ（リンク）は矢印や線など、ノードを接続するものです。
以下、代表的なものを見ていきます。
graph LR
%% 矢印の付いたリンク
A --> B
%% オープンリンク
C --- D
%% リンク上のテキスト
E-- This is the text! ---F
%% 矢印とテキストの付いたリンク
G-- text -->H
%% 点線リンク
I-.->J
%% テキスト付きの点線リンク
K-. text .-> L
%% 太いリンク
M ==> N
%% テキスト付きの太いリンク
O == text ==> P
%% 目に見えないつながり
Q ~~~ R
ちなみに、ラベリングは以下の書き方でも可能です。
個人的にはこちらの方が書く際には分かりやすいと思います。（コードリーディングの際は先ほどの方が分かりやすいかなと。）
graph LR
E---|This is the text|F
G-->|text|H
K-.->|text|L
O ==>|text| Pリンクの連鎖
以下のように、同じ行に複数のリンクを宣言することも可能です。
graph LR
A -- text --> B -- text2 --> C
また、以下のように同じ行に複数のノードリンクを宣言することもできます。
graph LR
a --> b & c--> d
これを応用すると、以下のような宣言もできます。
graph TB
A & B--> C & D
ちなみに、以下のコードでも同様の結果を得られます。
graph TB
A --> C
A --> D
B --> C
B --> Dリンクの長さ
リンクの長さは、単純にリンクのコードを長くすれば長くなります。
graph LR
A --- B
C ---- D
E ----- G
一覧化すると以下のようになります。
| 長さ | 1 | 2 | 3 |
|---|---|---|---|
| 線 | --- | ---- | ----- |
| 矢印 | --> | ---> | ----> |
| 太い線 | === | ==== | ===== |
| 太い矢印 | ==> | ===> | ====> |
| 点線 | -.- | -..- | -...- |
| 点線矢印 | -.-> | -..-> | -...-> |
サブグラフ
Mermaidではサブグラフが使えます。
見た方が早いので、とりあえず見てみましょう。
graph TD
subgraph サブグラフ1
A[開始] --> B{条件}
B -->|Yes| C[処理1]
B -->|No| D[処理2]
end
subgraph サブグラフ2
E[開始] --> F[処理3]
F --> G[処理4]
end
C --> E
D --> E
フローチャートがきれいに入れ子になっていることが分かります。
サブグラフの構造は、このようになっています。
subgraph タイトル
グラフの定義
endまた、フローチャートでは、以下の例のようにdirectionステートメントを使用してサブグラフがレンダリングされる方向を設定できます。
flowchart LR
subgraph TOP
direction TB
subgraph B1
direction RL
i1 -->f1
end
subgraph B2
direction BT
i2 -->f2
end
end
A --> TOP --> B
B1 --> B2
フォントアイコン
Mermaidでは、Font Awesome等のアイコンを図に追加できます。
これ、とても有用なので是非覚えてください。
fa:fa-アイコン名の形式でアイコンを指定
graph LR
A[開始] --> B(fa:fa-spinner 処理中)
B --> C{fa:fa-question 条件}
C -->|はい| D[fa:fa-check 完了]
C -->|いいえ| E[fa:fa-times エラー]
インタラクション
一部の環境ではサポートされていない場合もありますが、Mermaidではクリック可能な要素を追加できます。
graph LR
A[開始] --> B(処理)
B --> C{条件}
C -->|はい| D[完了]
C -->|いいえ| E[エラー]
click B href "https://example.com/process1" "処理1の詳細"
click D callback "完了をクリックしました"
click E callback "エラーをクリックしました"インタラクティブ要素の追加：
clickキーワードを使用href属性でリンクを指定callbackでJavaScript関数を呼び出し
応用例
今回は紹介しきれませんでしたが、こんなこともできますという例をいくつか示して終わろうと思います。
状態図
stateDiagram-v2
[*] --> 待機中
待機中 --> 処理中 : タスク開始
処理中 --> 完了 : タスク終了
処理中 --> エラー : エラー発生
state 処理中 {
[*] --> 初期化
初期化 --> 実行中
実行中 --> 後処理
後処理 --> [*]
}
エラー --> 待機中 : リセット
完了 --> [*]
note right of エラー : エラーログを記録
待機中 : タスクキューを監視
完了 : 結果を保存
タイムライン
timeline
title プロジェクトタイムライン
section 計画フェーズ
要件定義 : 2023-01-01 : 2023-01-31
設計 : 2023-02-01 : 2023-02-28
section 開発フェーズ
実装 : 2023-03-01 : 2023-04-30
テスト : 2023-05-01 : 2023-05-31
section リリースフェーズ
ベータ版リリース : 2023-06-01 : 2023-06-15
本番リリース : 2023-06-16 : 2023-06-30
スタイル設定
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000', 'edgeLabelBackground':'#ffffee', 'tertiaryColor': '#fff0f0'}}}%%
graph LR
A[開始] -->|処理| B(実行中)
B --> C{条件?}
C -->|はい| D[完了]
C -->|いいえ| E[エラー]
classDef default fill:#f9f,stroke:#333,stroke-width:2px;
classDef special fill:#bbf,stroke:#f66,stroke-width:2px,stroke-dasharray: 5, 5;
class A,D default;
class C special;
style E fill:#f99,stroke:#333,stroke-width:4px
まとめ
少々長くなってしまいましたが、Mermaidは近年かなり目にする機会が増えており、今後もますます発展していくと思われます。
生成AIの発達により、「こういったものはAIに書かせればいいじゃないか」という意見も多いとは思います（実際その通りです）が、自分で書いてみないと分からない世界というのもあるはずです。
「書けないからAIに書かせる」ではなく「書けるけどAIに書かせる」の方が、問題点にいち早く気づけるなど圧倒的に価値が高いので、どういった構造なのかくらいは抑えておいても良いと思います。
以上です。
需要があればもっとちゃんとまとめます。