【実務・中級編】VS Codeの「Markdownプレビュー」を最強の技術文書作成ツールへ：Mermaid連携とCSSカスタマイズで表現力を最大化 – 軽量・高機能テキストエディタ生産性向上バイブル

こんにちは。開発プロジェクトを率いるテックリードの皆さん、日々の技術仕様書やアーキテクチャ図の作成に疲弊していませんか？

「仕様書はConfluenceやNotion、図解はMiiMindやDraw.io、コードはVS Code」——このアプリのコンテキストスイッチこそが、エンジニアの脳のRAMを無駄に消費し、フロー状態を破壊する元凶です。

結論から言います。VS Codeを「最強のMarkdown文書作成環境」へ昇華させれば、ドキュメント作成のスピードは3倍になります。

今回は、標準のMarkdownプレビュー機能の限界を突破し、Mermaidによるコードベースの図解と、CSSによる洗練されたデザイン適用によって、VS Code内だけで出版物レベルの技術ドキュメントを完結させるための実践的アーキテクチャを伝授します。

—

なぜ「VS Code完結型」のドキュメント作成が実務で最強なのか？

多くのエンジニアが「Markdownは書けるけれど、プレビューが見づらい」「PDF出力するとダサい」という理由で、外部ツールに逃げます。しかし、それはツール側のポテンシャルを引き出せていないだけです。

VS CodeのMarkdownプレビューを拡張するというアプローチには、以下の圧倒的なアドバンテージがあります。

1. 完全なコンテキスト維持: コードを書いているそのエディタのまま、シームレスにドキュメントへ移行できる。
2. Gitとの親和性: すべてプレーンテキスト（.md）で管理されるため、コードレビューと同じフローでドキュメントの差分管理・レビューが可能。
3. ベンダーロックインの回避: プロプライエタリなクラウドサービスに依存せず、ローカル環境だけでアセットが完結する。

この環境を構築するために、まずは「絶対に導入すべき神プラグイン」から見ていきましょう。

—

絶対に入れるべき神プラグイン：エコシステムの極限活用

VS Codeのデフォルト機能だけでは、複雑な技術文書を書くには少し物足りません。以下のプラグイン群をインストールし、環境のベースを底上げします。

  • Markdown All in One (`yzane.markdown-all-in-one`)
  • 理由: ショートカットによる太字・斜体、リストの自動補完、目次（TOC）の自動生成など、Markdownを書く上での「無いと手が痛くなる」機能が全て詰まったマストバイ。
  • Markdown Preview Mermaid Support (`bierner.markdown-mermaider`)
  • 理由: 標準でもMermaidは動きますが、複雑なシーケンス図やアーキテクチャ図においてレンダリングの破綻を防ぎ、最新のMermaid構文を確実にプレビューに反映させるための必須拡張。
  • Markdown PDF (`yzane.markdown-pdf`)
  • 理由: 作成したMarkdownを、後述するカスタムCSSを適用したまま美しいPDFやHTMLとして一撃でエクスポートする。社内ニッチな共有に絶大な効果。

—

開発スピードを劇的に高める隠れたキーボードショートカット

マウスに手を伸ばした瞬間、あなたの思考の速度は落ちます。以下のショートカットを脳に焼き付けてください（Mac / Windows）。

  • プレビューの分割表示: `Cmd + K, V` (Mac) / `Ctrl + K, V` (Win)
  • 実践知: エディタの横にリアルタイムプレビューを常駐させ、タイピングの瞬間にレイアウトを確認するリズムを作ります。
  • 行の移動（上下）: `Option + ↑/↓` (Mac) / `Alt + ↑/↓` (Win)
  • 実践知: 箇条書きの順序入れ替えや、段落の構造化を瞬時に行います。
  • コマンドパレットからのクイックTOC生成: `Cmd + Shift + P` -> “Markdown All in One: Create Table of Contents”
  • 実践知: 長大な仕様書の冒頭に、手動で目次を書くエンジニアはもう時代遅れです。

—

【核心】カスタムCSSでプレビュー画面を「プロ仕様」に変える

VS Codeのデフォルトのプレビューは、GitHub風のテーマですが、実務の現場では「フォントサイズが小さい」「コードブロックのシンタックスハイライトが物足りない」「PDF出力時にレイアウトが崩れる」という不満が出てきます。

ここでは、外部CSSを読み込ませることで、プレビュー画面を美しいドキュメントビューアに変貌させる設定を解説します。

1. カスタムCSSファイルの作成

ワークスペースの適当な場所（例: `.vscode/markdown-style.css`）に、以下のCSSを配置します。

/ =================================================================
VS Code Markdown Preview Custom CSS (Enterprise Grade)
================================================================= /

/ 全体的なベース設定：可読性を極限まで高めるフォントと行間 /
body {
font-family: -apple-system, BlinkMacSystemFont, “Segoe UI”, Roboto, “Helvetica Neue”, Arial, “Hiragino Kaku Gothic ProN”, “Hiragino Sans”, Meiryo, sans-serif;
line-height: 1.8;
color: #24292e;
max-width: 900px;
margin: 0 auto;
padding: 40px;
background-color: #ffffff;
}

/ 見出しのスタイリング：技術文書としての階層を視覚的に明確化 /
h1 {
font-size: 2.2em;
border-bottom: 2px solid #eaecef;
padding-bottom: .3em;
margin-top: 1.5em;
}

h2 {
font-size: 1.6em;
border-bottom: 1px solid #eaecef;
padding-bottom: .3em;
margin-top: 1.5em;
color: #0366d6; / テックリード好みの知的なブルー /
}

/ コードブロックの洗練：視認性の高いダークテーマ風コンテナ /
code {
font-family: “Fira Code”, Consolas, “Courier New”, Courier, monospace;
background-color: rgba(27, 31, 35, 0.05);
padding: 0.2em 0.4em;
border-radius: 6px;
font-size: 85%;
}

pre code {
background-color: transparent;
padding: 0;
}

pre {
background-color: #f6f8fa;
border: 1px solid #e1e4e8;
border-radius: 6px;
padding: 16px;
overflow: auto;
}

/ 警告やヒントを強調するカスタムブロック（blockquoteを活用） /
blockquote {
border-left: 4px solid #0366d6;
background-color: #f1f8ff;
color: #24292e;
padding: 12px 16px;
margin: 16px 0;
border-radius: 0 6px 6px 0;
}

—

Mermaid連携による「コードで描く」アーキテクチャ図解

画像ファイルを別途作成して貼り付ける古い手法は捨てましょう。Markdown内に直接Mermaid記法を記述することで、テキストベースでバージョン管理可能な美しい図解を生成できます。

以下は、実務で即座に使える「システムアーキテクチャのシーケンス図」のサンプルです。これをVS Codeでプレビューすると、美しいベクター画像としてレンダリングされます。

認証フロー図 (OAuth2.0 / Authorization Code Flow)

sequenceDiagram
autonumber
actor User as ユーザー
participant Client as SPA / クライアント
participant Auth as 認証サーバー (Auth0/Cognito)
participant API as バックエンドAPI

User->>Client: ログインボタン押下
Client->>Auth: 認可リクエスト (/authorize)
Auth–>>User: ログイン画面表示
User->>Auth: 認証情報入力 (Credential)
Auth–>>Client: 認可コード (Authorization Code) 返却
Client->>Auth: トークン交換リクエスト (/oauth/token)
Auth–>>Client: アクセストークン / IDトークン 発行
Client->>API: APIリクエスト (Bearer Token付与)
API–>>Client: レスポンスデータ返却

—

チーム開発で役立つ設定の共有化ルール（ベストプラクティス設定）

個人の環境だけで動いても、チームの生産性が上がらなければテックリード失格です。プロジェクト内のメンバー全員が「同じ美しいプレビューとルール」でドキュメントを書けるよう、リポジトリに `.vscode/settings.json` を配置して設定を強制・共有します。

以下が、実戦投入に最適化された `settings.json` の全コードです。各行の意図をコメントで解説しています。

{
// =================================================================
// VS Code Workspace Settings for Technical Documentation
// =================================================================

// 1. 作成したカスタムCSSをMarkdownプレビューに適用するパス指定
“markdown.styles”: [
“.vscode/markdown-style.css”
],

// 2. プレビューの同期スクロールを有効化（エディタと完全連動）
“markdown.preview.scrollSync”: true,

// 3. ドキュメント内のリンク切れを検知するための設定
“markdown.validate.fileLinks.enabled”: “warn”,

// 4. エディタの基本作法：全角スペースの可視化と行端のトリム
“editor.renderWhitespace”: “all”,
“files.trimTrailingWhitespace”: true,

// 5. 日本語技術文書で読みやすくなるよう、ワードラップ（自動折り返し）を有効化
“editor.wordWrap”: “on”,
“editor.wordWrapColumn”: 100,

// 6. スペルチェック（Code Spell Checkerプラグイン等連携用）の除外設定
“cSpell.language”: “en,ja”,

// 7. 保存時に自動フォーマット（Prettier等）を走らせる設定
“editor.formatOnSave”: true,
“[markdown]”: {
“editor.defaultFormatter”: “esbenp.prettier-vscode”,
“editor.formatOnSave”: true
}
}

この `settings.json` をGit管理下に置くことで、新しいメンバーがリポジトリをクローンした瞬間から、誰一人追加の設定をすることなく「全く同じ高品質なドキュメント作成環境」が手に入ります。

—

テックリードからの総括

ドキュメント作成は、開発の「付随作業」ではありません。アーキテクチャの合意形成であり、チームの認知負荷を下げるための最重要エンジニアリングです。

今回紹介した、

  • VS Code + 厳選プラグインによるコンテキストスイッチの排除
  • カスタムCSSによる視認性の爆発的な向上
  • Mermaidによるコードとしての図解管理
  • `.vscode/settings.json` によるチーム全体への環境強制

これらを導入することで、あなたのチームのドキュメント文化は劇的に変わり、仕様策定から実装までのリードタイムは確実に短縮されます。

明日からではなく、今この瞬間のブランチから、この環境を構築してみてください。開発体験の次元が違うことに気づくはずです。

スポンサーリンク
タイトルとURLをコピーしました