システム設計やドキュメント作成において、図解は非常に重要な役割を果たします。特に Mermaid は、テキストベースで様々な図を描ける便利なツールとして多くの開発者に愛用されています。

VS Code で Mermaid を使った図作成を効率化したいと思いませんか。適切な拡張機能の選択、ライブプレビューの設定、ショートカットの活用により、図作成の生産性を大幅に向上させることができるんです。

本記事では、初心者の方でもすぐに実践できる VS Code での Mermaid 活用術を、機能別に詳しく解説いたします。

拡張機能の導入と初期設定

VS Code で Mermaid を快適に使用するためには、適切な拡張機能の選択と設定が重要です。ここでは、必要不可欠な拡張機能とその設定方法を詳しく説明いたします。

Mermaid Preview の導入

Mermaid Preview は、VS Code で Mermaid 図をリアルタイムでプレビューできる最も重要な拡張機能です。

以下の手順でインストールを行いましょう。

typescriptCopy code// VS Code の拡張機能検索でインストール
// Extension ID: bierner.markdown-mermaid

拡張機能をインストール後、基本設定を行います。

jsonCopy code// settings.json での基本設定
{
  "markdown.mermaid.theme": "default",
  "markdown.preview.breaks": true,
  "markdown.preview.linkify": true
}

この設定により、Mermaid 図が Markdown プレビュー内で自動的に表示されるようになります。VS Code の設定画面（Ctrl+,）から「mermaid」で検索すると、より詳細な設定も可能です。

Mermaid Syntax Highlighting の設定

コードの読みやすさを向上させるため、Mermaid 専用のシンタックスハイライトを設定しましょう。

typescriptCopy code// Mermaid Syntax Highlight 拡張機能
// Extension ID: bpruitt-goddard.mermaid-markdown-syntax-highlighting

この拡張機能をインストールすると、Mermaid のコードブロックが美しくハイライトされます。

jsonCopy code// language-configuration.json での追加設定
{
  "mermaid.editor.wordWrap": "on",
  "mermaid.editor.minimap.enabled": false,
  "editor.bracketPairColorization.enabled": true
}

シンタックスハイライトにより、Mermaid の構文エラーを視覚的に発見しやすくなり、コーディング効率が格段に向上します。

Mermaid Export 機能の活用

作成した図を様々な形式でエクスポートする機能も重要な要素です。

bashCopy code# Mermaid CLI のグローバルインストール
npm install -g @mermaid-js/mermaid-cli

VS Code の設定で、エクスポート機能を有効化します。

jsonCopy code// エクスポート関連の設定
{
  "mermaid.puppeteerConfigPath": "",
  "mermaid.outputFormat": "svg",
  "mermaid.theme": "default",
  "mermaid.width": 800,
  "mermaid.height": 600
}

これらの設定により、コマンドパレット（Ctrl+Shift+P）から「Mermaid: Export diagram」を実行して、SVG、PNG、PDF 形式でのエクスポートが可能になります。

VS Code で Mermaid を使う際の基本的な環境構築フローは以下のようになります。

mermaidCopy codeflowchart TD
    install_ext[拡張機能インストール] --> config_preview[プレビュー設定]
    config_preview --> config_syntax[シンタックスハイライト設定]
    config_syntax --> config_export[エクスポート機能設定]
    config_export --> ready[環境構築完了]

    install_ext --> |Mermaid Preview| preview_ext[bierner.markdown-mermaid]
    install_ext --> |Syntax Highlighting| syntax_ext[mermaid-syntax-highlighting]
    config_export --> |CLI Tool| mermaid_cli[mermaid-cli インストール]

この図は、VS Code で Mermaid を使うための基本的なセットアップフローを示しています。各ステップを順番に実行することで、快適な Mermaid 開発環境が整います。

ライブプレビュー機能の活用

Mermaid の図作成において、リアルタイムプレビューは作業効率を大幅に向上させる重要な機能です。適切な設定により、図の変更を即座に確認しながら作業を進めることができます。

プレビューペインの表示方法

VS Code でのプレビュー表示には、いくつかの方法があります。最も効率的な方法をご紹介いたします。

typescriptCopy code// コマンドパレットからプレビューを開く
// Ctrl+Shift+P → "Markdown: Open Preview to the Side"

プレビューペインを常に表示したい場合は、以下の設定を行いましょう。

jsonCopy code// プレビューの自動表示設定
{
  "markdown.preview.openMarkdownLinks": "inEditor",
  "markdown.preview.scrollPreviewWithEditor": true,
  "markdown.preview.scrollEditorWithPreview": true,
  "markdown.preview.doubleClickToSwitchToEditor": true
}

これらの設定により、エディタとプレビューが同期してスクロールし、編集箇所がプレビューでも即座に反映されるようになります。

キーボードショートカットでプレビューを開く方法も設定できます。

jsonCopy code// keybindings.json でのショートカット設定
{
  "key": "ctrl+k v",
  "command": "markdown.showPreviewToSide",
  "when": "!notebookEditorFocused && editorLangId == 'markdown'"
}

リアルタイム更新の設定

Mermaid 図のリアルタイム更新を最適化するための設定を行います。

jsonCopy code// 更新間隔とパフォーマンス設定
{
  "markdown.preview.refreshTime": 100,
  "mermaid.preview.updateDelay": 500,
  "files.autoSave": "onFocusChange",
  "editor.formatOnSave": true
}

自動保存機能と組み合わせることで、コードを書いている間も図が自動的に更新され続けます。

デバウンス機能により、連続した編集中に過度な再描画を防ぐことができます。

typescriptCopy code// プレビュー更新の最適化設定
interface PreviewConfig {
  updateDelay: number; // 500ms の遅延
  refreshThrottle: number; // 100ms のスロットリング
  autoRefresh: boolean; // 自動更新有効
}

プレビューレイアウトのカスタマイズ

作業効率を最大化するため、プレビューレイアウトをカスタマイズしましょう。

jsonCopy code// レイアウト設定
{
  "workbench.editor.splitInGroupLayout": "vertical",
  "markdown.preview.fontSize": 14,
  "markdown.preview.lineHeight": 1.6,
  "markdown.preview.fontFamily": "system-ui, sans-serif"
}

分割表示のカスタマイズも重要です。画面サイズに応じて最適な配置を選択しましょう。

mermaidCopy codestateDiagram-v2
    [*] --> SinglePane: 小画面
    [*] --> SplitVertical: 中画面
    [*] --> SplitHorizontal: 大画面

    SinglePane --> TabSwitch: Tab切り替え
    SplitVertical --> RealTime: リアルタイム編集
    SplitHorizontal --> WideView: 大きな図表示

    TabSwitch --> [*]: 編集完了
    RealTime --> [*]: 編集完了
    WideView --> [*]: 編集完了

この図は画面サイズに応じた最適なプレビューレイアウトの選択パターンを示しています。作業環境に合わせて適切なレイアウトを選ぶことで、図作成の効率が大幅に向上します。

プレビューのカスタム CSS 設定により、見た目をさらに調整できます。

cssCopy code/* カスタム CSS でプレビューを装飾 */
.mermaid {
  background: #fafafa;
  border-radius: 8px;
  padding: 16px;
  margin: 16px 0;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

ショートカット設定による効率化

Mermaid での図作成作業を効率化するには、適切なショートカットキーの設定が欠かせません。頻繁に使用するコマンドや操作を素早く実行できる環境を構築しましょう。

基本ショートカットの設定

VS Code でよく使用する Mermaid 関連のショートカットを設定いたします。

jsonCopy code// keybindings.json での基本ショートカット設定
[
  {
    "key": "ctrl+shift+m",
    "command": "markdown.showPreviewToSide",
    "when": "editorLangId == 'markdown'"
  },
  {
    "key": "ctrl+alt+m",
    "command": "mermaid.preview.zoomIn",
    "when": "mermaidPreviewFocus"
  },
  {
    "key": "ctrl+alt+n",
    "command": "mermaid.preview.zoomOut",
    "when": "mermaidPreviewFocus"
  }
]

よく使用される図作成コマンドのショートカットも設定しましょう。

jsonCopy code// 図作成関連のショートカット
[
  {
    "key": "ctrl+shift+f",
    "command": "mermaid.insertFlowchart",
    "when": "editorTextFocus && editorLangId == 'markdown'"
  },
  {
    "key": "ctrl+shift+s",
    "command": "mermaid.insertSequenceDiagram",
    "when": "editorTextFocus && editorLangId == 'markdown'"
  },
  {
    "key": "ctrl+shift+g",
    "command": "mermaid.insertGanttChart",
    "when": "editorTextFocus && editorLangId == 'markdown'"
  }
]

これらのショートカットにより、図の種類を素早く選択して挿入することができるようになります。

カスタムコマンドの作成

VS Code のタスク機能を使用して、独自の Mermaid コマンドを作成できます。

jsonCopy code// tasks.json でのカスタムタスク設定
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Mermaid Export SVG",
      "type": "shell",
      "command": "mmdc",
      "args": [
        "-i",
        "${file}",
        "-o",
        "${fileDirname}/${fileBasenameNoExtension}.svg",
        "-t",
        "default"
      ],
      "group": "build",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared"
      }
    }
  ]
}

カスタムコマンドをショートカットキーに割り当てることも可能です。

jsonCopy code// カスタムタスクのショートカット設定
{
  "key": "ctrl+alt+e",
  "command": "workbench.action.tasks.runTask",
  "args": "Mermaid Export SVG",
  "when": "editorTextFocus"
}

スニペット機能の活用

よく使用する Mermaid のテンプレートをスニペットとして登録することで、作業効率を大幅に向上させることができます。

jsonCopy code// markdown.json でのスニペット設定
{
  "Mermaid Flowchart": {
    "prefix": "mermaid-flow",
    "body": [
      "```mermaid",
      "flowchart TD",
      "    A[${1:Start}] --> B{${2:Decision}}",
      "    B -->|${3:Yes}| C[${4:Process 1}]",
      "    B -->|${5:No}| D[${6:Process 2}]",
      "    C --> E[${7:End}]",
      "    D --> E",
      "```"
    ],
    "description": "Insert Mermaid flowchart template"
  }
}

シーケンス図用のスニペットも作成しましょう。

jsonCopy code// シーケンス図スニペット
{
  "Mermaid Sequence": {
    "prefix": "mermaid-seq",
    "body": [
      "```mermaid",
      "sequenceDiagram",
      "    participant ${1:Actor1}",
      "    participant ${2:Actor2}",
      "    ${1:Actor1}->>+${2:Actor2}: ${3:Message 1}",
      "    ${2:Actor2}-->>-${1:Actor1}: ${4:Response 1}",
      "```"
    ],
    "description": "Insert Mermaid sequence diagram template"
  }
}

ER 図やガントチャートのスニペットも同様に作成できます。

jsonCopy code// ER図とガントチャートのスニペット
{
  "Mermaid ER Diagram": {
    "prefix": "mermaid-er",
    "body": [
      "```mermaid",
      "erDiagram",
      "    ${1:Entity1} ||--o{ ${2:Entity2} : has",
      "    ${1:Entity1} {",
      "        string ${3:id} PK",
      "        string ${4:name}",
      "    }",
      "```"
    ]
  }
}

効率的な Mermaid 作業フローは以下のような構成になります。

mermaidCopy codeflowchart LR
    shortcut[ショートカット] --> preview[プレビュー表示]
    shortcut --> template[テンプレート挿入]
    template --> snippet[スニペット使用]
    snippet --> edit[図編集]
    edit --> export[エクスポート]
    preview --> realtime[リアルタイム確認]
    realtime --> edit
    export --> share[共有・保存]

この図では、ショートカットキーからスニペット活用、リアルタイム編集、エクスポートまでの効率的な作業フローを表現しています。各段階でのショートカット活用により、図作成の時間を大幅に短縮できます。

実際の開発ワークフローでの活用

Mermaid を実際の開発プロジェクトで活用する際の実践的なワークフローとベストプラクティスをご紹介いたします。

Markdown と Mermaid の組み合わせ

開発ドキュメントでは、Markdown と Mermaid を効果的に組み合わせることが重要です。

markdownCopy code# システム設計書

# アーキテクチャ概要

本システムは以下の構成で動作します。

```mermaid
flowchart TD
    Client[クライアント] --> API[Web API]
    API --> Auth[認証サービス]
    API --> DB[(データベース)]
    Auth --> DB
```

# データフロー

ユーザーリクエストの処理フローは以下の通りです。

コードコメント内でも Mermaid を活用できます。

typescriptCopy code/**
 * ユーザー認証処理
 *
 * フロー:
 * ```mermaid
 * sequenceDiagram
 *     Client->>+API: ログイン要求
 *     API->>+Auth: 認証確認
 *     Auth-->>-API: 認証結果
 *     API-->>-Client: トークン返却
 * ```
 */
class AuthService {
  async login(
    credentials: LoginCredentials
  ): Promise<Token> {
    // 認証処理の実装
  }
}

図の管理とバージョン管理

プロジェクトが大きくなると、図の管理も重要になります。適切なファイル構成を心がけましょう。

bashCopy code# 推奨ファイル構成
docs/
├── architecture/
│   ├── system-overview.md
│   ├── api-design.md
│   └── database-schema.md
├── diagrams/
│   ├── flowcharts/
│   ├── sequences/
│   └── er-diagrams/
└── assets/
    └── images/
        └── exported-diagrams/

Git でのバージョン管理では、図の変更履歴も追跡しやすくなります。

jsonCopy code// .gitattributes での Mermaid ファイル設定
*.md linguist-detectable=true
*.mmd linguist-language=Mermaid

図の変更管理のためのコミットメッセージ規則も設定しましょう。

bashCopy code# 図変更時のコミットメッセージ例
feat(docs): Add user registration flow diagram
fix(docs): Update API sequence diagram for error handling
docs(arch): Revise system architecture diagram

チーム開発での図共有

チーム全体で一貫した図作成を行うため、スタイルガイドを策定します。

jsonCopy code// .vscode/settings.json でのチーム共有設定
{
  "mermaid.theme": "default",
  "mermaid.flowchart.curve": "basis",
  "mermaid.sequence.messageAlign": "center",
  "markdown-mermaid.lightModeTheme": "default",
  "markdown-mermaid.darkModeTheme": "dark"
}

チーム内での図スタイル統一のための設定テンプレートを作成します。

mermaidCopy code%%{init: {
  'theme': 'default',
  'themeVariables': {
    'primaryColor': '#ff6b6b',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#ff4757',
    'lineColor': '#5f27cd',
    'secondaryColor': '#00d2d3',
    'tertiaryColor': '#ffffff'
  }
}}%%
flowchart TD
    A[開始] --> B{条件分岐}
    B -->|Yes| C[処理A]
    B -->|No| D[処理B]

レビュープロセスでも図の品質を担保します。

markdownCopy code# プルリクエストテンプレート

# 図表の変更について

- [ ] 図の目的が明確である
- [ ] チームスタイルガイドに準拠している
- [ ] 図のエクスポート版も更新済み
- [ ] 図表のキャプションが適切である

チーム開発における Mermaid 活用の全体フローは以下のようになります。

mermaidCopy codesequenceDiagram
    participant Dev as 開発者
    participant Review as レビュアー
    participant Repo as リポジトリ
    participant Team as チーム

    Dev->>+Repo: 図を含む機能実装
    Repo->>+Review: プルリクエスト作成
    Review->>Review: 図の品質チェック
    Review->>+Team: チームレビュー依頼
    Team-->>-Review: フィードバック
    Review-->>-Repo: 承認・マージ
    Repo-->>-Dev: 機能リリース

この図では、開発者が図を作成してから、チーム全体でレビューを行い、品質を担保してリリースするまでの一連の流れを表現しています。各段階でのコミュニケーションが重要なポイントです。

トラブルシューティングと最適化

VS Code で Mermaid を使用する際によく発生する問題とその解決方法、パフォーマンス最適化のテクニックをご紹介いたします。

よくあるエラーとその解決方法

Mermaid の描画でよく発生するエラーパターンを整理します。

エラーの種類	症状	解決方法
構文エラー	図が表示されない	コードの構文を確認する
プレビューエラー	白い画面が表示される	拡張機能を再起動する
エクスポートエラー	ファイル出力に失敗する	CLI ツールの再インストール
日本語文字化け	日本語が正しく表示されない	フォント設定を確認する
パフォーマンス問題	プレビューが重い	更新間隔を調整する

構文エラーの代表的なパターンと修正方法をご紹介します。

javascriptCopy code// ❌ よくある間違い
flowchart TD
    A[Start] --> B[Process) // 括弧が不一致
    B --> C{Decision
    C --> D[End]

// ✅ 正しい記述
flowchart TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C --> D[End]

予約語の使用による問題も頻発します。

javascriptCopy code// ❌ 予約語を使用した場合
flowchart TD
    end --> process  // 'end' は予約語

// ✅ 正しい記述
flowchart TD
    finish --> process_step

パフォーマンスの最適化

大きな図や複雑な図でのパフォーマンス問題を解決するための設定を行います。

jsonCopy code// パフォーマンス最適化設定
{
  "mermaid.preview.updateDelay": 1000,
  "markdown.preview.refreshTime": 500,
  "mermaid.maxTextSize": 50000,
  "mermaid.maxEdges": 500,
  "editor.quickSuggestions": {
    "other": false,
    "comments": false,
    "strings": false
  }
}

メモリ使用量の最適化も重要です。

typescriptCopy code// 大きな図を分割する例
// ❌ 一つの巨大な図
flowchart TD
    A --> B --> C --> D --> E --> F --> G --> H --> I --> J

// ✅ 複数の小さな図に分割
// 図1: メインフロー
flowchart TD
    A[開始] --> B[前処理]
    B --> C[メイン処理]

// 図2: メイン処理詳細
flowchart TD
    C1[入力検証] --> C2[データ変換]
    C2 --> C3[結果出力]

メモリ使用量の監視と制御

VS Code のパフォーマンスモニターで Mermaid 拡張機能のリソース使用量を監視できます。

bashCopy code# VS Code プロセスのメモリ使用量確認
# コマンドパレット: "Developer: Reload Window With Extensions Disabled"
# で拡張機能なしでの動作確認

設定でのメモリ制御も可能です。

jsonCopy code// メモリ使用量制御設定
{
  "mermaid.preview.maxMemoryUsage": "512MB",
  "mermaid.preview.memoryMonitoring": true,
  "extensions.autoUpdate": false,
  "window.zoomLevel": 0
}

エラー対応のフローチャートを以下に示します。

mermaidCopy codeflowchart TD
    error[エラー発生] --> check_syntax{構文チェック}
    check_syntax -->|OK| check_extension{拡張機能確認}
    check_syntax -->|NG| fix_syntax[構文修正]

    check_extension -->|OK| check_memory{メモリ確認}
    check_extension -->|NG| reload_extension[拡張機能再起動]

    check_memory -->|OK| check_size{図のサイズ確認}
    check_memory -->|NG| optimize_memory[メモリ最適化]

    check_size -->|OK| solved[問題解決]
    check_size -->|NG| split_diagram[図の分割]

    fix_syntax --> solved
    reload_extension --> solved
    optimize_memory --> solved
    split_diagram --> solved

この図では、Mermaid でエラーが発生した際の系統的な対処方法を表現しています。各段階での確認項目を順番に実行することで、効率的に問題を解決できます。

まとめ

VS Code での Mermaid 活用について、拡張機能の選択からトラブルシューティングまで包括的にご紹介いたしました。適切な環境構築により、図作成の生産性を大幅に向上させることができます。

特に重要なポイントは以下の通りです。必須拡張機能の導入とライブプレビュー環境の構築により、リアルタイムでの図作成が可能になります。ショートカットキーとスニペット機能を活用することで、作業効率を最大化できるでしょう。

チーム開発では、図のスタイルガイド策定とレビュープロセスの確立が成功の鍵となります。また、パフォーマンス最適化とエラー対処法を理解しておくことで、安定した開発環境を維持できるはずです。

これらのテクニックを実践することで、VS Code での Mermaid 図作成が格段に快適になり、ドキュメント品質の向上と開発効率の改善を実現できるでしょう。

関連リンク

• Mermaid 公式ドキュメント
• VS Code Mermaid Preview 拡張機能
• Mermaid CLI ツール
• VS Code カスタマイズガイド