マーメイド記法は、図をテキストで記述してそのまま描画させる書式です。GitHubやGitLabのMarkdownが標準で解釈するため、設計図をソースコードと同じリポジトリに置き、プルリクエストの差分としてレビューが可能です。この記事では、公式サイトが2026年9月時点で示すバージョン11.17.2の構文を前提に、フローチャート・シーケンス図・ER図・クラス図・状態遷移図の書き方をコード例つきで整理します。あわせて、図が表示されないときの切り分け、そして設計ドキュメントをこの記法へ寄せるべき対象と、寄せるべきでない場面の線引きまで踏み込みます。
まとめ｜マーメイド記法を設計ドキュメントへ採用する判断と最初に覚える構文
結論から書きます。覚える順序は「先頭1行の図種宣言」「ノードと矢印の記法」「図種ごとの固有句」の3段です。この順で読めば、flowchartを書けた時点でsequenceDiagramもerDiagramも同じ骨格で書けます。図種の宣言を間違えると以降の全行が解釈されないため、エラーの大半はここに集まります。
採用の線引きははっきりしています。変更頻度が高く、レビューで差分を追いたい図（内部設計の処理フロー、API間の通信順序、テーブル間の関連）はテキスト管理へ寄せる対象です。逆に、配置そのものに意味を持たせる提案資料の構成図や、ノードが数十を超える全社システム関連図は自動レイアウトが崩れるため、作図ツールに残したほうが手戻りが少なくなります。両方をリポジトリに置く場合は、どちらが正本かをREADMEに明記してください。二重管理は図の不一致を生み、設計書としての信頼を落とします。
マーメイド記法の基本構造とv11.17.2時点で描ける20種類以上の図
まず記法の骨格を押さえます。図種を問わず構造は共通で、覚える量は見た目ほど多くありません。
先頭の図種宣言とインデントで決まるmermaidコードブロックの最小構成
1行目に図種を宣言し、2行目以降に要素と関係を並べる。これが全図種に共通する構造です。フローチャートならflowchart TDのように図種と方向を書き、続く行で「ノード定義」と「ノード間の接続」を記述します。インデントは解釈に影響しませんが、階層が深い図では2スペース単位で揃えたほうが差分レビューが読みやすくなります。
flowchart TD
A[受注データ受信] --> B{在庫引当可否}
B -->|引当可| C[出荷指示を作成]
B -->|引当不可| D[入荷待ちキューへ登録]
C --> E([出荷完了])
D --> E方向指定はTD（上から下）のほかTB、BT、LR、RLが公式のフローチャート構文ドキュメントに定義されています。業務フローは縦方向、システム間の連携は横方向にすると、幅の広いモニタでも読み取りやすい形に落ち着きます。
GitHub・GitLabのMarkdownが標準対応する描画範囲とバージョン確認
GitHubは、言語識別子にmermaidを指定したコードブロックをそのまま図として描画します。GitHub公式ドキュメントが示すバージョン確認方法は、本文がinfo1語だけのmermaidブロックを置く手順です。手元の記法が動かないとき、環境側のバージョンが古いのか自分の構文が誤っているのかを最初に切り分けられます。
同ドキュメントには、サードパーティのMermaidプラグインを併用しているとGitHub側の構文解釈でエラーになる場合がある、という注意書きも置かれています。CIでMarkdownを別のレンダラに通しているリポジトリでは、ここが原因で「ローカルでは出るのにGitHub上では出ない」という食い違いが起きます。
MIT配布のOSSとしての位置づけとmermaid.aiへの統合という現在地
Mermaid本体はGitHubのmermaid-js/mermaidでMITライセンスのもと公開されており、2026年9月時点でスター数は90.1k、READMEには「20+ Diagram Types」としてフローチャート、シーケンス図、クラス図、状態図、ER図、ガントチャート、円グラフ、Git Graph、マインドマップ、タイムライン、サンキー図が並びます。社内システムの設計書に使う場合でも、ライセンス上の制約で止まる場面はほぼありません。
一方で運営体制は動いています。公式サイトは現在「Mermaid.js now lives at mermaid.ai」として、OSSライブラリとその周辺プラットフォームを同一の場所に統合したことを告知しています。ドキュメントのURLを社内Wikiへ引用しているなら、リンク切れが起きていないか一度確認しておくとよいでしょう。表示されているバージョンは11.17.2です。
フローチャートとシーケンス図の記法比較と設計工程での書き分け基準
設計レビューで混乱が起きるのは、同じ処理をフローチャートで描く人とシーケンス図で描く人が混在するときです。記法の違いと、どちらを主にするかの基準を先に決めます。
ノード形状と矢印種別で処理と判断を描き分けるフローチャートの記法
フローチャートの表現力は、ノードを囲む括弧の種類と矢印の線種で決まります。実務で使う組み合わせは限られており、次の範囲を覚えれば内部設計の処理フローはほぼ書けます。
| 用途 | 記法 | 描かれる形 |
|---|---|---|
| 通常の処理 | A[テキスト] | 矩形 |
| 条件分岐 | B{テキスト} | 菱形 |
| 開始・終了 | C([テキスト]) | スタジアム形 |
| データストア | D[(テキスト)] | 円筒形 |
| 通常の遷移 | A 半角ハイフン2つと不等号 B | 実線矢印 |
| 非同期・例外 | A 点線矢印記法 B | 点線矢印 |
公式ドキュメントによると、バージョン11.3.0でA@{ shape: cyl }という統一構文と30種類の新形状が追加され、11.17.0では折りたたみ可能なサブグラフが入りました。ただし古い括弧記法も併存しているため、社内で書式が割れないよう、使ってよい形状をチーム内で6種類程度に絞って運用したほうが読みやすさは保てます。
participantとactivate句で通信順序を固定するシーケンス図の記法
シーケンス図は登場人物をparticipantで宣言し、その間のメッセージを時系列で並べる構文です。autonumberを先頭に置くとメッセージへ連番が振られ、レビューで「7番の呼び出しはタイムアウト時どうなるか」といった指摘がしやすくなります。activateとdeactivateで処理中の区間を明示すると、どの層が待っているのかが一目で分かります。
sequenceDiagram
autonumber
participant U as 購入者
participant W as 受注Web
participant P as 決済API
U->>W: 注文確定を送信
activate W
W->>P: オーソリ要求
P-->>W: 承認コードを返却
W-->>U: 注文番号を表示
deactivate W実線の矢印が要求、破線の矢印が応答という書き分けは公式のシーケンス図構文の定義に沿ったものです。UMLとしての読み方や複合フラグメントの扱いはシーケンス図の書き方をUMLの記法から整理した記事で詳しく扱っています。
業務フローと通信仕様のどちらを主にするかで決まる図種の選択基準
判断軸は「時間軸に意味があるか」の一点です。人の判断や分岐が主役なら、フローチャートを選びます。誰が誰をどの順で呼ぶかが主役なら、シーケンス図です。受注から出荷までの業務フローを描くならフローチャート、その中の決済処理だけを外部API込みで詰めるならシーケンス図、と粒度で使い分けると重複が起きません。
両方を1枚に詰め込もうとすると失敗します。分岐が5本を超えたフローチャートに通信の応答まで書き込むと、線が交差して読めなくなり、結局レビューで誰も見なくなります。分岐が主役の図から通信の詳細を切り出し、別のシーケンス図へ逃がしてください。
ER図・クラス図・状態遷移図をmermaidで書くときの型定義と注意点
ここから先は、実装に直結する3つの図です。属性の型まで書けるので、設計レビューの粒度が一段細かくなります。
カーディナリティ記号と属性行でテーブル設計を表すerDiagramの書式
ER図はerDiagramで宣言し、エンティティ間を記号で結ぶ書式です。||が1、o{が0以上、|{が1以上を表し、左右それぞれに置いて多重度を示します。中括弧のブロックにbigint customer_id PKのように「型・カラム名・キー種別」の順で並べると、そのままテーブル定義のレビュー資料になります。
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
ITEM ||--o{ ORDER_ITEM : referenced
CUSTOMER {
bigint customer_id PK
varchar name
varchar email UK
}
ORDER {
bigint order_id PK
bigint customer_id FK
datetime ordered_at
}キー種別はPK、FK、UKが公式のER図構文に定義されています。DDLと図がずれると設計書としての価値が消えるため、マイグレーションファイルを変更したプルリクエストでは同じ差分にER図の更新も含める運用にしてください。カーディナリティの読み方そのものに不安があれば、ER図の書き方とリレーションの考え方をまとめた記事を先に読むと迷いません。
可視性記号と関連線でドメインモデルを表現するclassDiagramの書式
クラス図では先頭の宣言がclassDiagramです。メンバの先頭に+を置けばpublic、-ならprivate、#ならprotectedを表し、ジェネリクスはList~OrderItem~のようにチルダで囲みます。集約はo--、コンポジションは*--、継承は矢頭付きの線で書き分けます。
classDiagram
class Order {
+Long orderId
+Long customerId
-List~OrderItem~ items
+confirm() void
+cancel(reason) void
}
class OrderItem {
+Long itemId
+int quantity
}
Order "1" o-- "1..*" OrderItem関連線の両端に"1"や"1..*"を置くと多重度を明示できます。この記法は公式のクラス図構文に一覧があります。集約とコンポジションのどちらを選ぶかで実装の削除カスケードが変わるため、判断に迷う場合はクラス図の関連と多重度を実装目線で解説した記事の基準に合わせるのが早道です。
状態と遷移条件を列挙するstateDiagram-v2で仕様漏れを潰す進め方
状態遷移図はstateDiagram-v2で宣言し、[*]で開始と終了を表す書式です。遷移の後ろにコロンで条件を書けるので、「どの状態からどの状態へ、何をきっかけに動くか」を1行ずつ確認できます。テキストで並ぶ利点はここに出ます。状態数と遷移数を数えれば、書き漏らした組み合わせが機械的に見つかるためです。
stateDiagram-v2
[*] --> 受付済
受付済 --> 与信待ち : 決済要求を送信
与信待ち --> 引当済 : 与信OK
与信待ち --> 与信失敗 : 与信NG
引当済 --> 出荷済 : 出荷指示を確定
与信失敗 --> [*]
出荷済 --> [*]この例では「引当済からのキャンセル」が定義されていません。図にした瞬間に穴が見えるのが、状態遷移図を設計レビューへ持ち込む理由です。受注・決済・在庫のように状態を持つ業務では、実装前に一度この形へ落としておくと、テスト設計時の異常系の洗い出しがそのまま流用できます。
mermaid記法を描画できる環境の対応範囲とレビュー運用への組み込み
記法を覚えても、描画される場所を決めないと運用に乗りません。編集時・レビュー時・公開時のどこで図を見せるかで、選ぶ環境が変わります。
Live Editorとエディタ拡張で分かれる編集時プレビューの選択基準
書きながら形を確かめたいだけなら、ブラウザで完結するLive Editorが手軽です。設定なしで開けて、共有用URLもその場で生成できます。操作手順と無料で使える範囲はMermaid記法の使い方とLive Editorの操作をまとめた記事に整理しました。
一方、設計書をリポジトリで管理するなら、エディタ拡張のほうが往復が減ります。Markdownファイルを開いたまま図を確認でき、そのままコミットへ進めるからです。画像として書き出す手順まで含めた比較はVSCodeでMermaidを使う方法と画像出力を解説した記事で扱っています。どちらか一方に統一する必要はなく、下書きはLive Editor、確定後はリポジトリ、という分担で問題ありません。
図が表示されない場合に切り分ける記法エラーと描画環境側の制限
図が出ないときは、原因を2種類に分けて考えます。1つ目は記法エラーで、この場合はどの環境でも同じ位置で失敗します。図種宣言のスペル、全角スペースの混入、ノードIDに使えない記号の3点を先に疑ってください。2つ目は描画環境側の制限で、この場合はLive Editorでは出るのに表示先では出ません。
自前のWebページへ埋め込んでいるなら、初期化オプションの確認が要ります。公式のUsageページにはsecurityLevelとしてstrict、loose、antiscript、sandboxの4値が定義されており、この設定によってHTMLラベルやクリックイベントの扱いが変わります。
// ページ内で描画するときの初期化例
mermaid.initialize({
startOnLoad: true,
securityLevel: 'strict',
flowchart: { useMaxWidth: false }
});エディタ側で図が出ないケースの具体的な対処は、VSCodeでMermaidが表示されないときの対処をまとめた記事に手順があります。
プルリクエストの差分で図の変更点を追えるテキスト管理の運用手順
テキストで書く価値が最大化されるのは、レビュー工程です。画像ファイルの差分は「変わった」ことしか分かりませんが、テキストなら「どのノードが増え、どの遷移条件が変わったか」まで行単位で追えます。次の順で組み込むと定着します。
- 図をMarkdownファイルとしてリポジトリ内の設計ドキュメント配下に置く
- 実装コードと同じプルリクエストで図の変更を含める規約にする
- レビュー観点に「図と実装の齟齬がないか」を1項目として追加する
- 公開先のWikiへは自動同期させ、手作業でのコピーを禁止する
4番目を守れないと、リポジトリとWikiで内容が食い違い、どちらが正しいか分からない状態に戻ります。設計情報を1か所に集約する考え方は、SSOTの意味とデータ一元化の設計を解説した記事で扱った原則がそのまま当てはまります。
設計ドキュメントをmermaidに寄せる判断基準と採用を見送る条件
ここは判断を言い切ります。全ての図をテキスト化する必要はなく、移行して効果が出る対象は限られています。
変更頻度が高い内部設計図から移行すると効果が出やすい対象の順序
着手順は、更新頻度の高い順です。第一に状態遷移図とシーケンス図、第二にER図、第三に画面遷移図。この3つは仕様変更のたびに書き換えが発生し、放置すると実装との乖離が最も早く進みます。逆に、年に1回しか触らない全体構成図を最初に移行しても、レビュー効率の改善はほとんど得られません。
既存システムの改修で「設計書が更新されておらず、実装を読むしかない」状態に陥っているなら、図の形式より先に現行仕様の再構築が必要です。当社では現行システムの調査と仕様の可視化を含むシステムマイグレーション・リプレイスとして、ドキュメントが失われた環境からの移行を請けています。
レイアウト指定が必要な提案資料や大規模構成図で見送るべき場面
採用しないほうがよい場面を明示します。1つ目は、配置そのものに意味を持たせる資料です。経営層向けの提案書で「左が現行、右が将来像」と対比させる図は、自動レイアウトでは意図した位置に固定できません。2つ目は、ノードが40を超える大規模なネットワーク構成図やシステム関連図です。自動配置では線の交差が増え、可読性が落ちます。
この2つは作図ツールに残してください。無理にテキスト化すると、レイアウト調整のための記述が本来の構造記述より長くなり、差分レビューという最大の利点が消えます。判断基準は単純で、「配置を人が決めたい図」は対象外です。
作図ツールと併用する場合に決めておく図の正本と生成物の管理ルール
併用する場合、決めるべきは2点だけです。図ごとに正本の置き場所を1つに固定すること。そして、そこから生成した画像は生成物として扱い、直接編集を禁止することです。この2点を決めずに走ると、リポジトリのMarkdownと共有ドライブのファイルが別々に更新され、半年後には照合不能になります。
正本の一覧はREADMEに表で置き、図の名前・形式・置き場所・更新責任者を並べます。1行で済む管理ですが、これがないまま運用したプロジェクトでは、リリース直前に「どのER図が最新か」を探す時間が発生します。手間の差は初期の10分と、後工程の数時間です。
よくある質問
マーメイド記法の導入時に実際に検索されている質問へ、順に答えます。
マーメイド記法はどこで書けば図として表示されますか？
GitHubとGitLabのMarkdownは標準で解釈するため、リポジトリ内のREADMEやIssue、プルリクエストの本文にそのまま書けば描画されます。ブラウザだけで試すならLive Editor、エディタで書くならVS Codeの拡張機能が選択肢です。自社のWebアプリへ埋め込む場合は、npmでmermaidパッケージを導入するか、CDNからESモジュールとして読み込みます。表示先ごとに対応バージョンが異なるため、新しい構文を使うときは事前に確認してください。
mermaidの図がGitHubで表示されないのはなぜですか？
多いのは、コードブロックの言語識別子をmermaidにし忘れているケースと、図種宣言のスペルミスです。次に多いのが、GitHub側が対応していない新しい構文を使っている場合で、本文がinfoだけのmermaidブロックを置けば、その環境のバージョンを確認できます。GitHubの公式ドキュメントは、第三者のMermaidプラグインを併用しているとエラーが出る場合があるとも記載しています。全角スペースの混入も見落としやすい原因です。
マーメイド記法でER図の主キーや外部キーはどう書きますか？
エンティティ名の後ろに中括弧のブロックを置き、「型・カラム名・キー種別」の順に1行ずつ並べる書式です。キー種別は主キーがPK、外部キーがFK、一意キーがUKで、公式のER図構文に定義されています。エンティティ間の多重度は||が1、o{が0以上、|{が1以上を表す記号を組み合わせて指定する形です。DDLの変更と同じプルリクエストで図も更新する規約にしておくと、乖離を防げます。
マーメイド記法とPlantUMLはどちらを選ぶべきですか？
GitHubやGitLabのMarkdownで追加のレンダラなしに描画したいなら、標準対応しているマーメイド記法が扱いやすくなります。一方、UMLの厳密な表記に沿った図種を細かく描き分けたい場合や、既存の設計資産がPlantUMLで蓄積されている場合は、そのままPlantUMLを継続するほうが移行コストを負いません。判断軸は表現力よりも「レビューする場所で追加設定なしに描画されるか」です。両方を並行運用すると記法の混在で読み手が迷います。
mermaidで描いた図を画像ファイルとして書き出せますか？
書き出せます。Live EditorにはPNGやSVGとしてダウンロードする機能があり、VS Codeの拡張機能からも画像出力が可能です。公式ドキュメントにはコマンドラインから扱うMermaid CLIのページも用意されており、CIで自動生成する構成も取れます。ただし書き出した画像は生成物として扱い、正本はテキスト側に置いてください。画像を直接編集すると、差分レビューという利点が失われます。
関連記事
- Mermaid記法の使い方を完全ガイド｜無料のLive Editorでフローチャート・シーケンス図を作成：ブラウザだけで書式を試すときの操作手順を扱っています。
- VSCodeでMermaidを使う方法｜記法・図作成・画像出力とAI拡張mermAId：エディタでの編集と画像書き出しの手順をまとめています。
- シーケンス図とは？UMLの書き方・ライフラインやメッセージ・複合フラグメントを解説：本記事のシーケンス図の章をUMLの表記から補います。
- ER図とは？書き方・エンティティやリレーション・カーディナリティを実装目線で解説：多重度の読み方とテーブル設計への落とし込みを扱っています。
- クラス図とは？UMLの書き方・関連や多重度・集約とコンポジションの違いを解説：集約とコンポジションの選び分けを詳しく解説しています。
