Mermaid（マーメイド）記法とは？

投稿日：

Mermaid（マーメイド）記法を調査しているときの覚書。
Gemini 3 Flash Previewと対話。


１． Mermaid記法の概要

Mermaidは、テキストベースで図を描画するためのJavaScriptライブラリおよびその記法。


Diagrams as Code (DaC)

「図をコードとして扱う」という思想に基づいている。
専用の描画ソフトを使わず、使い慣れたエディタでテキストを書くだけで、フローチャート、シーケンス図、ER図、クラス図などを生成できる。


エンジニアへのメリット

  • Git管理: テキストデータであるため図の変更履歴をGitで管理し、プルリクエストで差分（diff）を確認できる。
  • 自動レイアウト: 線の接続や配置はMermaidが自動で行うため、ユーザーは「構造」の記述に集中できる。
  • 高いポータビリティ: 多くのドキュメントツールやIDEで標準サポートされている。


２． 歴史およびMarddown（マークダウン）記法との関わり

Mermaidは、Markdownエコシステムの中で「図解を担当する標準パーツ」としての地位を確立してきた。


歴史 

2014年にKnut Sveidqvist氏によって公開された。
2019年にJS Open Source Awardsを受賞し、エンジニアの間で「PlantUMLよりも手軽な選択肢」として急速に普及した。


Markdownとの関係

  • シームレスな統合:
    Markdownのコードブロック記法（ ```mermaid ）の中に直接記述できるのが最大の特徴。
  • プラットフォームの採用:
    2022年にGitHubがネイティブサポートを開始したことが決定打となり、GitLab、Notion、Obsidian、Azure DevOpsなど、主要な開発プラットフォームで標準的にレンダリングされるようになった。


Docs as Codeの実現 

「文書（Markdown）」と「図（Mermaid）」を同じテキストファイル内で管理できるようになったことで、ドキュメントのメンテナンス性が飛躍的に向上した。


３． 生成AIとの親和性

Mermaidは、現代の生成AI（ChatGPT, Claude, Gemini等）と極めて相性が良い記法。

  • AIが得意な構造化出力:
    生成AIにとって、ピクセル単位の「画像」を作るのは困難だが、論理的な「テキスト記法」を出力するのは得意分野。
  • 対話的な修正:
    「このフローにエラーハンドリングの分岐を追加して」とAIに指示すれば、AIはMermaidのコードを数行書き換えるだけで図を更新できる。
  • プレビュー機能:
    最近のAIツール（ClaudeのArtifactsなど）は、出力されたMermaidコードをその場で図としてレンダリングして表示する機能を備えており、設計の「言語化」と「視覚化」を同時に行える。


４． Chromeプラグインとコード例

Chrome拡張機能「Markdown Viewer」。
Mermaid記法を有効にするにはオプションで設定する必要あり。


コード例

下記コードを「test.mb」で保存して、Google Chromeにドラッグアンドドロップすれば表示される。

# 主要な図の種類（エンジニアがよく使うもの）

Mermaidで描ける主要な図は、ソフトウェア開発の現場に特化しています。

1.  **Flowcharts (フローチャート):** 業務ロジックや条件分岐の整理。
2.  **Sequence Diagrams (シーケンス図):** APIコールやマイクロサービス間の通信フロー。
3.  **Class Diagrams (クラス図):** オブジェクト指向設計の可視化。
4.  **State Diagrams (状態遷移図):** ステートマシンの設計。
5.  **ER Diagrams (ER図):** データベースのテーブル設計。
6.  **Gantt Charts (ガントチャート):** プロジェクトの進捗管理。


# 認証フロー例

```mermaid
sequenceDiagram
    participant User as ユーザー
    participant App as アプリ
    participant API as 認証サーバー

    User->>App: ログインボタン押下
    App->>API: 認証リクエスト
    API-->>App: トークン発行
    App-->>User: ログイン完了通知
```

# 他のツール（PlantUMLなど）との違い

エンジニアが比較検討する際に役立つポイントです。

| 特徴 | Mermaid | PlantUML |
| :--- | :--- | :--- |
| **実行環境** | JavaScript (ブラウザで完結) | Java (Graphvizのインストールが必要) |
| **導入コスト** | 非常に低い (GitHub等で標準) | 中程度 (環境構築が必要な場合がある) |
| **表現力** | 標準的で美しい | 非常に高度で複雑な図も可能 |
| **Git親和性** | 非常に高い | 高い |


Markdown Viewerのスクリーンショット