拡張機能を1つ入れ忘れていただけで「Mermaidの図がただのコードブロックとして表示される」という現象にしばらく気づけませんでした。導入手順を一度きちんと整理しておきます。
⚠️ 今回はVS Code＋Mermaidを基準として書いています。
本記事の手順・画面イメージはVS Code環境を前提にしています。他のエディタをお使いの場合は、拡張機能の名称や設定方法を読み替えてください（比較はPART 01を参照）。
VS Codeの導入（要点）
VS Code自体のインストール手順は、本サイトのVSCode環境構築シリーズ PART 01 — 基本環境構築で詳しく解説しています。 この記事では要点だけ振り返ります。
- 公式サイトからインストーラーをダウンロードし、画面の指示に従ってインストールする
- Windows／macOS／Linux いずれにも対応しており、無料で利用できる
- Markdownの基本プレビュー機能は、追加インストールなしで最初から使える
💡 すでにVS Codeを使っている場合
Java・Python環境などですでにVS Codeを導入済みであれば、この章は読み飛ばして次の拡張機能導入に進んで問題ありません。
Mermaid対応拡張機能の導入
VS Code標準のMarkdownプレビューは、見出しや表などの基本記法には対応していますが、Mermaid記法のフローチャートはそのままではコードブロックとして表示されるだけです。 Mermaidの図をプレビュー上に描画するには、拡張機能を1つ追加します。
図1: 拡張機能タブから「Markdown Preview Mermaid Support」を検索してインストールする
手順は次の通りです。
- VS Code左側のアクティビティバーから拡張機能アイコン（四角が4つ並んだアイコン）をクリックする
- 検索ボックスに「
Markdown Preview Mermaid Support」と入力する - 検索結果の先頭に表示される拡張機能の「Install」ボタンをクリックする
コマンドパレットやターミナルからインストールすることも可能です。
# コマンドラインから直接インストールする場合
code --install-extension bierner.markdown-mermaid
# 目次生成・ショートカット拡張もあわせて入れる場合（任意）
code --install-extension yzhang.markdown-all-in-one✅ 設定ファイルの追加は不要
この拡張機能はインストールするだけで有効になり、settings.jsonを編集する必要はありません。他のMarkdown向け拡張機能（目次生成・Lintなど）についてはVSCode環境構築シリーズ PART 04で詳しく紹介しています。
プレビューの開き方
.mdファイルを開いた状態で、以下のいずれかの操作でプレビューを表示できます。
| 操作方法 | 内容 |
|---|---|
Ctrl + Shift + V | 現在のタブをプレビュー表示に切り替える |
Ctrl + K → V | ソースとプレビューを左右に並べて表示する（横並びプレビュー） |
| タブ右上のプレビューアイコン | 虫眼鏡＋本のアイコンをクリックして横並びプレビューを開く |
実務では、記法を書きながら右側でリアルタイムに崩れをチェックできる「横並びプレビュー」を使うのがおすすめです。
基本記法 早見表
見出し・強調・リストなどの基本記法は多くの解説記事があるため、ここでは早見表として整理するにとどめます。より網羅的な仕様を確認したい場合は Markdown Guide の基本記法一覧（英語）もあわせて参照してください。
| 記法 | 書き方 | 用途 |
|---|---|---|
| 見出し | # 見出し1 〜 ###### 見出し6 | セクションの階層分け |
| 強調（太字） | **太字** | 重要語句の強調 |
| 強調（斜体） | *斜体* | 補足的な強調 |
| 箇条書きリスト | - 項目 | 並列な項目の列挙 |
| 番号付きリスト | 1. 項目 | 手順・順序のある列挙 |
| 表（テーブル） | | 列1 | 列2 | と区切り行 | 構造化されたデータの提示 |
| 引用 | > 引用文 | 他文献・発言の引用 |
| リンク | [表示文字](URL) | 外部・内部リンク |
| 画像 |  | 図・スクリーンショットの挿入 |
| 水平線 | --- | セクションの区切り |
| タスクリスト | - [ ] 未完了 / - [x] 完了 | チェックボックス付きのTODO管理 |
特にタスクリストはREADMEの「今後の予定」欄や、作業チェックリストとして重宝します。GitHub上ではクリックでチェックのON/OFFを直接切り替えられるため、Issueやプルリクエストの説明欄でもよく使われます。
表示結果を確認する
実際に上記の記法を書いたときのソースとプレビューの対応関係は、次の図の通りです。
図2: 見出し・強調・リスト・表・引用・リンクのソース（左）とプレビュー表示（右）
表やリストは特にインデントや区切り文字の書き間違いで崩れやすい部分なので、書いたら都度プレビュー側で見た目を確認する習慣をつけると、あとから修正する手間が減ります。
特に表は、区切り行（|------|----|）のハイフンの数が列幅と合っていなくても表示自体は崩れませんが、列の数（|の数）が本文の行と合っていないと列がずれて表示されるため注意してください。
リストのネストはインデントの半角スペース数によって階層が決まります。エディタによってタブとスペースの扱いが異なることがあるため、迷った場合はスペース2〜4個で統一しておくと、他のツールで開いたときの崩れを防げます。