はじめに
設計書、README、Qiita記事、研究メモを書いていると、
- 処理の流れを簡単な図で説明したい
- 図を直すたびに PowerPoint や draw.io を開くのが面倒
- コードや文章と一緒に、図も Git で管理したい
- 学生や共同研究者に、解析手順を一枚の図で説明したい
と思うことがあります。
そのようなときに便利なのが Mermaid です。
Mermaid は、Markdown の中に直接書ける テキストベースの図表記述言語です。たとえば、次のように書くだけで、フローチャートを表示できます。
```mermaid
flowchart TD
A[入力] --> B[処理]
B --> C[出力]
```
表示結果は次のようになります。
つまり Mermaid を使うと、図を画像ファイルとして別に作るのではなく、文章やコードと同じようにテキストとして管理できます。
この記事では、Mermaid を初めて使う人に向けて、
- Mermaid とは何か
- 最低限覚えれば使える基本文法
- よく使う図の種類
- Qiita や GitHub README で使いやすい実例
- つまずきやすいポイント
を、コピペしながら試せる形で整理します。
Mermaid とは？
Mermaid は、簡単に言えば、
テキストから図を生成するための言語
です。
もう少し専門的に言うと、Mermaid は DSL（Domain Specific Language：ドメイン固有言語） の一種です。つまり、Python や JavaScript のような汎用プログラミング言語ではなく、図を書くことに特化した小さな言語です。
Mermaid の大きな特徴は次の3つです。
| 特徴 | 内容 |
|---|---|
| Markdown に直接書ける | README、Qiita、設計メモと相性がよい |
| テキストなので Git 管理しやすい | 差分が追いやすく、レビューしやすい |
| 図の修正が簡単 | 画像を作り直さず、テキストを直せばよい |
たとえば、PowerPoint や draw.io で作った図は、見た目の調整には強いですが、変更履歴を細かく追うのはやや苦手です。一方 Mermaid は、見た目の自由度は限定されますが、構造をテキストで表せるため、設計書や README と一緒に育てていくことができます。
Mermaid は、特に次のような用途に向いています。
- README に簡単な処理フローを入れる
- Qiita記事でアルゴリズムの流れを説明する
- 設計メモにコンポーネント間の関係を書く
- 状態遷移や条件分岐を整理する
- 研究や解析の手順を共有する
一方で、ピクセル単位で美しく配置したい図や、発表スライド用に見栄えを細かく整えたい図には、PowerPoint、Illustrator、draw.io などの方が向いています。
Mermaid は、あくまで 「構造を素早く共有するための図」 に強いツールです。
Mermaid の基本の書き方
Mermaid は、Markdown のコードブロックとして書きます。
```mermaid
ここに Mermaid のコードを書く
```
たとえば、フローチャートなら次のように書きます。
```mermaid
flowchart TD
A[開始] --> B[処理]
B --> C[終了]
```
ここで重要なのは、最初の行です。
flowchart TD
これは、
-
flowchart：フローチャートを書く -
TD：上から下へ流す
という意味です。
TD は Top Down の略です。つまり、図が上から下へ流れます。
1. フローチャート
Mermaid で最もよく使うのは、おそらくフローチャートです。
処理の流れ、判断、分岐、入力と出力の関係を表すのに向いています。
最小例
```mermaid
flowchart TD
A[開始] --> B[処理]
B --> C[終了]
```
この例では、
A[開始]
が「開始」という箱を表します。
A --> B
は、A から B へ矢印を引く、という意味です。
つまり、Mermaid のフローチャートでは、
ノード --> ノード
という形を基本にして、処理の流れを書いていきます。
図の向きを変える
フローチャートでは、図の向きを指定できます。
| 指定 | 意味 | 用途 |
|---|---|---|
TD |
上から下 | 処理の流れ、手順 |
LR |
左から右 | 入力から出力、データ処理 |
RL |
右から左 | 特殊な依存関係 |
BT |
下から上 | 階層構造を逆向きに見せたいとき |
たとえば、左から右に流したい場合は LR を使います。
```mermaid
flowchart LR
A[入力] --> B[計算]
B --> C[出力]
```
README や設計書では、短い処理フローなら LR、少し長い手順なら TD が見やすいことが多いです。
2. ノードの形
Mermaid では、ノードを囲む記号によって形が変わります。
```mermaid
flowchart TD
A[四角]
B(丸みのある四角)
C{条件分岐}
D[[サブルーチン]]
```
よく使うものは次の通りです。
| 記法 | 形 | 使いどころ |
|---|---|---|
A[処理] |
四角 | 通常の処理 |
A(開始) |
丸みのある四角 | 開始・終了 |
A{条件} |
ひし形 | Yes/No の分岐 |
A[[関数]] |
二重四角 | サブルーチン、関数、別処理 |
最初は、次の3つだけ覚えれば十分です。
A[処理]
A{条件}
A --> B
この3つだけでも、多くのフローチャートは書けます。
3. 条件分岐を書く
条件分岐を書くときは、ひし形のノード { } を使います。
```mermaid
flowchart TD
A[入力データを読む] --> B{データは正常？}
B -- Yes --> C[解析を実行]
B -- No --> D[エラーを表示]
```
矢印にラベルを付けるには、
B -- Yes --> C
のように書きます。
日本語でも書けます。
```mermaid
flowchart TD
A[ファイルを読み込む] --> B{ファイルは存在する？}
B -- はい --> C[処理を続ける]
B -- いいえ --> D[終了する]
```
ただし、Qiita や GitHub で安定して表示したい場合は、記号類はできるだけ半角で書くのがおすすめです。
4. 実用的なフローチャート例
ここでは、README や Qiita 記事でそのまま使いやすい例を示します。
Python スクリプトの処理フロー
```mermaid
flowchart TD
A[コマンドライン引数を読む] --> B[入力ファイルを確認]
B --> C{ファイルは存在する？}
C -- Yes --> D[データを読み込む]
C -- No --> E[エラーを表示して終了]
D --> F[解析を実行]
F --> G[結果を保存]
```
このような図を README に入れておくと、コードを読む前に全体像を理解しやすくなります。
Web アプリの基本構造
```mermaid
flowchart LR
User[ユーザー] --> Frontend[フロントエンド]
Frontend --> API[APIサーバー]
API --> DB[(データベース)]
API --> Storage[(ファイルストレージ)]
```
データベースのようなものは、円柱型のノードで表すと直感的です。
DB[(データベース)]
5. subgraph で処理をグループ化する
少し複雑な図では、subgraph を使うと処理をまとまりごとに整理できます。
```mermaid
flowchart TD
subgraph Input[入力]
A[設定ファイル]
B[観測データ]
end
subgraph Process[処理]
C[前処理]
D[解析]
end
subgraph Output[出力]
E[図]
F[レポート]
end
A --> C
B --> C
C --> D
D --> E
D --> F
```
subgraph は、次のような場面で便利です。
- 入力、処理、出力を分けたい
- フロントエンド、バックエンド、データベースを分けたい
- 前処理、解析、可視化を分けたい
- モジュールごとの責務を分けたい
図が複雑になってきたら、ノードを増やす前に、まず subgraph でまとまりを作ると読みやすくなります。
6. シーケンス図
フローチャートは「処理の流れ」を表すのに向いています。
一方で、誰が誰に何を送るのかを表したいときは、シーケンス図が便利です。
たとえば、ユーザーがシステムにリクエストを送り、システムがレスポンスを返す流れは次のように書けます。
```mermaid
sequenceDiagram
participant User
participant System
User->>System: リクエスト
System-->>User: レスポンス
```
矢印の意味
| 記法 | 意味 |
|---|---|
->> |
呼び出し、リクエスト |
-->> |
応答、レスポンス |
-> |
通常のメッセージ |
-- |
点線のメッセージ |
API 処理の例
```mermaid
sequenceDiagram
participant User
participant Browser
participant API
participant DB
User->>Browser: ボタンを押す
Browser->>API: データ取得リクエスト
API->>DB: クエリ実行
DB-->>API: 結果を返す
API-->>Browser: JSONを返す
Browser-->>User: 結果を表示
```
シーケンス図は、次のような説明に向いています。
- API の処理順序
- 関数やクラスの呼び出し関係
- ユーザー操作から画面表示までの流れ
- 外部サービスとの通信
- 認証処理
フローチャートでは「処理の順番」は分かりますが、「誰が誰に依頼しているのか」は見えにくいことがあります。そのような場合は、シーケンス図を使うと理解しやすくなります。
7. クラス図
クラス図は、オブジェクト指向プログラミングにおけるクラス構造を整理するための図です。
簡単な例を示します。
```mermaid
classDiagram
class Detector {
+float energy
+read()
}
class TES {
+float temperature
+measure()
}
Detector <|-- TES
```
この例では、TES が Detector を継承していることを表しています。
クラス図は、次のような場合に便利です。
- クラス設計を簡単に共有したい
- 属性とメソッドを整理したい
- 継承関係を説明したい
- コードを書く前に大まかな構造を考えたい
ただし、巨大なクラス設計を Mermaid だけで厳密に管理しようとすると、かえって読みづらくなることがあります。Mermaid のクラス図は、詳細な UML 図というより、設計のたたき台として使うのがよいと思います。
8. 状態遷移図
状態遷移図は、システムや処理がどのような状態を移り変わるかを表す図です。
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Finished
Finished --> [*]
```
[*] は開始点や終了点を表します。
状態遷移図の実例
たとえば、ファイル処理プログラムの状態は次のように表せます。
```mermaid
stateDiagram-v2
[*] --> Waiting
Waiting --> Loading: ファイル指定
Loading --> Processing: 読み込み成功
Loading --> Error: 読み込み失敗
Processing --> Saving: 処理完了
Saving --> Finished: 保存完了
Error --> [*]
Finished --> [*]
```
状態遷移図は、次のような場面で便利です。
- 組み込みソフトウェア
- UI の状態管理
- データ処理パイプライン
- エラー処理
- イベント駆動のプログラム
- 実験装置や観測装置の動作モード
「今どの状態にいて、どの条件で次の状態へ行くのか」を整理できるので、バグの発見にも役立ちます。
9. ガントチャート
Mermaid では、簡単なガントチャートも書けます。
```mermaid
gantt
title 開発スケジュール
dateFormat YYYY-MM-DD
section 設計
要件整理 :a1, 2026-01-01, 5d
基本設計 :a2, after a1, 7d
section 実装
実装 :b1, after a2, 10d
テスト :b2, after b1, 5d
```
簡易的なスケジュール共有には便利です。ただし、細かいプロジェクト管理を本格的に行う場合は、専用ツールを使った方がよいです。
10. Mermaid が向いている場面・向いていない場面
Mermaid は便利ですが、万能ではありません。
Mermaid が向いている場面
Mermaid が得意なのは、次のような図です。
- README に入れる簡単な構成図
- Qiita 記事の説明図
- 処理フロー
- API の呼び出し順序
- 状態遷移
- 解析パイプライン
- 設計のたたき台
- 議論用のラフな図
Mermaid の強みは、図をきれいに描くことよりも、構造を素早く共有することにあります。
Mermaid が向いていない場面
一方で、次のような用途にはあまり向いていません。
- 論文や発表スライド用の美しい模式図
- ピクセル単位で配置を調整したい図
- 複雑すぎる UML 図
- 厳密な製品仕様書としての図面
- デザイン性を重視する図
そのような場合は、draw.io、Figma、PowerPoint、Illustrator、PlantUML などを使った方がよい場合があります。
11. PlantUML や draw.io との使い分け
Mermaid は、PlantUML や draw.io と比較されることがあります。
大まかな使い分けは次のようになります。
| 用途 | おすすめ |
|---|---|
| README に簡単な図を入れたい | Mermaid |
| Qiita 記事で処理フローを説明したい | Mermaid |
| UML をかなり細かく書きたい | PlantUML |
| 見た目を細かく調整したい | draw.io |
| 発表スライド用に美しく整えたい | PowerPoint / Figma / Illustrator |
| コードと一緒に図を管理したい | Mermaid / PlantUML |
Mermaid は、詳細な設計を完璧に表すツールというより、設計や説明の入口に立つツールです。
最初に Mermaid で全体像を書き、必要に応じて PlantUML や draw.io に進む、という使い方が現実的だと思います。
12. よくあるエラーと注意点
Mermaid を使い始めると、いくつかつまずきやすい点があります。
インデントが崩れている
Mermaid は、完全に Python のようなインデント言語ではありませんが、インデントを整えて書いた方が安全です。
読みにくい例：
```mermaid
flowchart TD
A --> B
B --> C
```
読みやすい例：
```mermaid
flowchart TD
A --> B
B --> C
```
できるだけ、ノードや矢印の行にはインデントを入れると見やすくなります。
全角記号を使ってしまう
Mermaid の文法に使う記号は、基本的に半角で書きます。
たとえば、次のような記号です。
[ ]
( )
{ }
-->
-- Yes -->
日本語の文章は使えますが、構文に関わる記号は半角にするのが安全です。
ノード名と表示名を混同する
次の例を見てください。
A[入力ファイル]
ここで、A は Mermaid 内部で使うノードIDです。
入力ファイル は、図に表示されるラベルです。
つまり、
A[入力ファイル] --> B[解析]
は、
- 内部名
Aのノードに「入力ファイル」と表示する - 内部名
Bのノードに「解析」と表示する - A から B に矢印を引く
という意味です。
複雑な図では、ノードIDを分かりやすくすると読みやすくなります。
Input[入力ファイル] --> Analysis[解析]
図が複雑になりすぎる
Mermaid は便利なので、つい1枚の図に全部入れたくなります。
しかし、ノードが多すぎる図は読みにくくなります。
目安として、1枚の図に入れるノードは、最初は 5個から10個程度 に抑えるとよいです。複雑になってきたら、
- 図を分ける
-
subgraphで整理する - フローチャートではなくシーケンス図にする
- 詳細は本文で説明する
といった工夫をすると読みやすくなります。
13. コピペ用テンプレート集
ここからは、よく使う Mermaid のテンプレートをまとめます。
基本フロー
```mermaid
flowchart TD
A[開始] --> B[処理]
B --> C[終了]
```
条件分岐
```mermaid
flowchart TD
A[開始] --> B{条件を満たす？}
B -- Yes --> C[処理する]
B -- No --> D[終了する]
```
入力・処理・出力
```mermaid
flowchart LR
A[入力] --> B[処理]
B --> C[出力]
```
データ解析パイプライン
```mermaid
flowchart TD
A[生データ] --> B[前処理]
B --> C[品質チェック]
C --> D{問題なし？}
D -- Yes --> E[解析]
D -- No --> F[除外または再処理]
E --> G[可視化]
E --> H[結果保存]
```
API のシーケンス図
```mermaid
sequenceDiagram
participant User
participant App
participant API
participant DB
User->>App: 操作
App->>API: リクエスト
API->>DB: データ取得
DB-->>API: 結果
API-->>App: レスポンス
App-->>User: 表示
```
状態遷移図
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Success
Running --> Error
Success --> [*]
Error --> [*]
```
14. おまけ：研究・解析フローにも Mermaid は使える
Mermaid は、ソフトウェア開発だけでなく、研究やデータ解析の説明にも便利です。
研究では、数式、コード、文章がそれぞれ重要です。しかし、それだけでは「全体の流れ」が見えにくいことがあります。
たとえば、
- どのデータを入力にするのか
- どこでノイズ評価をするのか
- どの段階でフィルタを作るのか
- どこで推定値を得るのか
- どの結果を図や表にするのか
といった処理の流れは、文章だけで説明すると長くなりがちです。
ここで Mermaid を使うと、解析の全体像を一枚で共有できます。
例：TES 最適化フィルタ解析の概念図
ここでは、少し専門的な例として、TES マイクロカロリメータの最適化フィルタ解析を考えます。
詳しい物理や数式は省略しますが、処理の流れだけを見ると、Mermaid で次のように整理できます。
```mermaid
flowchart TD
subgraph Input[入力データ]
A[パルス波形]
B[ノイズ波形]
end
subgraph Noise[ノイズ評価]
C[PSDを計算]
D[ノイズ特性を推定]
end
subgraph Filter[フィルタ生成]
E[テンプレート波形を作成]
F[最適化フィルタを構築]
end
subgraph Estimate[推定]
G[フィルタを適用]
H[エネルギーを推定]
end
A --> E
B --> C
C --> D
D --> F
E --> F
F --> G
G --> H
```
このような図は、論文にそのまま載せる図というより、研究メモ、解析ノート、学生向け資料、共同研究者との議論に向いています。
Mermaid を使うことで、
| 表現 | 得意なこと |
|---|---|
| 数式 | 推定量やモデルを厳密に書く |
| コード | 実際に計算を実行する |
| Mermaid | 処理の流れや責務分担を見せる |
という役割分担ができます。
特に研究や解析では、「数式は正しいが、処理の流れが見えない」「コードは動くが、全体像が分からない」ということがよくあります。Mermaid は、その間をつなぐ補助線として使うと便利です。
まとめ
Mermaid は、Markdown の中に直接書ける図表記述言語です。
最大の利点は、図を画像として別管理するのではなく、文章やコードと同じようにテキストとして管理できることです。
この記事では、次の内容を紹介しました。
- Mermaid は Markdown に直接書ける図表言語である
- フローチャートは
flowchart TDから始める - ノードは
[ ]、( )、{ }などで形を変えられる - 条件分岐は
-- Yes -->のように書ける - シーケンス図は、誰が誰に何を送るかを表すのに便利
- 状態遷移図は、プログラムや装置の状態管理に便利
-
subgraphを使うと、複雑な処理をグループ化できる - Mermaid は README、Qiita、設計メモ、研究ノートと相性がよい
Mermaid は、美しい図を細かく作り込むためのツールではありません。
むしろ、
図を素早く書き、文章やコードと一緒に育てていくためのツール
です。
README や Qiita 記事で「ちょっと図を入れたい」と思ったとき、まずは Mermaid で書いてみると、ドキュメントの分かりやすさがかなり変わると思います。