VSCodeでMermaidを使う方法｜標準プレビュー・拡張機能の選び方・PNG/SVG出力【2026年10月】

VS Code 1.121（2026年5月20日リリース）から、Markdownに書いたMermaidの図は拡張機能なしでプレビューに表示されます。ただし、.mmdファイルのプレビューとPNG・SVGへの書き出しは今も標準機能にありません。拡張機能やmermaid-cliを足すと、今度はツールごとに中で動くMermaidの版が11系と12系に分かれ、同じ定義でも図の見た目が変わります。この記事では、VS CodeでMermaidを書く・見る・書き出す・AIに描かせる方法を、VS Code 1.141.1（2026年10月12日公開）時点の状態で整理します。

まとめ：VS CodeでMermaidを使うときの結論

• Markdownの```mermaidブロックを見るだけなら拡張機能は不要です。ビルトイン拡張「Mermaid Markdown Features」がプレビューに描画します。
• 旧拡張「Markdown Preview Mermaid Support」は本体に統合されて非推奨です。残すと図が出なくなる報告があるので削除します。
• .mmdファイルのプレビューと画像出力はアカウント不要の「Mermaid Preview」、Markdown内の図を1枚ずつ画像にするなら「Mermaid Viewer」が手早い方法です。公式の「Mermaid」拡張はv2.7.7からサインインが必要です。
• VS Codeの標準プレビューはMermaid 11.17.0、mermaid-cli 12.0.0を今入れると中身は12.2.0です。12系は既定のレイアウトと配色が違うため、資料用の画像は版を固定して書き出します。
• AI拡張のvscode-mermAIdは開発終了です。VS Code 1.109以降はCopilot Chatが標準でMermaid図を描画します。

VS Code標準のMermaidプレビューの使い方と設定

Markdownにmermaidブロックを書いてプレビューを開く手順

Markdownファイル（.md）に、言語名をmermaidにしたコードフェンスを書きます。

```mermaid
flowchart TD
    A[受注データ受信] --> B{在庫あり?}
    B -->|Yes| C[出荷指示]
    B -->|No| D[発注登録]
```

Ctrl+Shift+V（macOSはCmd+Shift+V）でプレビューを開くと図になります。編集画面と並べるならCtrl+K V（macOSはCmd+K V）です。ビルトイン拡張のソースでは、::: mermaid形式のブロックも図として扱われます。

描画される場所は、VS Code 1.121のリリースノートのとおり、Markdownプレビュー、ノートブックのMarkdownセル、チャットの3か所です。通常のテキストエディタには図は出ません。記法の書き方はマーメイド記法の書き方｜フローチャート・シーケンス図・ER図をテキスト管理する手順、図の種類別の書き方はVSCodeでシーケンス図・フローチャート自動生成｜Mermaidが表示されない対処で扱っています。

テーマ・拡大操作・サイズを変える設定キー

ビルトイン拡張の設定は、旧拡張と同じmarkdown-mermaid.で始まるキーを引き継いでいるので、旧拡張用に書いたsettings.jsonはそのまま効きます。VS Code 1.141.1の同梱版（package.json）にあるキーは次の8つです。

テーマの既定値vscodeは、VS Codeの配色テーマから図の色を作ります。ダークテーマのまま資料用のスクリーンショットを撮ると背景が黒い図になるので、白背景で見たいときはdefaultか、白黒印刷向けのneutralに固定します。

Altキーを押さないとマウスで拡大できないのは、mouseNavigation.enabledの既定値がaltだからです。ホイールでの拡大とドラッグでの移動は、Altキー（macOSはOptionキー）を押している間だけ効きます。常に有効にするなら次のように書きます。

{
  "markdown-mermaid.lightModeTheme": "default",
  "markdown-mermaid.darkModeTheme": "dark",
  "markdown-mermaid.mouseNavigation.enabled": "always",
  "markdown-mermaid.maxHeight": "80vh"
}

図を右クリックすると「Copy Diagram Source」でMermaidの定義をコピーできます。画像として保存するメニューはありません。

標準の描画をオフにする設定キーはありません。markdown.mermaid.enabledで無効化できると書く解説もありますが、1.141.1の同梱拡張とMarkdown拡張のpackage.jsonのどちらにもこのキーは定義されていません。止めたいときは、拡張機能ビューで@builtin mermaidと検索し、「Mermaid Markdown Features」を無効にします。

実験的なMarkdown Editorでの図の表示

VS Code 1.131（2026年7月29日リリース）で、プレビューと編集を1画面で行う実験的な「Markdown Editor」が入りました。.mdファイルのタブでコマンドパレットから「Reopen Editor With…」を選び、「Markdown Editor」に切り替えます。リリースノートはMermaidに触れていませんが、ソース（markdown-language-featuresのmarkdown-editor-src/editor.ts）を読むと、言語名がmermaidのブロックはこのエディタの中で図として描画されます。

この描画はMermaid Markdown Featuresとは別の仕組みです。Markdown拡張がMermaid 11.17.0を自前で同梱し、テーマをdefaultに固定して初期化しているため、上のmarkdown-mermaid.*の設定は効きません。ダークテーマでも、図はライト向けのdefaultテーマの配色で描かれます。描画に失敗した図は定義のテキストのまま表示されます。

図を見ながら前後の文章を直したい場合に向きます。ただし実験的機能なので、既定のエディタにするのは手元の検証用にとどめ、チームの手順書にはプレビュー（Ctrl+Shift+V）を書いておくほうが確実です。Markdown Editorと拡張機能のMarkdown Live Editorの違いはMarkdown Live Editorの使い方と注意点｜VS Code組み込みエディタとの違い【2026年10月】で扱っています。

標準機能では足りない3つの場面

• .mmd／.mermaidファイルのプレビュー：ビルトイン拡張はこの拡張子を言語として登録していないため、開いてもプレーンテキストのままです。
• PNG・SVG・PDFへの書き出し：右クリックメニューに画像保存の項目はありません。
• 編集画面のエラー診断：標準プレビューには構文エラーのメッセージが表示されますが、編集画面の該当行に診断の波線を付ける機能はありません。

どれかが必要になった時点で、次の章の拡張機能かmermaid-cliを足します。

VS CodeのMermaid拡張機能の選び方（2026年10月時点）

検索すると2021〜2023年の拡張機能紹介が今も上位に出ますが、2026年に入って主要な拡張機能の位置づけは変わりました。Visual Studio MarketplaceのAPIで2026年10月14日に確認した状態は次のとおりです。

.mmdファイルを扱うならMermaid Preview

Mermaid Previewは、Mermaid.jsの開発元が保守している無料の拡張機能です。README冒頭で、アカウントのログイン、クラウド同期、AI機能は公式の「Mermaid」拡張へ移し、こちらは無料のローカルプレビューに絞ったと説明しています。.mmdと.mermaidを言語として登録し、編集と同時に更新される横並びのプレビュー、パンとズーム、PNG・SVGの書き出し、構文ハイライト、構文エラーの行表示を備えます。

既定で利用状況の送信（Share usage analytics）がオンです。社外に送信したくない環境では、サイドバーの設定でオフにします。VS Code本体のテレメトリ設定をオフにした場合も送信は止まるとREADMEに書かれています。

Markdown内の図を1枚ずつ画像にするならMermaid Viewer

Mermaid PreviewもMarkdown内のmermaidブロックを検出し、編集用のリンクからその図をプレビュー・編集できます。「設計書.mdの中の図を1枚だけ、倍率を選んでPNGにしたい」という用途ならMermaid Viewer（2.4.3、2026年9月26日更新）が手早い方法です。Markdown内の各mermaidブロックにCodeLensのボタンを出し、その図だけを専用のプレビューで開きます。READMEの機能一覧によると、ツールバーからSVG、PNG（1〜4倍）、JPG（1〜4倍）で保存またはクリップボードへコピーでき、書き出す前に寸法が表示されます。

Mermaidを拡張内に同梱しているのでオフラインで動き、アカウントも不要です。ただし同梱しているMermaidは12.0.0で、標準プレビュー（11.17.0）とは配置や配色が変わる場合があります。インストール数は約7,400件です。組織で標準化するなら、更新履歴、Issueへの対応状況、自社で使う種類の図の描画結果を確かめてから決めてください。

公式「Mermaid」拡張のv2.7.7以降のサインイン必須化

MermaidChart.vscode-mermaid-chartは、Mermaid.js開発元の公式拡張です。変更履歴によると、2026年9月4日のv2.7.7で名称が「Mermaid Chart」から「Mermaid」に変わり、同時にこの拡張を使うにはMermaidアカウントが必要になりました。サインインしないままコマンドを実行すると通知が出て、Mermaid Previewの導入を案内されます。10月12日のv2.8.2では描画に使うMermaidが12.1.0に上がりました。

この拡張を選ぶ理由があるのは、mermaid.aiのアカウントで図をチーム共有したい場合と、後述のAI機能を使いたい場合です。READMEのプライバシー項目には、VS CodeのマシンID（vscode.env.machineId）と利用イベントがmermaid.aiへ送られると明記されています。v2.7.9で追加された設定mermaidChart.enableTelemetryは既定でオンです（VS Code本体のテレメトリがオフなら送信されません）。外部送信の審査が要る組織では、導入時にこの設定をオフにするか、Mermaid Previewで足りないかを先に確認します。

旧拡張Markdown Preview Mermaid Supportの非推奨化と削除

Matt Bierner氏のMarkdown Preview Mermaid Supportは、累計539万回以上インストールされてきた定番でした。この拡張がそのまま本体に取り込まれ、GitHubのREADME冒頭には「VS Code 1.121に統合されたため非推奨」と掲げられています。

残したまま1.121以降へ更新すると、旧拡張とビルトインが同じmermaidブロックの描画処理を二重に登録し、図が表示されなくなる不具合がVS CodeのIssue #317870として報告されています（2026年10月14日時点でオープン）。旧拡張の最終版1.32.1が同梱するMermaidは11.12.2で、ビルトインより古い点も削除する理由になります。表示されない場合の確認順はVSCodeでシーケンス図・フローチャート自動生成｜Mermaidが表示されない対処にまとめています。

Markdown全体をPDF・HTMLにするならMarkdown Preview Enhanced

Markdown Preview Enhanced（MPE）は、独自のプレビュー画面でMermaidやPlantUML、数式を描画し、文書全体をPDFやHTMLに書き出す拡張機能です。1,046万回以上インストールされています。変更履歴によると、0.8.37（2026年9月25日）で同梱のMermaidが11.17.2から12.0.0に上がり、同時に図の書き出しでシェルを経由していたためにフォルダ名からコマンドを注入できた問題（CVE-2022-45026）が修正されました。0.8.39ではWaveDrom図のXSSも修正されているので、使うなら0.8.39以上にします。

図は12系で描かれるので、標準プレビューで確認した図とPDFの図は一致しないことがあります。PlantUMLも同じ文書で使う場合の選択肢で、Mermaidだけなら標準プレビューとmermaid-cliで足ります。

VS CodeからMermaid図をPNG・SVG・PDFに出力する方法

1枚ずつなら拡張機能のエクスポート

.mmdファイルならMermaid Previewのプレビューから、Markdown内の図ならMermaid ViewerのツールバーからPNGかSVGを保存します。拡張機能を増やしたくない場合は、標準プレビューで図を右クリックして「Copy Diagram Source」で定義をコピーし、Mermaid記法の使い方｜無料のLive Editor（mermaid.live）でフローチャート・シーケンス図を作成で紹介しているMermaid Live Editorに貼ってダウンロードする方法もあります。

mermaid-cli（mmdc）によるファイル単位の画像出力

繰り返し出力するならmermaid-cliを使います。まずMermaidの定義だけをdiagram.mmdとして保存し、そのフォルダで以下を実行します。Markdownのコードフェンスはファイルに含めません。v12.0.0はNode.js 22.13以上が必要で、出力形式は-oの拡張子で決まります。

npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.svg
mmdc -i diagram.mmd -o diagram.png -s 2
mmdc -i diagram.mmd -o diagram.pdf
mmdc -i diagram.mmd -o diagram.svg -b transparent

-s 2はPuppeteerの倍率で、4ノードのフローチャートで試すと360×418ピクセルのPNGが720×836ピクセルになりました。v11まであった-w（幅）と-H（高さ）はv12.0.0で削除され、指定するとerror: unknown option '-w'で止まります。代わりに--size 1200のように長辺のピクセル数を指定します（同じ図で1033×1200ピクセル）。背景を透過する-b transparentはSVGにも効き、出力したSVGの背景指定がtransparentになることを確認しました。

Markdown内のMermaid図の一括画像変換

入力に.mdファイルを渡すと、中のmermaidブロックをすべて画像にし、画像参照に置き換えたMarkdownを出力します。Mermaidを描画できないWikiやPDF変換ツールへ設計書を渡すときに使えます。

mkdir dist
mmdc -i docs/design.md -o dist/design.md

図が2つあるMarkdownで実行すると、dist/design-1.svgとdist/design-2.svgができ、dist/design.mdの該当箇所は![diagram](./design-1.svg)の形の画像参照に変わりました。出力先のフォルダは先に作っておきます。無いフォルダを指定するとOutput directory "dist/" doesn't existで失敗します。画像の置き場所を分けたいときは-aで指定します。

構文エラーの図があると、mmdcは終了コード1で失敗し、変換後のMarkdownは出力しません。先に描画が済んだ図の画像は残る場合があります。この性質を使い、mmdc -i docs/design.md -o /tmp/check.md -qをプルリクエストのCIで実行してその成功をマージ条件にすると、描画できない図を含む変更を止められます。

Markdown PDFのMermaid読み込み先とバージョン固定

Markdown全体をPDFにする拡張機能Markdown PDF（yzane.markdown-pdf、2.2.0）も、Mermaidのブロックを図としてPDFに入れます。ただし設定markdown-pdf.mermaidServerの既定値はhttps://unpkg.com/mermaid/dist/mermaid.min.jsで、版を指定していません。このURLは2026年10月14日時点で[email protected]へ転送されるため、PDFの図はMermaid 12で描画され、オフラインでは図が出ません。見た目をプレビューに合わせたいときは、https://unpkg.com/[email protected]/dist/mermaid.min.jsのように版を固定したURLを設定します。

ツールごとに違うMermaidの版：プレビューと画像が一致しない問題

Mermaid本体は2026年9月10日にv12.0.0、10月2日に12.1.0、10月13日に12.2.0を公開しました。VS Code本体は11系のままなので、同じ定義を開いても、どのツールで描くかによって11系と12系が混在します。次の表は、VS Codeの同梱ソース、各拡張のVSIX、CLIのnpm依存関係、Markdown PDFのCDN読み込み先を2026年10月14日に確認した結果です。

mermaid-cli 12.0.0は依存をmermaid@^12.0.0と範囲で指定しているため、入れた日によって中身の版が変わります。2026年10月14日に入れると12.2.0でした。

Mermaid 12の既定レイアウトと配色の変更

Mermaid 12.0.0のリリースノートは、レイアウトエンジンELKを本体に同梱して既定にしたこと、既定の見た目を変えたことを破壊的変更として明記しています。フローチャート、状態遷移図、クラス図、ER図などでレイアウトを指定していない図は、dagreではなくELKで配置し直されます。

次の定義を、Node.js 26.5.0（macOS）上のmermaid-cli 11.17.0と12.0.0（中身は12.2.0）で、それぞれ-o d.pngと-o d.svgで書き出して比べました。

flowchart TD
  A[受注] --> B{在庫あり?}
  B -->|Yes| C[出荷]
  B -->|No| D[発注]

SVGが約14倍になったのは、v12がフォントをSVGに埋め込むようになったためです。--no-font-embedを付けると32,459バイトまで下がりますが、表示側にそのフォントが無い環境では文字の見た目が変わります。

従来の見た目に戻す設定と版の固定

リリースノートが示す戻し方は、layout・theme・lookの3つを明示することです。次のJSONをclassic.jsonとして保存し、mmdcの-cで渡します。

{
  "layout": "dagre",
  "theme": "default",
  "look": "classic"
}

mmdc -i diagram.mmd -o diagram.png -c classic.json

この設定で薄紫の塗りと曲線の矢印は戻り、SVGも13,750バイトに縮みました。ただしPNGは426×422ピクセルで、11.17.0の250×372ピクセルとは一致しません。資料に貼る図の寸法まで揃えるなら、設定で近づけるよりmermaid-cli自体を11系に固定するほうが確実です。

npx -p @mermaid-js/[email protected] mmdc -i diagram.mmd -o diagram.png

チームで使う場合は、package.jsonのdevDependenciesに版を固定して入れ、package-lock.jsonもコミットしてCIとローカルで同じ版を使います。npm install -gで各自が入れた版は11系と12系が混在し、同じ定義から違う画像ができる原因になります。VS Codeのビルトインが12系へ上がった時点で、固定を外すかを見直してください。

AIでMermaid図を作る方法：mermAIdの終了とCopilot Chat

vscode-mermAIdの開発終了

vscode-mermAIdは、Microsoftが公開していたGitHub Copilot連携の拡張機能で、チャットで@mermAIdに頼むと開いているコードから図を作る実験的なものでした。GitHubのリポジトリはアーカイブ済みで、READMEには「VS Code 1.109からMermaid図のサポートが本体に組み込まれたため、この拡張は保守されていない」と書かれています。これから導入する理由はありません。

Copilot ChatによるMermaid図の生成と描画

VS Code 1.109（2026年2月4日リリース）で、チャットの回答がrenderMermaidDiagramツールを使ってMermaid図を描画できるようになりました。図はチャット内でパン・ズームでき、エディタで大きく開いたり、右クリックでソースをコピーしたりできます。1.141.1では、このツールもビルトイン拡張「Mermaid Markdown Features」が提供しています。

確実に図で返させたいときは、プロンプトで#renderMermaidDiagramを参照します。たとえば対象ファイルを添付して「#renderMermaidDiagram この関数の処理をsequenceDiagramで描いて」と頼みます。コピーしたソースをMarkdownのmermaidブロックに貼れば、設計書にそのまま残せます。エージェントモードの使い方はGitHub Copilotエージェントモードの使い方｜Ask・Edit・Agentの違いと有効化・料金【2026年版】を参照してください。

公式「Mermaid」拡張にも@mermaid-chartというチャット参加者があり、/generate_diagram_from_codeでコードからER図やシーケンス図を生成できます。v2.7.4ではCopilotに拡張のコマンドを使わせるワークスペース用の指示ファイル（Mermaid AI Skills）も追加されました。いずれもGitHub CopilotとMermaidアカウントの両方が必要です。

AIが描いた図をそのまま使うべきでない場面

AIは呼び出し順序や分岐をもっともらしく補いますが、実際には存在しないメソッド呼び出しや通らない分岐が混ざり、例外処理とリトライは特に落ちやすい箇所です。顧客に提出する設計書や監査対象の処理フローに、コードと突き合わせずに載せてはいけません。生成した定義は.mdか.mmdとしてリポジトリに置き、プルリクエストの差分でレビューすると、図とコードのずれを人が確認する工程が残ります。

よくある質問

VSCodeでMermaidを使うのに拡張機能は必要ですか？

Markdownに書いた図をプレビューで見るだけなら、VS Code 1.121以降は不要です。.mmdファイルのプレビューや、PNG・SVGへの書き出しをVS Code内で行いたい場合は、アカウント不要のMermaid PreviewかMermaid Viewerを追加します。

Markdown Preview Mermaid Supportは安全ですか？

安全性全般を保証する情報はありません。判断材料になるのは、VS Code 1.121で本体に統合され、旧拡張が非推奨になったことです。同じ機能をビルトイン拡張が提供し、こちらはMermaid 11.17.0を同梱しているのでCDNから読み込みません。旧拡張を残すと図が表示されなくなる不具合（Issue #317870）が報告されているため、1.121以降では旧拡張を削除し、ビルトイン拡張を使ってください。

Mermaidのファイルの拡張子は何ですか？

図だけを書くファイルは.mmdか.mermaidを使います。mermaid-cliの入力にもそのまま渡せ、Mermaid PreviewとMermaid Viewerはこの2つを言語として登録します。Markdownの文書に図を混ぜるなら、拡張子は.mdのままでコードフェンスの言語名をmermaidにします。VS Codeの標準機能が描画するのはこちらの形式だけです。

VSCodeのMermaidプレビューで図を拡大するには？

Altキー（macOSはOptionキー）を押しながらマウスホイールを回すと拡大・縮小でき、押しながらドラッグすると移動できます。常に有効にするには、settings.jsonで"markdown-mermaid.mouseNavigation.enabled": "always"を設定します。図にカーソルを合わせると出るズームボタンも使えます。

Mermaidの構文エラーをチェックする方法はありますか？

編集中に確かめるなら、標準プレビューでも描画できなかった図の位置にエラーメッセージが表示されます。行の特定まで欲しい場合は、Mermaid Previewがエラーの行とメッセージをプレビューに表示します。リポジトリ全体で確かめるなら、Markdownファイルをmermaid-cliに渡して終了コードで判定します。構文エラーの図が1つでもあると終了コード1になるので、CIに組み込めば簡易なチェックになります。

関連記事

• VSCodeでシーケンス図・フローチャート自動生成｜Mermaidが表示されない対処
• Mermaid記法の使い方｜無料のLive Editor（mermaid.live）でフローチャート・シーケンス図を作成
• マーメイド記法の書き方｜フローチャート・シーケンス図・ER図をテキスト管理する手順
• Markdown Live Editorの使い方と注意点｜VS Code組み込みエディタとの違い【2026年10月】
• PlantUMLとは？記法・使い方・インストールから.puml拡張子まで解説