Markdown のコードブロックにテキストで図を書く記法(Mermaid・PlantUML・Graphviz など)を、用語の意味・方言ごとの対応状況・各記法の書き方の順にまとめたリファレンスです。

Markdown の方言ごとの拡張記法の一覧は、「方言・拡張記法のまとめ」を参照してください。

Markdownには CommonMark / GFM 以外にも多くの方言・拡張記法があります。GitLab(GLFM)・Pandoc・Markdown Extra・markdown-it・MultiMarkdown・kramdown・Markdo...  続きを読む

しくみ

図表の記法は、どれもコードブロックの言語名で指定します。

```mermaid
graph LR
A --> B
```

対応している環境では、言語名を見て、中身のテキストが図に変換されて表示されます。非対応の環境では、普通のコードブロックとしてテキストのまま表示されます。


用語の整理

言語名に使われている名前は、「図の記述言語」と「データの形式」と「変換サービス」が混ざっています。

図の記述言語

名前(言語名) 描ける図 描画のしくみ
Mermaid(mermaid) フローチャート・シーケンス図・クラス図・ER 図・ガントチャート・円グラフなど ブラウザで JavaScript が描画
PlantUML(plantuml / puml) UML の各種図(シーケンス図・クラス図・ユースケース図など)、ガントチャート、マインドマップ サーバー側で Java が描画
Graphviz(dot / viz / graphviz) ノードと矢印でつないだグラフ(依存関係・状態遷移・組織図など) Graphviz(dot はその配置エンジンの名前、viz はブラウザ版の Viz.js)
Vega / Vega-Lite(vega / vega-lite) 棒グラフ・折れ線グラフ・散布図などのデータのグラフ ブラウザで JavaScript が描画。JSON で書く
D2(d2) 構成図・フローチャートなど。Mermaid より新しい記法 D2 のコマンドで描画
TikZ(tikz) 自由な図形・数学の図 LaTeX で描画(LaTeX の環境が必要)
WaveDrom(wavedrom) デジタル回路のタイミング図 ブラウザで JavaScript が描画。JSON で書く
WebSequenceDiagrams(wsd) シーケンス図 外部の Web サービスで描画

データの形式

名前(言語名) 内容
GeoJSON(geojson) 地図上の点・線・範囲を表す JSON 形式。GitHub では地図として表示される
TopoJSON(topojson) GeoJSON をもとに、データを小さくした地図データの形式
STL(stl) 3D プリンターなどで使われる 3D モデルの形式。GitHub では回転できる 3D モデルとして表示される

変換サービス

名前 内容
Kroki(クロキ) Mermaid・PlantUML・Graphviz・D2・Vega など、20 種類以上の図の記述言語をまとめて画像(SVG・PNG)に変換するサーバー。公開サーバー(kroki.io)のほか、自分のサーバーに設置することもできる

対応状況一覧

○ = 対応、△ = 設定・プラグインなどが必要、- = 非対応

記法 GitHub GitLab MPE Qiita Zenn Obsidian VitePress Starlight
Mermaid ○ ○ ○ ○ ○ ○ △ △
PlantUML - ○ ○ ○ - - - -
Graphviz - △ ○ - - - - -
Vega / Vega-Lite - △ ○ - - - - -
D2 - △ ○ - - - - -
TikZ - △ ○ - - - - -
WaveDrom - △ ○ - - - - -
WebSequenceDiagrams - - ○ - - - - -
GeoJSON / TopoJSON ○ - - - - - - -
STL ○ - - - - - - -
Kroki 経由の図 - △ ○ - - - - -
  • GitLab の △ は、Kroki 経由で対応するものです。自分で運用している GitLab で、管理者が Kroki の連携を有効にした場合に使えます。
  • MPE の PlantUML・D2・TikZ などは、パソコンに Java・D2・LaTeX などのツールのインストールが必要です。
  • VitePress・Starlight の Mermaid は、プラグイン(vitepress-plugin-mermaid など)を追加すると使えます。
  • Pandoc・kramdown・Markdown Extra・MultiMarkdown・markdown-it は、図の記法に対応していません(Pandoc はフィルター、markdown-it はプラグインで追加できます)。

迷ったら Mermaid を使います。Mermaid だけが、ほとんどの方言で共通して使えます。


Mermaid

対応:GitHub・GitLab・MPE・Qiita・Zenn・Obsidian・VitePress(プラグイン)・Starlight(プラグイン)

フローチャート

```mermaid
flowchart LR
A[開始] --> B{条件}
B -->|Yes| C[処理1]
B -->|No| D[処理2]
C --> E[終了]
D --> E
```
  • 1 行目で図の種類と向きを指定します(LR は左から右、TD は上から下)。
  • [ ] は四角、{ } はひし形、( ) は角丸のノードになります。
  • --> で矢印、-->|ラベル| でラベル付きの矢印になります。

シーケンス図

```mermaid
sequenceDiagram
participant ブラウザ
participant サーバー
ブラウザ->>サーバー: リクエスト
サーバー-->>ブラウザ: レスポンス
```

->> は実線の矢印、-->> は点線の矢印(応答)です。

描ける図の種類

1 行目 図の種類
flowchart フローチャート
sequenceDiagram シーケンス図
classDiagram クラス図
stateDiagram-v2 状態遷移図
erDiagram ER 図
gantt ガントチャート
pie 円グラフ
gitGraph Git のブランチ図
mindmap マインドマップ
timeline タイムライン

注意:Mermaid は更新が早く、新しい図の種類が追加され続けています。サービスごとに使っている Mermaid のバージョンが違うため、新しい種類の図は、環境によって表示されないことがあります。Qiita では、1 つのコードブロックあたり 2000 文字までなどの制限もあります。


PlantUML

対応:GitLab・MPE・Qiita

```plantuml
@startuml
actor ユーザー
ユーザー -> システム: ログイン
システム --> ユーザー: 結果
@enduml
```
  • @startuml 〜 @enduml で囲みます。
  • UML の図を細かく書けるのが特徴で、Mermaid より描ける図の種類と設定が多いです。
  • 描画にはサーバー側の Java が必要です。MPE では、Java をインストールするか、PlantUML のサーバーを指定します。
  • MPE では、言語名を puml と書くこともできます。

Graphviz(DOT 言語)

対応:MPE・GitLab(Kroki)

```dot
digraph G {
	rankdir=LR;
	A -> B;
	A -> C;
	B -> D;
	C -> D;
}
```
  • digraph(矢印あり)または graph(矢印なし)で、ノードのつながりを書きます。
  • ノードの配置は、Graphviz が自動で決めます。つながりが多く、配置を自分で考えたくない図に向いています。
  • MPE では、言語名を dot または viz と書きます。GitLab(Kroki)では graphviz と書きます。

Vega / Vega-Lite

対応:MPE・GitLab(Kroki)

```vega-lite
{
	"data": {
		"values": [
			{"月": "1月", "売上": 28},
			{"月": "2月", "売上": 55},
			{"月": "3月", "売上": 43}
		]
	},
	"mark": "bar",
	"encoding": {
		"x": {"field": "月", "type": "nominal"},
		"y": {"field": "売上", "type": "quantitative"}
	}
}
```
  • データとグラフの種類(mark)を JSON で書くと、グラフが表示されます。
  • Vega-Lite は、よく使うグラフを短く書ける簡易版です。Vega は、細かい設定まで書ける完全版です。まずは Vega-Lite を使います。
  • GitLab(Kroki)では、言語名を vegalite と書きます。

D2

対応:MPE・GitLab(Kroki)

```d2
ブラウザ -> サーバー: リクエスト
サーバー -> データベース: クエリ
```
  • -> で矢印、: の後ろにラベルを書きます。
  • Mermaid より新しい記法で、見た目のテーマやレイアウトを細かく変えられます。
  • MPE では、パソコンに D2 のコマンドのインストールが必要です。

TikZ

対応:MPE・GitLab(Kroki)

```tikz
begin{tikzpicture}
draw (0,0) circle (1cm);
draw[->] (0,0) -- (1,1);
end{tikzpicture}
```
  • LaTeX の図を描くためのパッケージで、座標を指定して自由に図形を描けます。数学・物理の図によく使われます。
  • 描画には LaTeX の環境が必要です。MPE では、LaTeX と pdf2svg のインストールが必要です。

WaveDrom

対応:MPE・GitLab(Kroki)

```wavedrom
{ "signal": [
		{ "name": "clk",  "wave": "p......" },
		{ "name": "data", "wave": "x.34.x.", "data": ["A", "B"] }
	]}
```
  • デジタル回路の信号のタイミング図を、JSON で書きます。
  • wave の 1 文字が 1 周期分の信号を表します(p はクロック、x は不定、. は前の状態の継続、数字はデータ)。

WebSequenceDiagrams

対応:MPE

```wsd
ブラウザ->サーバー: リクエスト
サーバー-->ブラウザ: レスポンス
```
  • シーケンス図を描く Web サービスの記法です。
  • 描画は外部のサービスで行われるので、インターネットへの接続が必要です。

GeoJSON / TopoJSON(地図)

対応:GitHub

```geojson
{
	"type": "FeatureCollection",
	"features": [
		{
			"type": "Feature",
			"geometry": { "type": "Point", "coordinates": [139.7671, 35.6812] },
			"properties": { "name": "東京駅" }
		}
	]
}
```
  • 地図上に、点(Point)・線(LineString)・範囲(Polygon)を表示します。
  • 座標は [経度, 緯度] の順で書きます(緯度・経度の順ではないので注意)。
  • 言語名を topojson にすると、TopoJSON 形式で書けます。

STL(3D モデル)

対応:GitHub

```stl
solid triangle
facet normal 0 0 1
outer loop
vertex 0 0 0
vertex 1 0 0
vertex 0 1 0
endloop
endfacet
endsolid
```
  • テキスト形式(ASCII STL)で書いた 3D モデルが、マウスで回転できる形で表示されます。
  • 3 つの頂点(vertex)で三角形の面(facet)を作り、その組み合わせで立体を表します。

Kroki

対応:GitLab(管理者による設定が必要)・MPE

Kroki は図の記述言語ではなく、図の記述言語を画像に変換するサーバーです。Kroki に対応した環境では、Kroki が対応しているすべての言語が使えるようになります。

対応している主な言語
Mermaid・PlantUML・Graphviz・D2・Vega・Vega-Lite・WaveDrom・TikZ・BlockDiag(SeqDiag・ActDiag など)・BPMN・Bytefield・DBML・Ditaa・Excalidraw・Nomnoml・Pikchr・Structurizr・Svgbob など

GitLab:管理者が Kroki の連携を有効にすると、graphviz vegalite wavedrom などの言語名のコードブロックが図として表示されます。

MPE:コードブロックに {kroki=true} を付けると、その図を Kroki で描画します。パソコンにツールをインストールしなくても、PlantUML・D2 などの図を表示できます。

```plantuml {kroki=true}
@startuml
A -> B: こんにちは
@enduml
```

MPE の Kroki は、既定では公開サーバー(kroki.io)に図のテキストを送信します。社外に出せない内容を図にする場合は、自分で設置した Kroki のサーバーを指定します。


使い分けの目安

やりたいこと 記法
どの環境でも表示させたい Mermaid
UML の図を細かく書きたい PlantUML
つながりの多い図を、配置を気にせず書きたい Graphviz
データからグラフを作りたい Vega-Lite
見た目にこだわった構成図を書きたい D2
数学・物理の図を正確に描きたい TikZ
地図・3D モデルを表示したい(GitHub) GeoJSON・STL

Web ページで表示するには(Mermaid)

Markdown から変換した HTML で Mermaid の図を表示するには、ページに Mermaid を読み込みます。

多くのパーサーは、```mermaid のコードブロックを <pre><code class="language-mermaid"> に変換します。Mermaid は class="mermaid" の要素を図に変換するので、読み込み時に置き換えてから描画します。

<script type="module">
	import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';

	// <pre><code class="language-mermaid"> を <div class="mermaid"> に置き換える
				document.querySelectorAll('pre > code.language-mermaid').forEach(function (code) {
					const div = document.createElement('div');
					div.className = 'mermaid';
					div.textContent = code.textContent;
					code.parentElement.replaceWith(div);
				});

				mermaid.initialize({ startOnLoad: false });
				await mermaid.run();
			</script>

textContent で中身を取り出すので、コードの中の &lt; &lsqb; などの文字参照は、元の文字に戻ってから Mermaid に渡されます。


参考リンク

Markdown のコードブロックにテキストで図を書く記法(Mermaid・PlantUML・Graphviz など)を、用語の意味・方言ごとの対応状況・各記法の書き方の順にまとめたリファレンスです。

Markdown の方言ごとの拡張記法の一覧は、「方言・拡張記法のまとめ」を参照してください。

Markdownには CommonMark / GFM 以外にも多くの方言・拡張記法があります。GitLab(GLFM)・Pandoc・Markdown Extra・markdown-it・MultiMarkdown・kramdown・Markdo...  続きを読む

しくみ

図表の記法は、どれもコードブロックの言語名で指定します。

```mermaid
graph LR
A --> B
```

対応している環境では、言語名を見て、中身のテキストが図に変換されて表示されます。非対応の環境では、普通のコードブロックとしてテキストのまま表示されます。


用語の整理

言語名に使われている名前は、「図の記述言語」と「データの形式」と「変換サービス」が混ざっています。

図の記述言語

名前(言語名) 描ける図 描画のしくみ
Mermaid(mermaid) フローチャート・シーケンス図・クラス図・ER 図・ガントチャート・円グラフなど ブラウザで JavaScript が描画
PlantUML(plantuml / puml) UML の各種図(シーケンス図・クラス図・ユースケース図など)、ガントチャート、マインドマップ サーバー側で Java が描画
Graphviz(dot / viz / graphviz) ノードと矢印でつないだグラフ(依存関係・状態遷移・組織図など) Graphviz(dot はその配置エンジンの名前、viz はブラウザ版の Viz.js)
Vega / Vega-Lite(vega / vega-lite) 棒グラフ・折れ線グラフ・散布図などのデータのグラフ ブラウザで JavaScript が描画。JSON で書く
D2(d2) 構成図・フローチャートなど。Mermaid より新しい記法 D2 のコマンドで描画
TikZ(tikz) 自由な図形・数学の図 LaTeX で描画(LaTeX の環境が必要)
WaveDrom(wavedrom) デジタル回路のタイミング図 ブラウザで JavaScript が描画。JSON で書く
WebSequenceDiagrams(wsd) シーケンス図 外部の Web サービスで描画

データの形式

名前(言語名) 内容
GeoJSON(geojson) 地図上の点・線・範囲を表す JSON 形式。GitHub では地図として表示される
TopoJSON(topojson) GeoJSON をもとに、データを小さくした地図データの形式
STL(stl) 3D プリンターなどで使われる 3D モデルの形式。GitHub では回転できる 3D モデルとして表示される

変換サービス

名前 内容
Kroki(クロキ) Mermaid・PlantUML・Graphviz・D2・Vega など、20 種類以上の図の記述言語をまとめて画像(SVG・PNG)に変換するサーバー。公開サーバー(kroki.io)のほか、自分のサーバーに設置することもできる

対応状況一覧

○ = 対応、△ = 設定・プラグインなどが必要、- = 非対応

記法 GitHub GitLab MPE Qiita Zenn Obsidian VitePress Starlight
Mermaid ○ ○ ○ ○ ○ ○ △ △
PlantUML - ○ ○ ○ - - - -
Graphviz - △ ○ - - - - -
Vega / Vega-Lite - △ ○ - - - - -
D2 - △ ○ - - - - -
TikZ - △ ○ - - - - -
WaveDrom - △ ○ - - - - -
WebSequenceDiagrams - - ○ - - - - -
GeoJSON / TopoJSON ○ - - - - - - -
STL ○ - - - - - - -
Kroki 経由の図 - △ ○ - - - - -
  • GitLab の △ は、Kroki 経由で対応するものです。自分で運用している GitLab で、管理者が Kroki の連携を有効にした場合に使えます。
  • MPE の PlantUML・D2・TikZ などは、パソコンに Java・D2・LaTeX などのツールのインストールが必要です。
  • VitePress・Starlight の Mermaid は、プラグイン(vitepress-plugin-mermaid など)を追加すると使えます。
  • Pandoc・kramdown・Markdown Extra・MultiMarkdown・markdown-it は、図の記法に対応していません(Pandoc はフィルター、markdown-it はプラグインで追加できます)。

迷ったら Mermaid を使います。Mermaid だけが、ほとんどの方言で共通して使えます。


Mermaid

対応:GitHub・GitLab・MPE・Qiita・Zenn・Obsidian・VitePress(プラグイン)・Starlight(プラグイン)

フローチャート

```mermaid
flowchart LR
A[開始] --> B{条件}
B -->|Yes| C[処理1]
B -->|No| D[処理2]
C --> E[終了]
D --> E
```
  • 1 行目で図の種類と向きを指定します(LR は左から右、TD は上から下)。
  • [ ] は四角、{ } はひし形、( ) は角丸のノードになります。
  • --> で矢印、-->|ラベル| でラベル付きの矢印になります。

シーケンス図

```mermaid
sequenceDiagram
participant ブラウザ
participant サーバー
ブラウザ->>サーバー: リクエスト
サーバー-->>ブラウザ: レスポンス
```

->> は実線の矢印、-->> は点線の矢印(応答)です。

描ける図の種類

1 行目 図の種類
flowchart フローチャート
sequenceDiagram シーケンス図
classDiagram クラス図
stateDiagram-v2 状態遷移図
erDiagram ER 図
gantt ガントチャート
pie 円グラフ
gitGraph Git のブランチ図
mindmap マインドマップ
timeline タイムライン

注意:Mermaid は更新が早く、新しい図の種類が追加され続けています。サービスごとに使っている Mermaid のバージョンが違うため、新しい種類の図は、環境によって表示されないことがあります。Qiita では、1 つのコードブロックあたり 2000 文字までなどの制限もあります。


PlantUML

対応:GitLab・MPE・Qiita

```plantuml
@startuml
actor ユーザー
ユーザー -> システム: ログイン
システム --> ユーザー: 結果
@enduml
```
  • @startuml 〜 @enduml で囲みます。
  • UML の図を細かく書けるのが特徴で、Mermaid より描ける図の種類と設定が多いです。
  • 描画にはサーバー側の Java が必要です。MPE では、Java をインストールするか、PlantUML のサーバーを指定します。
  • MPE では、言語名を puml と書くこともできます。

Graphviz(DOT 言語)

対応:MPE・GitLab(Kroki)

```dot
digraph G {
	rankdir=LR;
	A -> B;
	A -> C;
	B -> D;
	C -> D;
}
```
  • digraph(矢印あり)または graph(矢印なし)で、ノードのつながりを書きます。
  • ノードの配置は、Graphviz が自動で決めます。つながりが多く、配置を自分で考えたくない図に向いています。
  • MPE では、言語名を dot または viz と書きます。GitLab(Kroki)では graphviz と書きます。

Vega / Vega-Lite

対応:MPE・GitLab(Kroki)

```vega-lite
{
	"data": {
		"values": [
			{"月": "1月", "売上": 28},
			{"月": "2月", "売上": 55},
			{"月": "3月", "売上": 43}
		]
	},
	"mark": "bar",
	"encoding": {
		"x": {"field": "月", "type": "nominal"},
		"y": {"field": "売上", "type": "quantitative"}
	}
}
```
  • データとグラフの種類(mark)を JSON で書くと、グラフが表示されます。
  • Vega-Lite は、よく使うグラフを短く書ける簡易版です。Vega は、細かい設定まで書ける完全版です。まずは Vega-Lite を使います。
  • GitLab(Kroki)では、言語名を vegalite と書きます。

D2

対応:MPE・GitLab(Kroki)

```d2
ブラウザ -> サーバー: リクエスト
サーバー -> データベース: クエリ
```
  • -> で矢印、: の後ろにラベルを書きます。
  • Mermaid より新しい記法で、見た目のテーマやレイアウトを細かく変えられます。
  • MPE では、パソコンに D2 のコマンドのインストールが必要です。

TikZ

対応:MPE・GitLab(Kroki)

```tikz
begin{tikzpicture}
draw (0,0) circle (1cm);
draw[->] (0,0) -- (1,1);
end{tikzpicture}
```
  • LaTeX の図を描くためのパッケージで、座標を指定して自由に図形を描けます。数学・物理の図によく使われます。
  • 描画には LaTeX の環境が必要です。MPE では、LaTeX と pdf2svg のインストールが必要です。

WaveDrom

対応:MPE・GitLab(Kroki)

```wavedrom
{ "signal": [
		{ "name": "clk",  "wave": "p......" },
		{ "name": "data", "wave": "x.34.x.", "data": ["A", "B"] }
	]}
```
  • デジタル回路の信号のタイミング図を、JSON で書きます。
  • wave の 1 文字が 1 周期分の信号を表します(p はクロック、x は不定、. は前の状態の継続、数字はデータ)。

WebSequenceDiagrams

対応:MPE

```wsd
ブラウザ->サーバー: リクエスト
サーバー-->ブラウザ: レスポンス
```
  • シーケンス図を描く Web サービスの記法です。
  • 描画は外部のサービスで行われるので、インターネットへの接続が必要です。

GeoJSON / TopoJSON(地図)

対応:GitHub

```geojson
{
	"type": "FeatureCollection",
	"features": [
		{
			"type": "Feature",
			"geometry": { "type": "Point", "coordinates": [139.7671, 35.6812] },
			"properties": { "name": "東京駅" }
		}
	]
}
```
  • 地図上に、点(Point)・線(LineString)・範囲(Polygon)を表示します。
  • 座標は [経度, 緯度] の順で書きます(緯度・経度の順ではないので注意)。
  • 言語名を topojson にすると、TopoJSON 形式で書けます。

STL(3D モデル)

対応:GitHub

```stl
solid triangle
facet normal 0 0 1
outer loop
vertex 0 0 0
vertex 1 0 0
vertex 0 1 0
endloop
endfacet
endsolid
```
  • テキスト形式(ASCII STL)で書いた 3D モデルが、マウスで回転できる形で表示されます。
  • 3 つの頂点(vertex)で三角形の面(facet)を作り、その組み合わせで立体を表します。

Kroki

対応:GitLab(管理者による設定が必要)・MPE

Kroki は図の記述言語ではなく、図の記述言語を画像に変換するサーバーです。Kroki に対応した環境では、Kroki が対応しているすべての言語が使えるようになります。

対応している主な言語
Mermaid・PlantUML・Graphviz・D2・Vega・Vega-Lite・WaveDrom・TikZ・BlockDiag(SeqDiag・ActDiag など)・BPMN・Bytefield・DBML・Ditaa・Excalidraw・Nomnoml・Pikchr・Structurizr・Svgbob など

GitLab:管理者が Kroki の連携を有効にすると、graphviz vegalite wavedrom などの言語名のコードブロックが図として表示されます。

MPE:コードブロックに {kroki=true} を付けると、その図を Kroki で描画します。パソコンにツールをインストールしなくても、PlantUML・D2 などの図を表示できます。

```plantuml {kroki=true}
@startuml
A -> B: こんにちは
@enduml
```

MPE の Kroki は、既定では公開サーバー(kroki.io)に図のテキストを送信します。社外に出せない内容を図にする場合は、自分で設置した Kroki のサーバーを指定します。


使い分けの目安

やりたいこと 記法
どの環境でも表示させたい Mermaid
UML の図を細かく書きたい PlantUML
つながりの多い図を、配置を気にせず書きたい Graphviz
データからグラフを作りたい Vega-Lite
見た目にこだわった構成図を書きたい D2
数学・物理の図を正確に描きたい TikZ
地図・3D モデルを表示したい(GitHub) GeoJSON・STL

Web ページで表示するには(Mermaid)

Markdown から変換した HTML で Mermaid の図を表示するには、ページに Mermaid を読み込みます。

多くのパーサーは、```mermaid のコードブロックを <pre><code class="language-mermaid"> に変換します。Mermaid は class="mermaid" の要素を図に変換するので、読み込み時に置き換えてから描画します。

<script type="module">
	import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';

	// <pre><code class="language-mermaid"> を <div class="mermaid"> に置き換える
				document.querySelectorAll('pre > code.language-mermaid').forEach(function (code) {
					const div = document.createElement('div');
					div.className = 'mermaid';
					div.textContent = code.textContent;
					code.parentElement.replaceWith(div);
				});

				mermaid.initialize({ startOnLoad: false });
				await mermaid.run();
			</script>

textContent で中身を取り出すので、コードの中の &lt; &lsqb; などの文字参照は、元の文字に戻ってから Mermaid に渡されます。


参考リンク