MarkdownとGitHubドキュメントでMermaid図を使う

MarkdownドキュメントでのMermaid

Mermaidの最大の強みの一つは、人気のあるプラットフォームでのネイティブサポートです。ビルドツール、プラグイン、画像生成なしで、Markdownファイルに直接ダイアグラムを埋め込めます。

GitHubのネイティブサポート

GitHubは以下の場所でMermaidダイアグラムを自動的にレンダリングします：

• README.mdやその他のMarkdownファイル
• IssueとPull Request
• Wikiページ
• Discussions

mermaid言語識別子を持つフェンスドコードブロックを使用するだけです：

```mermaid
flowchart LR
    A[Push code] --> B[CI runs]
    B --> C{Tests pass?}
    C -->|Yes| D[Deploy]
    C -->|No| E[Fix & retry]
```

GitLabのサポート

GitLabもMarkdownでMermaidをネイティブサポートしています。構文はGitHubと同じで、```mermaid``フェンスドコードブロックを使用します。

ドキュメントツール

多くのドキュメントフレームワークがMermaidをサポートしています：

ツール	サポート
Docusaurus	@docusaurus/theme-mermaidで組み込み
MkDocs	mkdocs-mermaid2-plugin経由
VitePress	vitepress-plugin-mermaid経由
Notion	コードブロックでネイティブサポート
Obsidian	組み込みレンダリング

フォールバック戦略

Mermaidをネイティブサポートしていないプラットフォームの場合：

1. SVGに事前レンダリング — Mermaid CLI（mmdc）を使ってSVGファイルを生成し、画像として埋め込みます。
2. ライブエディタリンクを使用 — mermaid.liveへのリンクにダイアグラムコードをURLエンコードして貼り付けます。
3. GitHub Action — mermaid-js/mermaid-cli-actionなどのアクションでプッシュ時にSVG生成を自動化します。

# Mermaid CLIで事前レンダリング
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

ドキュメントのベストプラクティス

1. ダイアグラムを小さく保つ — 5〜15ノードを目安にしましょう。大きなダイアグラムは複数の焦点を絞ったものに分割します。
2. 代替テキストを追加する — アクセシビリティのために、HTMLの<details>タグでダイアグラムをラップし、テキスト説明を追加します。
3. バージョン管理 — Mermaidダイアグラムはプレーンテキストなので、Pull Requestできれいにdiffが取れます。
4. コンテキストを提供する — ダイアグラムの上に、それが何を示しているかを説明する1〜2文を必ず追加しましょう。