2026年9月25日時点で、Mermaid（マーメイド）記法は「図をテキストで書き、表示する側のツールが自動で描画する」ための記法です。公式ドキュメントの「Diagram Syntax」に並ぶ図の種類は31種類、公開中の最新版は 12.0.0。GitHub・GitLab・VS Code・Obsidian の4つは、追加の拡張機能なしで mermaid と書いたコードブロックをそのまま図として描画すると各公式ドキュメントに明記されています。覚えるのは「1行目で図の種類を宣言する」「矢印でつなぐ」の2つだけで、最小のフローチャートは2行で書けます。
Mermaid が注目されるのは、生成AIとの相性が理由です。AIが出せるのはテキストなので、図を頼むと画像ではなくMermaidのコードが返ってきます。それを貼るだけで図になる場所（GitHubのIssue、VS Codeのプレビュー、Obsidianのノート）を知っているかどうかで、設計書や議事録を作る速度が変わります。この記事では、公式ドキュメントに載っている記法と描画対応だけを使って、8種類の最小記法・AIに描かせるプロンプト7本・描画できる場所の対応表・公式が警告しているエラー5つを整理します。本文のコードはすべて mermaid.js.org・GitHub Docs・VS Code 公式ドキュメント・Obsidian 公式ヘルプに掲載されている例です。
Mermaid記法とは｜テキストで書いて、ツール側が図にする
この記事の要点
- 要点1：Mermaid は JavaScript 製の作図ツールで、公式は「Markdown 風のテキスト定義を図に変換する」と説明しています。図の実体はコードなので、Git で差分が見え、AIがそのまま生成できます。
- 要点2：2026年9月25日時点で、公式ドキュメントに描画対応が明記されている主な場所は GitHub（Issues・Discussions・プルリクエスト・Wiki・Markdown ファイル）、GitLab（Mermaid バージョン11対応）、VS Code（組み込みの Markdown プレビュー）、Obsidian（
mermaidコードブロック）です。 - 要点3：最新の 12.0.0 からフローチャートの既定が変わりました。テーマが
redux-color、見た目がneo、レイアウトエンジンが Dagre から ELK になっています。以前の見た目に戻す指定も公式に用意されています。
対象読者：設計書・議事録・手順書に図を入れたい開発者・PM・情報システム担当。作図ツールを立ち上げる時間がなく、AIに図の下書きを任せたい人。
今日やること：手元のドキュメントから図にしたい箇所を1つ選び、後述のプロンプト1本をAIに投げ、返ってきたコードを VS Code のプレビューか Mermaid Live Editor に貼って表示を確認する。
公式サイト「About Mermaid」は、Mermaid を「テキストとコードで図や可視化を作れるようにするもの」と定義しています。JavaScript ベースの作図・チャート作成ツールで、Markdown から着想を得たテキスト定義をレンダラーが図に変換する、という構成です。公式が挙げている目的は1つで、「ドキュメントを開発に追いつかせること」。図の更新が後回しになって資料が腐る状態（公式は Doc-Rot と呼んでいます）を、図をコード化することで解決する、という位置づけです。
動きは3段に分かれます。（1）書く：mermaid という言語識別子を付けたコードブロックの中に記法を書く。（2）渡す：GitHub や VS Code などの表示側が、そのブロックを Mermaid のパーサーに渡す。（3）描く：Mermaid が SVG を生成して画面に表示する。つまり書き手が用意するのはテキストだけで、画像ファイルは1つも生まれません。
最小のフローチャートは、公式ドキュメントの例どおり次の2行です。
flowchart LR
Start --> Stop1行目の flowchart が図の種類、LR が向き（左から右）です。公式が挙げている向きは TB（上から下）、TD（上から下・TBと同じ）、BT（下から上）、RL（右から左）、LR（左から右）の5つです。2行目の --> が矢印。この「1行目で種類、2行目以降で中身」という形は、後述するシーケンス図やガントチャートでも変わりません。
自分のサイトに組み込むときの最小構成
すでに Mermaid が組み込まれているサービスに書くだけなら準備は不要ですが、自社のドキュメントサイトに載せる場合は、公式の「About Mermaid」にある次のスクリプトを HTML に入れます。
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>公式の説明では、これで Mermaid のパーサーが class="mermaid" を持つ <div> または <pre> タグを探し、その中の定義を読んで SVG に描画します。バンドラーを使って導入する場合は Node.js v22.12.0 以降が必要で、npm i mermaid（または yarn add mermaid、pnpm add mermaid）と公式に書かれています。
12.0.0 で既定の見た目が変わっている
ここは既存の解説記事と食い違いが出やすい点です。公式のフローチャート構文ページには「Default theme, look and layout（v12.0.0 以降）」という節があり、フローチャートは既定で redux-color テーマ・neo ルックになり、レイアウトは Dagre ではなく ELK で行われると書かれています。すべての図種が同じ既定というわけではなく、図種ごとの既定は公式のテーマ設定ページに一覧があります。
以前の見た目に戻したいときは、公式どおり図の冒頭（フロントマター）で3つのキーを指定します。
---
config:
theme: default
look: classic
layout: dagre
---
flowchart LR
subgraph Client
UI[Web app]
Cache[(Local cache)]
end
subgraph Services
API[API gateway]
Auth[Auth service]
Orders[Order service]
end
subgraph Storage
DB[(Orders DB)]
end
UI --> API
UI --> Cache
API --> Auth
API --> Orders
Orders --> DB
Auth -. token .-> UI公式は「どちらも既定にすぎないので、自分で指定したものが優先される」と明記しています。同じ3つのキーを mermaid.initialize() に渡せば、そのページのすべての図に適用されます。社内の図の見た目を揃えたい場合は、この指定を社内テンプレートに書いておくのが早い方法です。
Mermaidで描ける図は31種類｜まず覚える8つの最小記法一覧
公式ドキュメントの左サイドバー「Diagram Syntax」に並ぶ図の種類は、2026年9月25日時点で31種類あります。フローチャート、スイムレーン、シーケンス図、クラス図、状態遷移図、ER図、ユーザージャーニー、ガント、円グラフ、四象限チャート、要求図、ユースケース図、GitGraph、C4、マインドマップ、タイムライン、ZenUML、サンキー、XYチャート、ブロック図、パケット図、かんばん、アーキテクチャ図、レーダーチャート、イベントモデリング、ツリーマップ、ベン図、特性要因図、ワードリーマップ、クネビン、ツリービューです。
ただし実務で使うのはこのうち一部です。業務ドキュメントで出番が多い8種類について、宣言キーワードと使いどころを先に一覧にします。
| 図の種類 | 1行目の宣言 | 主な使いどころ |
|---|---|---|
| フローチャート | flowchart（または graph） |
業務フロー、処理の分岐、システム構成の概略 |
| シーケンス図 | sequenceDiagram |
API連携、画面と裏側のやり取り、障害時の経路 |
| クラス図 | classDiagram |
データ構造、オブジェクト設計、責務の分割 |
| 状態遷移図 | stateDiagram-v2 |
申請ステータス、注文ステータス、画面遷移 |
| ER図 | erDiagram |
テーブル設計、マスタとトランザクションの関係 |
| ガントチャート | gantt |
プロジェクト計画、導入スケジュール |
| 円グラフ | pie |
構成比の速報、簡易な内訳表示 |
| マインドマップ | mindmap |
論点の洗い出し、議事録の整理 |
1. フローチャート（mermaid 記法 フローチャート）
ノード（図形）とエッジ（線）で構成します。公式のサブグラフの例です。
flowchart TB
c1-->a2
subgraph one
a1-->a2
end
subgraph two
b1-->b2
end
subgraph three
c1-->c2
endsubgraph から end までが1つの枠になります。線の種類は公式に表があり、実線が ---、矢印つきが -->、太線が ===、太線の矢印が ==>、点線が -.-、点線の矢印が -.-> です。ダッシュやドットを増やすと線が長くなり、レイアウト上の段（ランク）をまたぐ距離を指定できます。
2. シーケンス図（mermaid 記法 シーケンス図）
公式の最小例です。登場人物を宣言しなくても、メッセージを書けば自動的に登場します。
sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!矢印は [Actor][Arrow][Actor]:Message text の形で書きます。公式の表によると、-> は矢印なしの実線、--> は矢印なしの点線、->> は矢印つきの実線、-->> は矢印つきの点線、-x は末尾がバツ印の実線、-) は末尾が開いた矢印（非同期）です。双方向の矢印 <<->> と <<-->> はバージョン 11.0.0 以降で使えます。
登場人物に役割を与え、通番を振った公式の例がこちらです。API連携の説明にはこの形が近くなります。
sequenceDiagram
autonumber
actor Customer
participant Web as Web app
participant API as API gateway
participant Bank
Customer->>Web: Place order
Web->>API: POST /orders
activate API
API->>Bank: Authorise payment
Bank-->>API: Approved
API-->>Web: 201 Created
deactivate API
Web-->>Customer: Order confirmed
Note over Customer,Bank: One order, one transaction3. クラス図（mermaid 記法 クラス図）
公式の例では、クラスの定義・関連・多重度をまとめて書けます。
classDiagram
class Customer {
+String name
+String email
}
class Order {
+String id
+Date placedAt
+total() Money
}
class LineItem {
+int quantity
}
class Payment {
<<interface>>
+authorise() bool
}
Customer "1" --> "*" Order : places
Order "1" *-- "*" LineItem : contains
Order --> Payment : settled by4. 状態遷移図
公式の最小例です。[*] が開始と終了を表します。
stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]5. ER図（mermaid 記法 er図）
公式の Order example です。属性を書かない簡易版と、属性まで書く版の両方が公式に載っています。
erDiagram
CUSTOMER ||--o{ ORDER : places
CUSTOMER {
string name
string custNumber
string sector
}
ORDER ||--|{ LINE-ITEM : contains
ORDER {
int orderNumber
string deliveryAddress
}
LINE-ITEM {
string productCode
int quantity
float pricePerUnit
}6. ガントチャート（mermaid ガントチャート）
公式の基本例です。dateFormat で入力日付の書式を宣言し、section で区切り、タスクごとに「ID, 開始日, 期間」を書きます。
gantt
title A Gantt Diagram
dateFormat YYYY-MM-DD
section Section
A task :a1, 2014-01-01, 30d
Another task :after a1, 20d
section Another
Task in Another :2014-01-12, 12d
another task :24d公式が注意しているのは excludes の挙動です。「日付・曜日・weekends を除外指定した場合、ガントチャートはタスクの中に空白を作るのではなく、同じ日数だけ右へ延長する」と明記されています。一方、連続して始まる2つのタスクの間に除外日がある場合は、グラフ上はスキップされて空白になり、次のタスクは除外期間の後から始まります。除外指定は YYYY-MM-DD 形式の特定の日付、曜日名（sunday など）、weekends を受け付けますが、weekdays という語は使えないと公式に書かれています。
7. 円グラフ
もっとも短い図です。公式の例をそのまま引きます。
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 158. マインドマップ
インデントの深さがそのまま階層になります。公式の形状指定の例です。
mindmap
id(I am a rounded square)どこに書けば図になるか｜描画できる場所の対応表（2026年9月25日時点）
「Mermaid記法はどのエディタで使えますか」は、実際に検索されている質問です。ここでは各サービスの公式ドキュメントに記載があるものだけを表にします。記載を確認できなかったものは「公式に記載なし」と書いています。
| 場所 | 描画 | 公式ドキュメントの記載（2026年9月25日取得） |
|---|---|---|
| GitHub | 対応 | Issues・Discussions・プルリクエスト・Wiki・Markdown ファイルで描画。mermaid 言語識別子付きのコードブロックに書く |
| GitLab | 対応 | Mermaid バージョン11に対応。PlantUML・Kroki も利用可。Wiki では diagrams.net エディタも使える |
| VS Code | 対応 | 組み込みの Markdown プレビューが mermaid フェンスドコードブロックを描画。拡張機能の追加は不要 |
| Obsidian | 対応 | mermaid コードブロックを作ると図になる。公式ヘルプに手順と例を掲載 |
| Notion | 対応（開発者ドキュメントに記載） | 拡張 Markdown 形式の仕様に「Mermaid の図には mermaid を使う」と明記 |
| Mermaid Live Editor | 対応 | 公式が「プログラマーでなくても図を作れる」場所として案内している公式エディタ |
| Claude（アーティファクト） | 公式に Mermaid の語の記載なし | 公式ヘルプはアーティファクトの種類として「図とフローチャート」を挙げているが、Mermaid という語の記載は確認できず |
| ChatGPT（キャンバス） | 未確認 | 公式ヘルプページが 403 で取得できず。描画可否を本記事では断定しない |
GitHub：4つの記法のうちの1つとして位置づけられている
GitHub Docs の「Creating diagrams」は、Markdown で図を作る方法を mermaid・geojson・topojson・ASCII STL の4つの記法と説明し、描画できる場所として「GitHub Issues、GitHub Discussions、プルリクエスト、Wiki、Markdown ファイル」を挙げています。掲載されている最小例がこちらです。
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;実務で効くのが、同じページにあるバージョン確認の方法です。「自分が書いた Mermaid 構文を GitHub がサポートしているか確かめるには、現在使われている Mermaid のバージョンを確認する」として、次のブロックを書く方法が案内されています。
infoこれを mermaid コードブロックに書くと、その環境の Mermaid バージョンが表示されます。新しい図種（公式の一覧で「実験的」と付いているもの）を使う前に、貼り付け先で1回試しておくと、描画されない原因の切り分けが一度で済みます。GitHub Docs は「サードパーティの Mermaid プラグインを動かしている状態で GitHub 上の Mermaid 構文を使うとエラーが出ることがある」とも注意しています。
GitLab：バージョン11、ほかの作図記法も併用できる
GitLab のドキュメントは「GitLab は Mermaid バージョン11 をサポートする」と明記しています。treeView-beta の図は GitLab 19.4 で導入されたという記載もあります。Mermaid のほかに PlantUML と Kroki が使え、Wiki では diagrams.net エディタで作った図も追加・編集できます。加えて「Mermaid Live Editor は Mermaid の学習と、コードの問題のデバッグに役立つ」と公式が推奨しています。GitLab を使っているチームの Mermaid 運用は、Claude Code GitLab連携完全ガイドで扱っているマージリクエストの自動化と組み合わせると、設計変更と図の更新を同じ流れに乗せられます。
VS Code：プレビューが標準で描画する（mermaid 記法 vscode）
VS Code の公式ドキュメント「Markdown editing」には「VS Code の組み込み Markdown プレビューは、mermaid フェンスドコードブロックの Mermaid 図を描画する」と書かれています。掲載されている例がこちらです。
flowchart LR
Sleep[Sleep] --> Wake{Awake?}
Wake -->|No| Sleep
Wake -->|Hungry| Snack[Get treat]
Wake -->|Not in sunbeam| Move[Move to sunbeam]
Wake -->|Human is typing| Keyboard[Sleep on keyboard]
Snack --> Sleep
Move --> Sleep
Keyboard --> Sleep大きな図の扱いについても公式に記載があります。プレビュー上で図をパン（移動）・ズームでき、既定のマウス操作は Alt キー（macOS では Option キー）を押しながらのドラッグで移動、スクロールで拡大縮小、クリックで拡大。Alt と Shift を同時に押しながらのクリックで縮小、ピンチ操作なら Alt を押さずにズームできます。図にカーソルを合わせるとパンモードの切り替え・拡大・縮小・リセットのコントロールが出ます。右クリックメニューの「Copy Diagram Source」で、描画済みの図から元の Mermaid コードをコピーできる点も、レビュー時に使えます。
Obsidian と Notion：コードブロックの言語指定だけ
Obsidian の公式ヘルプ「Advanced formatting syntax」には「Mermaid を使ってノートに図やチャートを追加できる」と書かれ、フローチャート・シーケンス図・タイムラインが例示されています。追加方法は mermaid コードブロックを作るだけで、公式ヘルプには次の例がそのまま載っています。
sequenceDiagram
Alice->>+John: Hello John, how are you?
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
John-->>-Alice: I feel great!公式ヘルプは補足として「ノートに入れる前に Mermaid の Live Editor で図を組み立てるとよい」とも案内しています。Notion については、ヘルプセンターの「Code blocks」ページを 2026年9月25日に取得した時点では Mermaid の記載を確認できませんでした。一方、Notion の開発者向けドキュメント「Enhanced markdown format」には、コードブロックの説明として「Mermaid の図には mermaid を使う」と明記されています。Notion を業務の記録先にしているチームは、Notion Agent APIの使い方で扱う API 経由の書き込みと合わせると、図つきの記録を自動で積み上げられます。
AIに図を描かせるプロンプト7本｜そのままコピーして使う
Mermaid の価値が一段上がるのは、記法を人が覚えるのではなくAIに書かせて、人は直すだけにしたときです。AIの出力はテキストなので、画像生成と違って1文字単位で直せますし、間違っていればその行だけ指摘できます。
プロンプトに必ず入れる要素は3つです。（1）出力形式の固定：「Mermaid 記法のコードブロックだけを返す」と書き、説明文を止める。（2）図の種類の指定：flowchart なのか sequenceDiagram なのかを人が決める。AIに任せると、時系列の話をフローチャートで描くなど噛み合わない図が返ります。（3）素材の提供：議事録・仕様の本文をそのまま貼る。中身を渡さないと一般論の図が返ります。プロンプトを型として管理する考え方は、AIエージェントのプロンプト設計｜例とテンプレ8パターンで扱っている設計と同じです。
プロンプト1：議事録をフローチャートにする
以下の議事録から、業務の流れを Mermaid の flowchart TD で図にしてください。
条件：
- 出力は mermaid のコードブロックだけ。説明文は不要
- ノードは議事録に出てくる言葉だけを使い、新しい用語を作らない
- 分岐は {} の菱形で書く
- ノードは12個以内にまとめる
--- 議事録 ---
（ここに本文を貼る）プロンプト2：API連携をシーケンス図にする
以下の仕様から、Mermaid の sequenceDiagram を書いてください。
条件：
- 出力は mermaid のコードブロックだけ
- 登場するシステムは participant で先に宣言する
- 同期呼び出しは ->>、応答は -->> で書く
- autonumber を入れる
- 仕様に書かれていない処理を足さない
--- 仕様 ---
（ここに本文を貼る）プロンプト3：既存のテーブル定義をER図にする
以下のテーブル定義から Mermaid の erDiagram を書いてください。
条件：
- 出力は mermaid のコードブロックだけ
- リレーションの多重度は定義から読み取れる範囲だけ書く
- 読み取れない関係は書かず、末尾のコメント行に「不明」として列挙する
--- テーブル定義 ---
（ここに DDL を貼る）プロンプト4：ステータス管理を状態遷移図にする
以下の説明から Mermaid の stateDiagram-v2 を書いてください。
条件：
- 出力は mermaid のコードブロックだけ
- 開始と終了は [*] で書く
- 遷移の条件は矢印のラベルに短く書く
- 説明に出てこない状態を追加しない
--- 説明 ---
（ここに本文を貼る）プロンプト5：計画をガントチャートにする
以下の計画を Mermaid の gantt で書いてください。
条件：
- 出力は mermaid のコードブロックだけ
- dateFormat は YYYY-MM-DD を宣言する
- 土日を外す場合は excludes weekends を使う
- 期間が書かれていないタスクは、期間を推測せず日数を空欄にせずに「要確認」とラベルへ書く
--- 計画 ---
（ここに本文を貼る）プロンプト6：長い図を縮める
次の Mermaid コードは読みにくいので整理してください。
条件：
- 出力は mermaid のコードブロックだけ
- ノードの数を減らす場合は、消した要素を最後にコメント行で列挙する
- 関係の意味は変えない
- subgraph でまとまりを作ってよい
--- コード ---
（ここに Mermaid コードを貼る）プロンプト7：エラーが出た図を直す
次の Mermaid コードが描画されません。原因と修正版を出してください。
条件：
- 最初に原因を1行で書く
- 次に修正後の mermaid コードブロックを出す
- 図の内容は変えず、構文の問題だけ直す
--- コード ---
（ここに Mermaid コードを貼る）
--- 表示されたメッセージ ---
（あれば貼る）7本に共通しているのは「書かれていないことを足すな」という制約です。AIが図を作るときに起きやすいのは、素材に無い工程やシステムを補完してしまうことで、図になった瞬間にそれが事実のように見えてしまいます。図はレビューの対象物なので、元の文章にある語だけで描かせるほうが直す手数が減ります。
よくあるエラー5つと直し方｜公式が警告している落とし穴
Mermaid のエラーは、原因の大半が公式ドキュメントの警告ボックスに書かれています。よく踏むものを5つに絞ります。
エラー1：小文字の end でフローチャートが壊れる
公式のフローチャート構文ページの冒頭に警告があります。「フローチャートのノードで end という語を使う場合は、単語全体か一部の文字を大文字にする（例：End、END）。すべて小文字の end はフローチャートを壊す」。subgraph の終端キーワードと衝突するためです。日本語の図でも「end」を英語ラベルとして使うことがあるので、最初に疑う場所です。
エラー2：o と x で始まるノード名が線の種類に化ける
同じく公式の警告です。「つなぎ先のノード名の最初の文字に o または x を使う場合は、文字の前にスペースを入れるか、大文字にする（例：dev--- ops、dev---Ops）」。公式によると A---oB は丸印のエッジ、A---xB はバツ印のエッジとして解釈されます。ops、order、x-axis といった名前は業務の図に普通に出てくるため、これも頻出です。
エラー3：括弧や引用符を含むラベルで構文が壊れる
公式には「構文を壊す特殊文字」という節があり、「扱いにくい文字を描画するにはテキストを引用符で囲めばよい」として次の例が挙がっています。
flowchart LR
id1["This is the (text) in the box"]引用符そのものを表示したいときは、エンティティコードで逃がす方法が公式に示されています。
flowchart LR
A["A double quote:#quot;"] --> B["A dec char:#9829;"]数値は10進数で指定するため、# 自体は #35; と書けます。HTML の文字名も使えると公式に書かれています。
エラー4：ラベルが勝手に折り返される／折り返したいのに1行になる
公式の「Markdown Strings」の説明では、マークダウン文字列を使うとノード内のテキストが長くなったときに自動で折り返され、改行文字だけで改行できます（従来の文字列では <br> タグが必要でした）。自動折り返しが邪魔な場合は、公式どおり設定で止められます。
---
config:
markdownAutoWrap: false
---
graph LRこの指定はノードのラベル・エッジのラベル・サブグラフのラベルに効きます。
エラー5：クリックしても何も起きない／貼り付け先で描画されない
Mermaid はノードにクリックイベントを結びつけられますが、公式は「この機能は securityLevel='strict' では無効、securityLevel='loose' で有効」と注記しています。公開ドキュメントサイトは安全側の設定になっていることが多いので、「ローカルでは動くのに本番で動かない」はまずここを疑います。
そもそも図が出ない場合は、順に3つを確認します。（1）コードブロックの言語識別子が mermaid になっているか。（2）貼り付け先が対応している場所か（前掲の対応表）。（3）貼り付け先の Mermaid のバージョンが、使おうとしている図種に追いついているか。GitHub なら info の1行で、GitLab なら公式記載のバージョン11で判断できます。
法人の使いどころ｜設計書・議事録・手順書のどこで効くか
Mermaid が効くのは「図が古くなると困る場所」です。逆に、一度作って終わりの提案資料やプレゼン用の図では、見た目の自由度が高い作図ツールのほうが向きます。
1. 設計書：変更点が差分で見える
図がコードなので、プルリクエストの差分に「どのノードが増えたか」が行単位で出ます。画像ファイルの差し替えでは「前の図と何が変わったのか」がレビューで分からず、結局は口頭説明が必要になります。Mermaid にしておくと、仕様変更のレビューと図のレビューが同じ画面で完結します。GitHub ではプルリクエストの本文でも描画されるため、説明文の中に図を置けます。
2. 議事録：決まった流れをその場で図にする
議事録を書いた直後に前掲のプロンプト1を投げると、フローチャートの下書きが返ります。議論の最中に「つまりこの順番ですか」と確認する材料になるので、認識違いを翌週まで持ち越さずに済みます。長文のポリシーや手順をそのまま並べても読まれないという問題は、HANDBOOK.md解説｜長文ポリシーはエージェントを縛れないでも扱っています。図にして構造を見せるのは、その対処の1つです。
3. 手順書：分岐のある作業を1枚にする
「エラーが出たらこちら、出なければ次へ」という分岐を文章だけで書くと、読む側が自分の位置を見失います。フローチャートの菱形（{}）で分岐を書き、手順書の該当セクションに置くと、読み手は自分の現在地を1目で確認できます。手順の中身が変わったら、その行だけ書き換えます。
なお、ドキュメント生成や図の自動化をどのツールに任せるかは、扱う情報の置き場所によって変わります。エージェント系のツールを比較検討している段階なら、AIエージェントツール比較12選｜用途・料金・選び方で用途別の整理を確認してください。
法人で使うときの注意点｜貼り付け先・セキュリティ設定・バージョン差
Mermaid そのものは図を描くだけの仕組みですが、業務で使う以上は次の4点を先に決めておくほうが安全です。
| 決めること | 判断の材料 |
|---|---|
| どこに貼ってよいか | 図のラベルには顧客名・システム名・社内の用語が入る。社外サービスに貼る前に、通常の文書と同じ基準で扱う |
| クリック連携を許すか | 公式は securityLevel='strict' でクリックによる JavaScript コールバックが無効、'loose' で有効と明記。自社サイトに組み込むなら既定値を決める |
| どのバージョンに合わせるか | GitLab は公式にバージョン11、GitHub は info で確認。社内で使う図種を、いちばん古い環境に合わせる |
| 見た目を揃えるか | 12.0.0 でフローチャートの既定テーマ・ルック・レイアウトが変わった。揃えるならフロントマターか mermaid.initialize() で固定する |
特に3つ目は、複数のツールを併用しているチームで問題になります。ローカルの VS Code では新しい図種が描画できても、社内 Wiki 側の Mermaid が古ければ表示されません。「どの環境でも描けるのはこの8種類」と社内で線を引いておくと、貼り直しの手戻りが減ります。
Mermaid運用の失敗パターン4つ
失敗1：AIの出力をそのまま貼って、図の中身を確認しない
❌ AIが返した Mermaid コードを読まずに設計書へ貼る。
⭕ 描画された図のノードを1つずつ元の文章と突き合わせる。AIは素材に無い工程を補完することがあり、図にした瞬間に決定事項のように見えます。レビューの前に、書いた本人が「この四角はどの段落から来たか」を言える状態にします。
失敗2：1枚の図に全部を詰める
❌ 業務フロー全体を1つの flowchart に詰め込み、ノードが50個を超える。
⭕ 粒度で分け、subgraph でまとまりを作るか、図を分割する。公式には長い線を作る方法（ダッシュを増やす）やレイアウトの指定はありますが、情報量そのものを減らす機能はありません。読めない図は、描画に成功していても目的を果たしません。
失敗3：貼り付け先を確認せずに新しい図種を使う
❌ 公式ドキュメントで見つけた新しい図種を社内 Wiki に書き、表示されずに「Mermaid は使えない」と結論づける。
⭕ 先に info でバージョンを確認するか、前掲の対応表で描画先を確かめる。図種によって対応バージョンが違うことは公式の各ページに書かれています。
失敗4：図をスクリーンショットで共有する
❌ 描画された図を画像として撮り、資料に貼って配る。
⭕ 更新の必要がある図は、コードのまま共有する。画像にした時点で、Mermaid を使う最大の理由（更新が差分で追える）が消えます。どうしても画像で配る必要があるなら、元のコードを同じ場所に残しておきます。
Mermaidと他の作図手段の違い｜PlantUML・作図ツールとの使い分け
「Mermaid記法と PlantUML の違いは何ですか」は、実際に多く検索されている質問です。2026年9月25日時点で公式ドキュメントから確認できる事実ベースで整理します。
| 手段 | 実体 | 向いている場面 |
|---|---|---|
| Mermaid | JavaScript 製。表示側のレンダラーが SVG を生成する。公式に31種類の図種 | GitHub・GitLab・VS Code・Obsidian など、そのまま描画される場所に図を置きたいとき |
| PlantUML | GitLab が Mermaid と並べて公式にサポートしている別の作図記法 | すでに PlantUML の資産がある、または対応環境が整っているとき |
| Kroki | GitLab が公式に挙げている、複数の作図記法をまとめて扱う仕組み | 1つの環境で複数の記法を使い分けたいとき |
| diagrams.net エディタ | GitLab の Wiki で図の追加・編集に使えると公式に記載 | マウス操作で自由に配置を決めたいとき |
| 画像ファイル | 作図ツールで作った PNG・SVG | 更新予定がなく、見た目を細かく作り込みたい提案資料 |
判断の軸はシンプルで、「その図は今後書き換わるか」です。書き換わるならテキストで持ち、書き換わらないなら画像で持つ。業務ドキュメントの図は前者が大半なので、Mermaid が既定の選択肢になります。
よくある質問
Mermaid記法とMarkdownの違いは何ですか？
別物です。Markdown は文章の書式（見出し・箇条書き・リンク）を指定する記法、Mermaid は図の構造を指定する記法です。公式は Mermaid を「Markdown から着想を得たテキスト定義」と説明していますが、Markdown の仕様の一部ではありません。実際の使い方としては、Markdown のコードブロックに mermaid という言語識別子を付けて、その中に Mermaid 記法を書く、という入れ子の関係になります。
Mermaid記法の使い方は？ 最短で試す方法を教えてください
公式の Mermaid Live Editor を開き、本記事の2行のフローチャートを貼るのが最短です。何もインストールせずに描画結果を確認できます。手元のエディタで試すなら、VS Code で Markdown ファイルを作り、mermaid のコードブロックに同じ2行を書いてプレビューを開きます。公式ドキュメントに「拡張機能なしで描画する」と明記されています。
Mermaid記法はどのエディタで使えますか？
公式ドキュメントで描画対応が確認できるのは、本文の対応表のとおり GitHub、GitLab、VS Code、Obsidian、Notion（開発者ドキュメントに記載）、Mermaid Live Editor です。これ以外のツールについては、Mermaid 公式サイトに「Integrations – Community」という一覧ページがあり、コミュニティによる連携がまとめられています。導入前にそのツール自身の公式ドキュメントで確認してください。
プレビューするにはどうすればいいですか？
3通りあります。（1）Mermaid Live Editor に貼る。（2）VS Code の Markdown プレビューを開く。（3）GitHub の Issue やプルリクエストの本文欄でプレビュータブを使う。VS Code の場合は、大きな図をパン・ズームできる操作も公式に用意されています。
Mermaid記法とPlantUMLの違いは何ですか？
どちらもテキストから図を作る記法で、目的は近いものです。違いが出るのは対応環境です。GitLab のドキュメントは Mermaid・PlantUML・Kroki の3つを併記しており、環境によって使えるものが変わります。GitHub Docs が公式に挙げている図の記法は mermaid・geojson・topojson・ASCII STL の4つで、PlantUML は含まれていません。貼り付け先で決めるのが確実です。
Excel や PowerPoint の図を Mermaid記法に変換できますか？
2026年9月25日時点で、mermaid.js.org の公式ドキュメントに「既存の図ファイルを変換する機能」の記載はありません。実務では、図の内容を文章に起こしてから本記事のプロンプト1〜4でAIに書かせ、返ってきたコードを直す流れになります。元の図に書かれていない工程を足さないよう、プロンプトに制約を入れておくことが前提です。
コードにコメントは書けますか？
書けます。公式のガントチャートのページには「コメントはガントチャートの中に書けて、パーサーは無視する。コメントは独立した行に置き、先頭に %%（パーセント記号2つ）を付ける必要がある」と明記されています。コメント開始から次の改行までは、図の構文であってもすべてコメントとして扱われます。
ノードの文字が長いとき、改行や折り返しはできますか？
できます。公式の説明では、マークダウン文字列を使うとテキストが長くなったときに自動で折り返され、改行文字だけで改行できます。従来の文字列では <br> タグが必要でした。自動折り返しを止めたい場合は、フロントマターで markdownAutoWrap: false を指定します。
ChatGPT や Claude に図を描かせられますか？
Mermaid のコード自体は、どの生成AIでもテキストとして出力できます。問題はそれがその画面で図として描画されるかで、ここは各サービスの公式記載に従う必要があります。Claude の公式ヘルプは、アーティファクトとして作れるものの例に「図とフローチャート」を挙げていますが、2026年9月25日時点で Mermaid という語の記載は確認できませんでした。ChatGPT のキャンバスについては、公式ヘルプページが 403 で取得できなかったため、本記事では描画可否を断定しません。確実なのは、返ってきたコードを VS Code や Mermaid Live Editor に貼って確認する方法です。
作った図を画像として配るには？
mermaid.js.org の「About Mermaid」は、姉妹プロジェクトとして Mermaid Live Editor と Mermaid CLI を挙げています。画像への書き出し手順はそれぞれの公式ページで確認してください。ただし前述のとおり、更新される図を画像で配ると差分が追えなくなります。配布物に画像が必要な場合も、元の Mermaid コードを同じ場所に残しておくことをおすすめします。
運営元 Uravation よりAIエージェントを構想から本番運用まで進める順番と、体制・KPIの決め方をまとめた資料を無料で公開しています。 AIエージェント導入ロードマップを受け取る（無料）
参考・出典
- About Mermaid — Mermaid 公式ドキュメント（参照日 2026年9月25日・定義／Live Editor／CDN と初期化スクリプト／Node.js v22.12.0 以降／姉妹プロジェクト）
- Flowcharts – Basic Syntax — Mermaid 公式ドキュメント（参照日 2026年9月25日・向き5種類／線の種類／end と o・x の警告／特殊文字とエンティティコード／12.0.0 以降の既定テーマとELK／markdownAutoWrap／securityLevel）
- Sequence diagrams — Mermaid 公式ドキュメント（参照日 2026年9月25日・矢印の種類表／autonumber と participant の例）
- Gantt diagrams — Mermaid 公式ドキュメント（参照日 2026年9月25日・dateFormat／excludes の挙動／コメントの書き方）
- Class diagrams — Mermaid 公式ドキュメント（参照日 2026年9月25日・クラス定義と多重度の例）
- State diagrams — Mermaid 公式ドキュメント（参照日 2026年9月25日・stateDiagram-v2 の最小例）
- Entity Relationship Diagrams — Mermaid 公式ドキュメント（参照日 2026年9月25日・Order example）
- Pie chart diagrams — Mermaid 公式ドキュメント（参照日 2026年9月25日・円グラフの例）
- Mindmap — Mermaid 公式ドキュメント（参照日 2026年9月25日・形状指定の例）
- Creating diagrams — GitHub Docs（参照日 2026年9月25日・描画される場所／4つの記法／info によるバージョン確認／プラグイン併用の注意）
- GitLab Flavored Markdown — GitLab Docs（参照日 2026年9月25日・Mermaid バージョン11／PlantUML・Kroki／diagrams.net／Live Editor の推奨／treeView-beta は GitLab 19.4）
- Markdown editing in Visual Studio Code — Visual Studio Code Docs（参照日 2026年9月25日・組み込みプレビューでの描画／パンとズームの操作／Copy Diagram Source）
- Advanced formatting syntax — Obsidian Help（参照日 2026年9月25日・mermaid コードブロックでの図／Live Editor の案内／シーケンス図の例）
- Enhanced markdown format — Notion Developers（参照日 2026年9月25日・コードブロックで mermaid を使う記載）
- What are artifacts and how do I use them? — Claude Help Center（参照日 2026年9月25日・アーティファクトの種類に「図とフローチャート」の記載。Mermaid の語は確認できず）
- Mermaid Live Editor — Mermaid 公式（参照日 2026年9月25日・公式が案内するオンラインエディタ）
本文の記法・対応状況・バージョンは、2026年9月25日に上記の公式ページから取得した内容です。コード例はすべて各公式ドキュメントに掲載されているものを引用しており、当社で実行環境を構築して測定した値は含まれていません。Mermaid は更新の速いツールのため、実装前に必ず各公式ページで最新の記載を確認してください。
まとめ｜今日やる3つ
- 今日：Mermaid Live Editor か VS Code のプレビューを開き、本記事の2行のフローチャートを貼って描画を確認する。続けて、手元の議事録でプロンプト1を1回だけ試す。
- 今週：チームが図を置いている場所（GitHub の Issue、社内 Wiki、Notion、Obsidian）を1つ選び、
infoか公式記載でバージョンを確認する。そのうえで「この8種類なら全員の環境で描ける」という範囲を決める。 - 今月：更新頻度の高い図を1つ選んで画像から Mermaid へ置き換え、設計変更のプルリクエストで図の差分が読めるかを確かめる。見た目を揃える必要があれば、フロントマターの3キー（テーマ・ルック・レイアウト）を社内テンプレートに書き足す。
図やドキュメントの作成をAIに任せるところまで進めたい方へ
Uravation の資料ダウンロードでは、生成AIを社内業務に組み込むときの進め方をまとめた資料を無料で配布しています。導入設計や社内研修のご相談はお問い合わせフォームからどうぞ。
