マーメイド記法：Mermaid図の書き方とGitHub READMEへの埋め込み

マーメイド記法とは

マーメイド記法（Mermaid）は、短いテキスト記述から図を生成する「diagram-as-code」の記法です。 flowchart（フローチャート）、sequenceDiagram（シーケンス図）、erDiagram（ER図）、 classDiagram（クラス図）、gantt（ガントチャート）などを、同じ記法で書けます。 図がコードなので Pull Request の差分でレビューでき、コードと一緒にバージョン管理できるのが大きな利点です。

基本の書き方

フローチャートは flowchart TD（上から下）で始め、ノードと矢印を並べます。判断は { }（ひし形）で表します：

flowchart TD
  A[開始] --> B{条件?}
  B -->|はい| C[処理]
  B -->|いいえ| A

シーケンス図は sequenceDiagram で始め、participant で登場人物を宣言し、メッセージを1行ずつ書きます。->> が呼び出し、-->> が応答です：

sequenceDiagram
  participant U as ユーザー
  participant S as サーバー
  U->>S: GET /profile
  S-->>U: 200 OK（プロフィール）

さらに詳しくは、シーケンス図ジェネレーターやフローチャート作成ツールに、図タイプ別の構文チートシートと例があります。

GitHub READMEに埋め込む（3ステップ）

1. 01

   図を作成する

   上のエディタでMermaid図を書くか貼り付け、思いどおりに描画されることを確認します。

2. 02

   Markdownブロックをコピー

   書き出しメニューの「Markdown」ボタンで、```mermaid のコードブロックをクリップボードにコピーします。

3. 03

   READMEに貼り付け

   README.md に貼り付けてコミットします。GitHubが ```mermaid のフェンスブロックを自動で図としてレンダリングします（画像ファイルは不要）。

```mermaid のフェンスで囲んだ部分が、GitHub上で図になります：

```mermaid
flowchart TD
  A[開始] --> B{OK?}
  B -->|はい| C[公開]
  B -->|いいえ| A
```

よくある構文エラーと直し方

• フェンスは小文字で正確に ```mermaid。大文字やスペル違いだとコードのまま表示されます。
• インデントはタブではなく半角スペースで統一します（特に mindmap やネスト）。
• 日本語ラベルはそのまま使えますが、( ) や { } などの記号はノード形状の構文と衝突するため、必要なら "…" で囲みます。
• 矢印は ->>（実線・呼び出し）と -->>（破線・応答）を使い分けると、リクエストとレスポンスが明確になります。

まず1つ作ってみますか？ 無料のMermaidエディタを開くと、書いたそばから図になり、Markdownブロックをコピーできます。

よくある質問

マーメイド記法とは何ですか?

マーメイド記法（Mermaid）は、図を「コードとして書く」ための記法です。短いテキストで flowchart（フローチャート）、sequenceDiagram（シーケンス図）、erDiagram（ER図）などを書くと図になり、GitHub・GitLab・Obsidian など多くのツールが標準で表示に対応しています。

GitHubのREADMEでMermaid図は表示されますか?

はい。GitHubは ```mermaid のフェンス付きコードブロックを README.md・Issue・Pull Request・Discussion で自動レンダリングします。テキストを貼り付けるだけで図が描かれ、画像のアップロードは不要です。

Mermaid図がコードのまま表示されるのはなぜ?

フェンスが正確に ```mermaid（小文字）になっているか、構文が有効かを確認してください。まず上のエディタで描画してパースが通ることを確かめ、Markdownブロックをコピーし直すと確実です。

シーケンス図の書き方は?

「sequenceDiagram」で始め、participant で登場人物を宣言し、「A->>B: メッセージ」を1行ずつ書きます。実線の矢印（->>）が呼び出し、破線の矢印（-->>）が応答です。alt/loop で分岐や繰り返しも表せます。

マーメイド記法はどこで覚えられますか?

上のエディタで例を読み込み、編集しながら覚えるのが最短です。先頭の宣言（flowchart / sequenceDiagram / erDiagram など）を変えるだけで図の種類が切り替わります。日本語のラベルもそのまま使えます。