VS CodeのMarkdownプレビューを極限まで研ぎ澄ませ：MermaidとカスタムCSSで構築する「ドキュメント駆動開発」の真髄
世の多くのエンジニアは、VS Codeを「コードを書くためのエディタ」としか認識していない。しかし、真のアーキテクトにとって、VS Codeはコード、インフラ定義、そして技術仕様書という「プロダクトの全貌」をシームレスに統合する統合開発環境（IDE）であり、思考をダイレクトに成果物へ変換するための究極のキャンバスだ。
特に技術文書の作成において、WordやConfluence、あるいは外部のSaaS型ドキュメントツールに依存することは、開発サイクルのコンテキストスイッチ（文脈の切り替え）を生み出し、エンジニアの認知負荷を無駄に増大させる。コードを書く手をとめず、エディタ内で完結するMarkdownプレビュー環境をどれだけ極められるか——それが、スピーディかつ堅牢なシステムを組み上げるチームの分水嶺となる。
本稿では、VS Code標準のMarkdownプレビューを、単なる「テキストの簡易表示機能」から、複雑なアーキテクチャ図を内包し、厳格なデザインガイドラインに準拠した「最強の技術文書作成エンジン」へと昇華させるための全設定を公開する。
—
1. 内部アーキテクチャの理解：VS Codeプレビューの描画メカニズム
まず、表面的な設定の前に、VS Code内部でMarkdownプレビューがどのようにレンダリングされているか、その低レイヤの挙動を把握しておかねばならない。
VS CodeのMarkdownプレビューは、Electronのレンダラープロセス内で動作するWebviewによって構成されている。
Markdownテキストは、バックグラウンドで動作する拡張機能ホスト内のパーサー（標準では `markdown-it`）によってHTMLに変換され、セキュリティ上のサンドボックス（`iframe`ベース）を介してWebviewへ流し込まれる。
このアーキテクチャが意味することは一つ：「Webviewに適用されるDOM構造とCSSを完全に掌握すれば、プレビュー画面の見た目や挙動は無限にカスタマイズ可能である」ということだ。さらに、近年のVS Codeでは、標準でMermaid.jsがバンドルされており、テキストベースのダイアグラム描画がコアエンジンレベルでサポートされている。
このエコシステムを最大限にハックし、開発環境を構築する手順を解説する。
—
2. 拡張機能の選定と最小限にして最強の環境構築
余計な拡張機能の乱立は、VS Code全体のメモリ消費量を増大させ、インテリセンスの応答速度を低下させる。MarkdownとMermaid、そしてプレビューの拡張において導入すべきものは、実質的に以下の極少数に絞られる。
- Markdown Preview Mermaid Support (標準で内蔵されているが、最新のMermaid構文に追従するために挙動の確認が必要)
- Markdown All in One (ショートカット、目次自動生成、数式補完のデファクト)
- Markdown PDF (HTML/PDFへのオフラインビルド用)
これらを導入した上で、ワークスペースごとの `.vscode/settings.json` を用いて、環境そのものをコード化（Infrastructure as Codeのドキュメント版）する。
—
3. 実践：カスタムCSSによる「エンジニアリング仕様書」のデザイン統制
デフォルトのプレビューテーマは汎用的すぎる。厳密なアーキテクチャ図やAPI仕様書を記述する際、フォントファミリー、行間、コードブロックの視認性、そしてページ余白に至るまで、開発チーム全体でデザインシステムが統一されていなければならない。
プロジェクトルートに `.vscode/` ディレクトリを作成し、専用のCSSファイルと設定を流し込む。
ディレクトリ構造
.
├── .vscode/
│ ├── settings.json # VS Codeのワークスペース設定
│ └── styles/
│ └── document.css # プレビュー専用のカスタムCSS
└── docs/
└── architecture.md # 対象の技術文書
1. カスタムCSSの定義 (`.vscode/styles/document.css`)
以下のCSSは、GitHubのドキュメントスタイルをベースにしつつ、コードブロックの視認性を極限まで高め、Mermaid図表が画面幅いっぱいに美しく描画されるよう調整したプロ仕様のスタイルシートである。
/ — VS Code Markdown Preview Custom CSS — /
/ プレビュー全体のベーススタイルとタイポグラフィの最適化 /
body.vscode-body {
font-family: -apple-system, BlinkMacSystemFont, “Segoe WPC”, “Segoe UI”, “SF Pro Text”, Helvetica, Arial, sans-serif;
line-height: 1.7;
padding: 2rem 4rem;
color: #24292e;
background-color: #ffffff;
max-width: 1000px;
margin: 0 auto;
}
/ ダークテーマ検知時の自動切り替え /
body.vscode-dark.vscode-body {
color: #c9d1d9;
background-color: #0d1117;
}
/ 見出しの階層構造を視覚的に強調 /
h1, h2, h3, h4, h5, h6 {
margin-top: 24px;
margin-bottom: 16px;
font-weight: 600;
line-height: 1.25;
border-bottom: 1px solid #eaecef;
padding-bottom: 0.3em;
}
body.vscode-dark.vscode-body h1,
body.vscode-dark.vscode-body h2 {
border-bottom-color: #30363d;
}
h1 { font-size: 2em; }
h2 { font-size: 1.5em; }
h3 { font-size: 1.25em; }
/ コードブロックの視認性向上（シンタックスハイライトの親要素） /
code {
font-family: “SFMono-Regular”, Consolas, “Liberation Mono”, Menlo, Courier, monospace;
padding: 0.2em 0.4em;
margin: 0;
font-size: 85%;
background-color: rgba(27, 31, 35, 0.05);
border-radius: 6px;
}
body.vscode-dark.vscode-body code {
background-color: rgba(240, 246, 252, 0.15);
}
pre code {
padding: 0;
background-color: transparent;
}
pre {
padding: 16px;
overflow: auto;
font-size: 85%