VSCodeでmermaidの図を描く手順【拡張機能なしで使えるようになりました】

Markdown に図を埋め込むのに mermaid を使う場面が増えました。以前の VSCode では描画に拡張機能が必要でしたが、バージョン 1.121 で mermaid のレンダリングが本体に取り込まれ、何も入れなくてもプレビューに図が出るようになりました。

この記事では、VSCode で mermaid の図を描く手順と、設定・プレビュー上の操作・うまく描画されないときの見分け方をまとめます。手元の VSCode 1.132.1（Windows）で実際に描画を確認しながら書いています。

本記事の内容

1. VSCodeは拡張機能なしでmermaidが描ける
2. 実際に図を描いてみる
3. プレビューの上でできる操作
4. 設定で変えておきたい項目
5. 新しい記法がそのまま使える
6. うまく描画されないときの見分け方
7. まとめ

1. VSCodeは拡張機能なしでmermaidが描ける

VSCode 1.121（2026年5月）のリリースノートによると、Matt Bierner 氏の拡張機能「Markdown Preview Mermaid Support」が本体に統合され、Mermaid Markdown Features という組み込み拡張になりました。同梱されているため、無効化はできてもアンインストールはできません。

描画されるのは次の3か所です。

Markdown プレビュー
ノートブックの Markdown セル
チャット

つまり、README や手順書を書くときも、Jupyter のセルでも、同じ書き方が使えます。VSCode の Markdown 環境そのもののセットアップは以下にまとめています。

VSCodeで超快適なMarkdownエディタ環境を作る【プレビュー/画像貼付/目次/PlantUML】

2. 実際に図を描いてみる

.md ファイルの中に、コードフェンス（バッククォート3つ）の言語指定を mermaid にしたブロックを書きます。あとは Ctrl+Shift+V でプレビューを開くだけです（横に並べたい場合は Ctrl+K V）。

flowchart TB
    subgraph office[社内LAN]
        direction LR
        PC[業務端末] --> PRX[プロキシ]
    end
    PRX --> SAAS[SaaS]

左にソース、右にプレビューを並べると次のようになります。エディタを保存しなくても入力に追従して描き直されます。

VSCodeのMarkdownプレビューでmermaidの図が描画されている画面

上の図では subgraph の中で direction LR を指定し、グループの中だけ流れる向きを変えています。ネットワーク構成のように「箱の中は横並び、全体は縦」という図を書くときに効きます。

シーケンス図も同じフェンスの中に書けます。

sequenceDiagram
    autonumber
    利用者->>ヘルプデスク: 障害連絡
    ヘルプデスク->>基盤担当: エスカレーション
    基盤担当-->>利用者: 復旧報告

ファイルを保存しなくても、外部のツールがファイルを書き換えた場合もプレビューは自動で追従します。スクリプトで生成した図を確認しながら調整する、といった使い方もできます。

3. プレビューの上でできる操作

描画された図にカーソルを合わせると、右上にズーム用のボタンが4つ出ます。左からパンモードの切り替え・縮小・拡大・パンとズームのリセットです。

大きな構成図をプレビューから離れずに拡大できるので、以前の拡張機能より扱いやすくなっています。

図を右クリックすると、次の3つが選べます。

メニュー	動作
エディターでダイアグラムを開く	その図だけを別タブで大きく表示する
ダイアグラムソースのコピー	mermaid のソーステキストをコピーする
パンとズームのリセット	拡大・移動した表示を元に戻す

画像として保存するコマンドはありません。 図をファイルとして持ち出したい場合は、GitHub や GitLab に置いてそちらの表示を使うのが手っ取り早い方法になります。

4. 設定で変えておきたい項目

設定は markdown-mermaid で始まるキーにまとまっています。既定値は次の通りです。

設定キー	既定値	内容
`markdown-mermaid.lightModeTheme`	`vscode`	ライトモードでのテーマ
`markdown-mermaid.darkModeTheme`	`vscode`	ダークモードでのテーマ
`markdown-mermaid.languages`	`["mermaid"]`	図として扱うフェンスの言語
`markdown-mermaid.maxTextSize`	`50000`	1つの図に書ける最大文字数
`markdown-mermaid.mouseNavigation.enabled`	`alt`	マウス操作を有効にする条件
`markdown-mermaid.controls.show`	`onHoverOrFocus`	ズームボタンを出す条件
`markdown-mermaid.resizable`	`true`	下端のドラッグで高さを変えられるか
`markdown-mermaid.maxHeight`	空	図の最大の高さ（`400px` など）

テーマの既定値 vscode は、エディタのカラーテーマから色を作るという意味です。ダークテーマで使っていると図も暗い配色になります。印刷したり社外に配る資料に貼るなら、白黒でも読める neutral を明示しておくと安全です。

{
    // エディタのテーマに引きずられないよう固定する
    "markdown-mermaid.lightModeTheme": "neutral",
    "markdown-mermaid.darkModeTheme": "neutral",
    // ズームボタンを常に出す
    "markdown-mermaid.controls.show": "always"
}

なお、記事内で %%{init: {'theme':'forest'}}%% と書いてもテーマは変わりませんでした。設定側のテーマが優先されるためです。他のツールで使い回す .md にテーマ指定を書いている場合は、VSCode 上では見え方が変わる点に注意してください。

チーム内で設定を揃える方法は以下にまとめています。

VSCodeの設定をプロジェクトメンバー全員で統一する方法

5. 新しい記法がそのまま使える

VSCode 1.132.1 に同梱されている mermaid は 11.15.0 でした。実際に描画を通して確認したところ、次の記法がすべて描画できています。

flowchart / sequenceDiagram / classDiagram / erDiagram / gitGraph
subgraph の中の direction
mindmap / timeline / quadrantChart
architecture-beta / packet-beta / treemap-beta / radar-beta / kanban

ここがエディタによって差が出るところです。同じ .md でも、描画するエンジンのバージョンが古いと新しい記法は構文エラーになります。PyCharm で試したときは mermaid 8.9.1 が使われていて、mindmap も subgraph 内の direction も通りませんでした。

PyCharm 側の検証結果と記法のまとめは以下に書いています。

PyCharmのMarkdownでmermaidのフロー図を書く【記法まとめとバージョンの罠】

6. うまく描画されないときの見分け方

6.1 構文が間違っている場合

図の代わりに、次のようなエラーがそのまま表示されます。

Parse error on line 2:
...    A[障害の連絡を受ける --> B{他の利用者も同じ症状か}     B
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND',
'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND',
'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'DIAMOND_START'

実際の画面では、図が表示されるはずの場所にそのままエラーが出ます。