システム設計書や仕様書、Qiita・Zennなどの技術ブログを書く際、「ここにちょっとしたフローチャートやシーケンス図を入れたいな」と思うことはありませんか？
しかし、専用の画像編集ソフトや作図ツールを立ち上げて図を描き、それを画像として書き出してMarkdownに貼り付ける……という作業は非常に面倒で、修正の手間もかかります。
そこでおすすめなのが、テキストから図を自動生成できるツール「Mermaid（マーメイド）」です。使い慣れたVSCode（Visual Studio Code）を少しカスタマイズするだけで、Markdownファイルの中にテキストを書くだけで美しい図をその場でレンダリングし、リアルタイムに確認・管理できる最強の作図環境が手に入ります。
本記事では、VSCodeでMermaid図を作成するための準備から、実際の作図手順、実務でよく使う図のサンプルコード、さらにGit管理との相性の良さまで徹底的に解説します！
Mermaidとは？
まずは、Mermaidがどのようなツールなのか、概要をサクッと押さえておきましょう。
Mermaidとは何か
Mermaid（マーメイド）は、「テキストコードからフローチャートやシーケンス図などの図表を自動で描画（レンダリング）できる」JavaScriptベースのツールです。
最大の特徴は、Markdownとの相性が抜群に良いこと。Markdown内に特定の記法でテキストを記述するだけで、ブラウザやエディタのプレビュー画面が自動的に見やすい図へと変換してくれます。
Mermaidで作成できる図
Mermaidを使えば、開発現場で必要となる大半の図表をテキストだけで作成できます。
- フローチャート: 業務フローや条件分岐、アルゴリズムの可視化
- シーケンス図: 処理の実行順序やオブジェクト間のやり取り
- ER図: データベースのテーブル設計やリレーション（関係性）
- ガントチャート: プロジェクトのスケジュール管理
- クラス図: オブジェクト指向のクラス構造と関係性
これらすべてを、マウス操作なしの「キーボードタイピングだけ」で完結させられます。
VSCodeでMermaidを使う準備
それでは、VSCodeを使ってMermaidを描くための具体的な準備ステップを進めましょう。
Markdownファイルを作成する
まずはずを埋め込むためのMarkdownファイルを用意します。
- VSCodeを開き、新しいファイルを作成します。
- ファイル名をdesign.mdのように、必ず末尾に.mdという拡張子をつけて保存してください。
Mermaid対応のプレビュー環境を確認する
現在のVSCodeは標準機能の「Markdownプレビュー」だけでも基本的なMermaidの描画に対応しています。ファイルを作成したら、Cmd + K → V （Windowsは Ctrl + K → V ）を押して、右側にプレビュー画面を立ち上げておきましょう。
必要に応じて拡張機能を導入する
標準機能でも図を見ることはできますが、実務でゴリゴリ図を描くなら、より多機能な拡張機能（プラグイン）の導入を強く推奨します。
おすすめは以下の2つです。VSCodeの拡張機能マーク（四角いアイコン）から検索してインストールしてください。
- Markdown Preview Enhanced
標準のプレビューより描画スピードが早く、Mermaidの最新文法にも追従しています。背景テーマの変更や、図をPDF/PNG/SVG形式でエクスポートする機能が非常に強力です。 - Mermaid Markdown Syntax Highlighting
Mermaidのコード内に「色」をつけて見やすくしてくれる（シンタックスハイライト）拡張機能です。タイピング時の構文ミスを劇的に減らすことができます。
VSCodeでMermaid図を作成する方法
準備が整ったら、実際にメインコンテンツである作図に挑戦してみましょう。最初は最もシンプルなフローチャート（上から下へ流れる図）を例にします。
Mermaidコードを書く
Markdwonファイル（左側の画面）に、以下のように記述してください。Mermaidを書くときは、バッククォート３つ（“`）の後にMermaidと宣言するのがルールです。
```mermaid
graph TD
A[スタート] --> B{条件分岐}
B -- Yes --> C[処理1]
B -- No --> D[処理2]プレビューで確認する
コードを入力した瞬間、右側のプレビュー画面（Markdown Preview Enhancedなど）に、カチッとした美しいフローチャートが自動で描画されます。
図を修正する
修正もテキストを書き換えるだけです。例えば、C[処理]の部分をC[成功画面へ移動]に変更すれば、右側の図の中のテキストも完全リアルタイムで書き換わります。
画像を別ソフトで作り直して、エクスポートして、差し替えて……というあの不毛な作業がすべて過去のものになります。
よく使うMermaid図の例
開発ドキュメントや仕様書で頻出する、主要な3つの図のサンプルコードと書き方のポイントを紹介します。
フローチャート（Flowchart）
業務ルールやプログラムの処理ロジックを可視化するのに最適です。grath TD（Top to Bottom：上から下）のほか、grath LR（Left to Right：左から右）もよく使われます。
【入力するテキスト】
```mermaid
graph LR
User([ユーザー]) --> Login[ログイン画面]
Login --> Auth{認証確認}
Auth -->|成功| Dash[ダッシュボード]
Auth -->|失敗| Error[エラー表示]
```
シーケンス図（Sequence Diagram）
フロントエンド、APIサーバー、データベース間のやり取りなど、時間経過に伴う処理の流れを分かりやすく示せます。
【入力するテキスト】
```mermaid
sequenceDiagram
autonumber
ブラウザ->>+APIサーバー: ユーザー情報リクエスト (GET /user)
APIサーバー->>+データベース: ユーザーデータ照会 (SQL)
データベース-->>-APIサーバー: 照会結果の返却
APIサーバー-->>-ブラウザ: JSONデータの返却 (200 OK)
```
ER図（Entity Relationship Diagram）
データベースのテーブル構造と、それらのリレーション（1対多など）を表現します。
【入力するテキスト】
```mermaid
erDiagram
USERS ||--o{ ORDERS : "1対多の関係"
USERS {
int id PK
string name
string email
}
ORDERS {
int id PK
int user_id FK
int total_amount
}
```
Mermaidを書くときによくあるエラーと対処法
テキストで作図できる反面、1文字の間違いで図が壊れてしまうこともあります。メインのつまずきやすいポイントと解決策をまとめました。
図が表示されない / 文字のままになる
- 原因：最初の「“`mermaid」の綴りが間違っているか、末尾の「“`」で正しく閉じられていません。
- 解決策：すべて半角英数字で書かれているか、余計なスペースが入っていないかを確認してください。また、VSCode標準プレビューの場合は、拡張機能が干渉していないか確認するか、Markdown Preview Enhancedのプレビュー画面に切り替えてみてください。
構文エラー（Syntax Error）になる
- 原因：矢印（–> や ->>）の記法が、その図の種類（graphやsequenceDiagram）で許されていない形になっています。あるいは、括弧のペア（ [ ] や { } ）が正しく閉じられていません。
- 解決策：プレビュー画面に赤文字でエラーの行数が表示されるので、その行の記法を公式リファレンス等と照らし合わせて確認しましょう。前述のMermaid Markdown Systax Highlightingを入れておくと、構文ミスがある部分のエディタの色が変わるため気づきやすくなります。
プレビューが更新されない
- 原因：エディタのキャッシュや、プレビュー拡張機能の読み込みが一時的にストップしています。
- 解決策：Markdownファイルを一度上書き保存（Mac：Cmd + S / Win：Ctrl + S）するか、プレビュー画面を一度閉じて再起動（Cmd + K → V）してください。
Mermaidを使うメリット
作図をすべてMermaidに移行することで、開発プロセス全体に大きなイノベーションが生まれます。
テキストで管理できる
「あの仕様書の図の元データ、誰のPCのどこ annealed？」という問題が永久に消滅します。ドキュメントの文字と一緒に図のデータも1つのファイル内に保存されているため、ファイルさえ開けば誰でもいつでも修正可能です。
Gitで差分管理しやすい
画像ファイル（.pngなど）をGitで管理すると変更履歴（差分）が分かりませんが、Mermaidはただのテキストです。
「どのテーブルにどのカラムが追加されたか」「フローのどこに条件分岐が増えたか」が、Gitのdiff（緑の赤の行）として完璧に可視化されます。プルリクエストのコードレビューと同じ感覚で、設計図のレビューができるようになります。
ドキュメント作成が効率化できる
マウスでポチポチと線を引いたり、配置をピクセル単位で微調整したりする美化作業に時間を溶かす必要がなくなります。配置はAIやMermaidのシステムが自動で綺麗に整えてくれるため、開発者は「設計の論理構造」を考えることだけに集中できます。
Markdownと組み合わせて活用しよう
Mermaidは、単体で使うよりもMarkdownドキュメントの「一要素」として組み込むことで真価を発揮します。
プロジェクトのルートにあるREADME.mdに簡単なシステムアーキテクチャの図を載せておけば、新しくチームに参画したメンバーへのキャッチアップが驚くほどスムーズになります。また、社内Wikiや仕様書フォルダ（docs/）にMarkdown＋Mermaidの形で設計書をストックしていけば、コードの変更とドキュメントの更新が常に同期した、生きたドキュメント資産を作り上げることができます。
【関連記事】
まとめ
VSCodeとMermaidを組み合わせた作図環境についてのまとめです。
- MermaidはVSCodeで手軽に利用できる：標準機能でも動きますが、Markdown Preview Enhancedなどの拡張機能を入れることで、超快適なリアルタイムレンダリング環境が完成します。
- さまざまな図をテキストで管理・Git共有できる：フローチャート、シーケンス図、ER図などをタイピングだけで作成。Gitの差分管理（diff）にも完全対応。
- ドキュメント作成が劇的に効率化する：マウス操作による配置の微調整から解放され、仕様変更にもテキストの書き換えだけで一瞬で追従。
一度テキストで図を描く快適さを知ってしまうと、もう重い作図ソフトを使って画像を作る時代には戻れなくなります。ぜひVSCodeの設定を済ませて、スマートで効率的なドキュメント作成をスタートさせてください！
