Mermaid図解文法：MarkdownおよびObsidian完全ガイドと実例

Mermaid図解とは、Mermaid JSライブラリを使用してプレーンテキストのコードから自動生成される視覚的ダイアグラムのことです。2014年頃にKnut Sveidqvist氏によって開始されたこのMermaidオープンソースプロジェクトは、ソフトウェアドキュメントにおけるテキストベース作図の標準へと成長しました。2026年現在、GitHub、GitLab、および主要なドキュメント作成ツールがMermaid構文のネイティブ描画に対応しています。

本ガイドでは、Mermaidの構文、主要な図解タイプ、MarkdownやObsidianでの描画方法、エクスポートの選択肢、ならびに一般的なエラーの解決法を解説します。

基本構文の例は以下の通りです。

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

「Diagrams as Code（コードとしての図解）」というアプローチは、バージョン管理を通じた保守性の向上を実現し、エンジニアリングチーム全体のコラボレーションを簡素化します。以降のセクションでは、代表的な図解タイプ、ステップバイステップの作成手順、および静止画を必要とするステークホルダー向けのエクスポート方法について説明します。

Mermaid構文クイックリファレンス（チートシート）

図解タイプ	開始キーワード	主な用途
フローチャート	flowchart TD または flowchart LR	プロセスや意思決定のフロー
シーケンス図	sequenceDiagram	リクエスト／レスポンスやサービス間の相互作用
ER図（実体関連図）	erDiagram	データベースのエンティティとリレーション
状態遷移図	stateDiagram-v2	ステータスやライフサイクルの遷移
ガントチャート	gantt	マイルストーンやスケジュール管理
クラス図	classDiagram	ドメインモデルやオブジェクトモデル設計

すべてのMermaidブロックには、開始キーワードが1つ必要です。ノードIDは簡潔で安定した文字列にし、表示ラベルには読みやすい長文テキストを含めることができます。

Mermaid図解とは？なぜ使うべきなのか？

Mermaid図解は、Mermaid JavaScriptライブラリによって解釈される軽量なテキスト構文から生成されます。ドラッグ＆ドロップのGUIを使用する代わりに、Mermaidコードを記述すると、ライブラリがそれをSVGグラフィックに変換します。

Mermaidコードがビジュアルに変換される仕組み：

• graph TD; A –> B; は上から下へのフローチャートとして描画されます

• sequenceDiagramブロックはメッセージのやり取りを示すシーケンス図になります

• erDiagramの定義はデータベースのER図を生成します

テキスト作図の主なメリット：

• 誰でも編集可能な人間が読みやすいプレーンテキスト

• 変更点が正確に把握できるGitフレンドリーな差分（diff）

• プルリクエストでのコードレビューが容易

• 管理すべき独自形式の図解ファイルが不要

2026年における具体的な活用事例：

• シーケンス図によるマイクロサービスの認証フローのドキュメント化

• コミットから本番デプロイまでのCI/CDパイ프ラインの可視化

• ガントチャートを用いた2026年第2四半期の製品ローンチマイルストーンの計画

Mermaid図解は、Markdownベースのドキュメント、内部Wiki、開発者ポータルと自然に統合され、組織全体のドキュメント管理を効率化します。

主要なMermaid図解タイプ

Mermaidは多彩な図解タイプをサポートしています。本セクションでは網羅的なリファレンスではなく、実用性の高い主要タイプを紹介します。

代表的な図解タイプ：

タイプ	キーワード	最適な用途
フローチャート	graph TD / flowchart LR	業務フロー、意思決定ツリー
シーケンス図	sequenceDiagram	API呼び出し、サービス間連携
クラス図	classDiagram	オブジェクトモデル、ドメイン設計
状態遷移図	stateDiagram-v2	ライフサイクル状態、ワークフロー
ER図（実体関連図）	erDiagram	データベーススキーマ設計
ユーザー旅程図（User Journey)	journey	顧客体験マッピング
ガントチャート	gantt	プロジェクト工程表、ロードマップ
パイチャート（円グラフ）	pie	割合データの可視化
Gitグラフ	gitGraph	ブランチ戦略の図式化

実際の活用例：

• フロントエンド → API Gateway → 決済サービスAPIのシーケンス図

• 依存関係を含む2026年Q2機能ロードマップのガントチャート

• 注文ライフサイクルの状態遷移図：保留中 → 支払済 → 発送済 → 配達完了

フローチャート、シーケンス図、ER図、状態遷移図は、ソフトウェア開発チームで最も一般的に使用されます。プロダクトや運用チームは、顧客体験やビジネスプロセスのためにユーザー旅程図、ガントチャート、円グラフを好む傾向があります。

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

Mermaid図解の作成方法

フローチャートを迅速に作成するには、基本構造を理解することから始まります。テキストエディタとMermaid構文があれば、誰でも作成可能です。

ステップ・バイ・ステップ手順：

1. 図解のキーワード（graph TD, sequenceDiagram, ganttなど）から始めます

2. IDとラベルを使用してノードや参加者を定義します

3. 矢印やリレーション線で要素同士を接続します

4. 必要に応じてラベルやグループ化（subgraph）を追加します

以下は、実際に動作するログインプロセスのフローチャート例です：

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

矢印の種類とラベル：

• –> は標準的な有向矢印を作成します

• –>|label| は接続線に条件テキストを追加します

• — は矢印のない直線を描画します

• -.-> は間接的な関係を示す点線矢印を生成します

MermaidはELKレイアウトアルゴリズムを使用してノードを自動配置します。手動での位置調整ではなく、論理構造と命名に集中しましょう。配置のために余分なコードを書く必要はありません。

2026年にMermaid図解を利用できる環境

多くの主要プラットフォームがMermaidをネイティブサポート、または拡張機能経由でサポートしており、すぐに作成を始めることができます。

主な利用環境：

• GitHub & GitLab: README.md、ドキュメント、Issue、Wikiでのネイティブ表示

• 静的サイトジェネレーター: 拡張機能を備えたDocusaurus、MkDocs、Sphinx

• 内部開発者ポータル: BackstageやカスタムReactアプリ

• ノートアプリ: Mermaidチャート表示を標準サポートするNotionおよびObsidian

Visual Studio CodeやJetBrains IDEは拡張機能を通じたライブプレビューに対応しており、入力しながら即座に視覚化できます。これによりコミット前に構文エラーを検知できます。

Confluence Cloudなどの一部のプラットフォームではアドオンが必要です。チームによっては図解のソースコードをGitリポジトリで管理し、閲覧用にエクスポートした画像を併置する運用が一般的です。

さまざまなプラットフォームでのMermaid描画

描画（レンダリング）処理によって、MermaidテキストがSVG/HTMLのビジュアルに変換されます。

共通パターン：mermaid言語識別子を指定したコードブロック内にMermaidコードを記述します。GitHub、GitLab、ドキュメント生成ツールは、ブラウザ閲覧時にこれらを自動的にビジュアル描画します。

ローカル開発では、拡張機能やプラグインがリアルタイムプレビューを提供します。Sphinxベースのドキュメントでは、ビルド時に図解を生成するsphinxcontrib-mermaidなどの拡張機能を有効化します。

MarkdownファイルでのMermaid描画

Markdown内でMermaidを描画するには：

1. バックティック3つでコードブロックを開きます

2. 言語識別子に mermaid を指定します

3. 内部に図解定義を記述します

4. バックティック3つで閉じます

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• GitHub、GitLab、現代のドキュメントサイトはこのパターンを直接サポートしています

• 本番環境にマージする前に、プレビュー環境で描画を確認してください

• Mermaidのデフォルトテーマは、大半の技術ドキュメントによく馴染みます

ObsidianでのMermaid描画

Obsidianは、閲覧モード（Reading View）およびライブプレビュー（Live Preview）の両方で mermaid コードブロックをネイティブ描画します。Mermaidサポートが標準組み込みされているため、基本的な作図にコミュニティプラグインは不要です。

図解が描画されない場合：

1. 開始コードブロックが正確に ```mermaid であるか確認します。
2. 1行目に flowchart LR などの有効なキーワードがあるか確認します。
3. 記号を含むラベルはダブルクォーテーションで囲みます（例：A["Review: blocked?"]）。
4. ノードを2つまで減らし、エラーの原因となる構文が特定できるまで1行ずつ戻していきます。
5. お使いのObsidianのバージョンが、コピーした新しいMermaid構文に対応しているか確認します。

Obsidian固有のテキスト装飾については、Obsidian基本フォーマット設定チートシートを参照してください。

IDEやローカルツールでのMermaid描画

VS CodeのMermaidプラグインを使用すると、編集しながら横画面でリアルタイムプレビューを確認できます。構文ハイライトやエラー修正提案機能を備えた拡張機能も存在します。

JetBrains IDEもプラグイン経由で同等の機能を提供しており、エラーヒントやエクスポート機能を備えています。自動修復ボタンで一般的な文法ミスを一括修正できるツールもあります。

ローカルプレビューを活用することで、Gitリポジトリへ押し込む前にミスを防げます。開発手順書でおすすめの拡張機能セットを標準化しておきましょう。

Mermaid図解のエクスポートと共有

コードベースの編集は開発者にとって効率的ですが、ステークホルダーはMicrosoft PowerPointプレゼンテーションや報告書用に静止画像を好むことがよくあります。

一般的なエクスポート形式：

• PNG: チャットツール等での迅速な共有

• SVG: スライド用の高品質なベクター画像

• PDF: 印刷可能なドキュメントパッケージ

エクスポートの手順はツールにより異なります。組み込みのエクスポートボタンを持つものもあれば、Mermaid ChartエディタやMermaid Live Editorなどのオンラインツールを使用するものもあります。CLIツールを用いれば、CI/CDの一環として複数の図解ファイルから画像を一括生成できます。

図解を後から再編集できるよう、エクスポートした画像と一緒に元のMermaidソースコードを必ず保存しておきましょう。

Mermaid図解の画像フォーマット変換

オンラインエディタを使用した手順：

1. ブラウザでMermaid Live Editorを開きます

2. Mermaidコードを貼り付けるか、サンプルを使用します

3. スタイル設定を調整します

4. 必要に応じてテーマを選択します（ダークモード／ライトモードに対応）

5. 「Download SVG」または「Download PNG」をクリックします

エクスポートした図解がブランドガイドラインに沿ったフォントや色を使用しているか確認してください。GitHubのスクリーンショットはビットマップ化して拡大時にぼやける可能性があるため、スライド資料には可能な限りSVGエクスポートを使用してください。

Mermaid図解のベストプラクティスと限界

Mermaidは強力ですが、適切なスコープと構造を意識して運用することが重要です。

推奨事項：

• 1つの図解には1つの明確なテーマのみを扱います

• 分かりやすいノードラベルと統一された命名規則を使用します

• 関連する手順はサブグラフ（subgraph）ブロックでグループ化します

• 複雑なシステムは1つの巨大な図にするのではなく、複数のファイルに分割します

考慮すべき限界点：

• 巨大で密度の高いシステムをコードだけで管理するのは困難です

• レイアウト調整は大まかなものであり、ピクセル単位の精密な配置はできません

• 従来の専用描画ツールやホワイトボードツールほど装飾の自由度は高くありません

• 概念的なビジュアルデザインやUIモックアップには向いていません

アーキテクチャの概要やワークフローにはMermaidを活用し、ピクセル単位の精密なレイアウトや複雑なネットワーク構成図が必要な場合は専用ツールに切り替えましょう。

Mermaid図解をすばやく始めるために

新規ユーザー向けアクションリスト：

1. 図解タイプを1つ選択します（まずは簡単なフローチャートがおすすめ）

2. ビジュアルエディタやAI補助機能のある拡張機能を導入するか、Mermaid Live Editorを開きます

3. 現在のプロジェクトの実際のプロセス（2026年のデプロイパイプラインなど）を描いてみます

4. 構文パターンを学びながら、徐々に表現を広げていきます

主なリソース：

• 構文リファレンスが網羅されたMermaid公式ドキュメント

• AI生成機能を試せるMermaid Live Editor

• コードスニペットを提供するVS Code拡張機能

• チーム機能を利用するための各種コラボレーションツール

開発用ハンドブックに、命名規則、推奨図解タイプ、権限設定などを定めた「図解ガイドライン」セクションを設けましょう。自然言語での説明とAIツールを組み合わせることで、技術的な熟練度に関わらず誰でも迅速に図解を作成できるようになります。

Mermaid図解を採用することで、ドキュメント作成をソースコードと同じレビュー・自動化プロセスに乗せることができます。機械学習パイプラインをドキュメント化するエンジニアであれ、ワークフローをマッピングするプロジェクト管理者であれ、Mermaidはチームにバージョン管理された視覚資料をもたらします。今日から最初の1図を作成してみましょう。