VSCode Markdown環境構築ガイド - おすすめ拡張機能と設定を徹底解説

VSCodeでMarkdownを書く最適な環境を構築する

Visual Studio Code（VSCode）は、Markdownファイルの編集において非常に優れた機能を備えています。標準機能だけでもプレビューや基本的なシンタックスハイライトが利用できますが、VSCode Markdown拡張機能を導入することで、執筆効率は飛躍的に向上します。

本記事では、VSCodeでMarkdownを快適に執筆するための環境構築を、拡張機能の選定から設定のカスタマイズまで体系的に解説します。技術ブログの執筆、プロジェクトドキュメントの作成、READMEファイルの整備など、あらゆるMarkdown執筆シーンで活用できる実践的なガイドです。

この記事で得られること

• VSCode標準のMarkdown機能の理解
• 目的別のおすすめMarkdown拡張機能
• settings.jsonによる最適な設定方法
• 執筆効率を高めるショートカットとテクニック

前提条件と実行環境

本記事の内容を実践するための環境要件は以下のとおりです。

VSCode標準のMarkdown機能

VSCodeには、拡張機能なしでも利用できるMarkdown機能が搭載されています。

これらの標準機能に加えて、拡張機能を導入することで、より高度なMarkdown編集環境を構築できます。

必須のVSCode Markdown拡張機能

Markdown執筆の生産性を最大化するために、以下の拡張機能を導入することを強く推奨します。

Markdown All in One

Markdown All in Oneは、VSCodeでMarkdownを書くための統合拡張機能です。インストール数は1,200万を超え、最も人気のあるMarkdown拡張機能のひとつです。

主な機能

インストール方法

VSCodeのコマンドパレット（Ctrl+Shift+P）を開き、以下を入力します。

ext install yzhang.markdown-all-in-one

または、拡張機能パネル（Ctrl+Shift+X）で「Markdown All in One」を検索してインストールします。

便利なショートカット

Markdown All in Oneが提供する主要なショートカットは以下のとおりです。

目次の自動生成

コマンドパレットから「Markdown All in One: Create Table of Contents」を実行すると、現在の見出し構造から目次を自動生成します。

1
2
3
4
5

## 目次

- [セクション1](#セクション1)
  - [サブセクション1-1](#サブセクション1-1)
- [セクション2](#セクション2)

ファイル保存時に目次を自動更新する設定も可能です。

markdownlint

markdownlintは、Markdownファイルの品質を維持するためのリンター（静的解析ツール）です。一貫性のないスタイルや潜在的な問題を検出し、警告を表示します。

主な検出ルール

markdownlintは60以上のルールを持ち、以下のような問題を検出します。

インストール方法

ext install DavidAnson.vscode-markdownlint

設定のカスタマイズ

プロジェクトルートに.markdownlint.jsonを作成することで、ルールをカスタマイズできます。

1
2
3
4
5
6
7

{
  "MD013": false,
  "MD033": {
    "allowed_elements": ["br", "details", "summary"]
  },
  "MD041": false
}

各設定項目の意味は以下のとおりです。

自動修正機能

markdownlintは多くの問題を自動修正できます。以下の設定をsettings.jsonに追加すると、ファイル保存時に自動修正が実行されます。

1
2
3
4
5
6
7
8

{
  "[markdown]": {
    "editor.formatOnSave": true
  },
  "editor.codeActionsOnSave": {
    "source.fixAll.markdownlint": "explicit"
  }
}

Markdown Preview Enhanced

Markdown Preview Enhancedは、VSCode標準のプレビュー機能を大幅に強化する拡張機能です。Mermaid、PlantUML、数式レンダリングなど、高度なプレビュー機能を提供します。

主な機能

インストール方法

ext install shd101wyy.markdown-preview-enhanced

Mermaid記法の例

Markdown Preview Enhancedでは、以下のようなMermaid記法をプレビュー上でレンダリングできます。

graph TD
    A[Markdownファイル作成] --> B[VSCodeで編集]
    B --> C{プレビュー確認}
    C -->|問題なし| D[コミット]
    C -->|修正が必要| B

ショートカット

補助的なVSCode Markdown拡張機能

必須ではありませんが、用途に応じて導入を検討すべき拡張機能を紹介します。

Paste Image

Paste Imageは、クリップボードの画像をMarkdownファイルに直接貼り付ける拡張機能です。スクリーンショットを多用する技術記事の執筆に便利です。

ext install mushan.vscode-paste-image

デフォルトではCtrl+Alt+V（Mac: Cmd+Option+V）で画像を貼り付けられます。

Markdown Table

Markdown Tableは、テーブルの作成と編集を支援する拡張機能です。Excelライクな操作でテーブルを編集できます。

ext install TakumiI.markdowntable

Markdown Footnotes

Markdown Footnotesは、脚注記法のシンタックスハイライトとプレビューを提供します。

ext install bierner.markdown-footnotes

VSCode Markdown設定のカスタマイズ

拡張機能の導入に加えて、settings.jsonをカスタマイズすることで、Markdown編集環境をさらに最適化できます。

推奨設定

以下は、Markdown執筆に最適化されたsettings.jsonの設定例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.quickSuggestions": {
      "comments": "on",
      "strings": "on",
      "other": "on"
    },
    "editor.tabSize": 2,
    "editor.insertSpaces": true,
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "yzhang.markdown-all-in-one",
    "editor.rulers": [80, 120],
    "editor.renderWhitespace": "all"
  },
  "markdown.preview.fontSize": 14,
  "markdown.preview.lineHeight": 1.6,
  "markdown.extension.toc.updateOnSave": true,
  "markdown.extension.orderedList.autoRenumber": true,
  "markdown.extension.list.indentationSize": "inherit"
}

設定項目の解説

各設定項目の目的と効果を解説します。

プロジェクト固有の設定

チームでMarkdownの執筆ルールを統一する場合は、.vscode/settings.jsonにプロジェクト固有の設定を記述します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "[markdown]": {
    "editor.defaultFormatter": "yzhang.markdown-all-in-one"
  },
  "markdown.extension.toc.levels": "2..4",
  "markdownlint.config": {
    "MD013": false,
    "MD024": {
      "siblings_only": true
    }
  }
}

推奨拡張機能の共有

チームメンバーに拡張機能のインストールを促すには、.vscode/extensions.jsonを作成します。

1
2
3
4
5
6
7
8

{
  "recommendations": [
    "yzhang.markdown-all-in-one",
    "DavidAnson.vscode-markdownlint",
    "shd101wyy.markdown-preview-enhanced",
    "mushan.vscode-paste-image"
  ]
}

この設定により、プロジェクトを開いた際に推奨拡張機能のインストールを促すポップアップが表示されます。

実践的なMarkdown執筆ワークフロー

ここまでの設定を活用した、効率的なMarkdown執筆ワークフローを紹介します。

ワークフロー図

graph LR
    A[新規ファイル作成] --> B[アウトライン作成]
    B --> C[本文執筆]
    C --> D[プレビュー確認]
    D --> E{markdownlintチェック}
    E -->|エラーあり| F[修正]
    F --> D
    E -->|エラーなし| G[目次生成]
    G --> H[保存・コミット]

Step 1: テンプレートの活用

VSCodeのスニペット機能を使って、Markdownファイルのテンプレートを登録しておくと便利です。

.vscode/markdown.code-snippetsに以下を追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "Blog Post Template": {
    "prefix": "blogpost",
    "body": [
      "---",
      "title: \"$1\"",
      "date: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE",
      "description: \"$2\"",
      "tags: [$3]",
      "---",
      "",
      "## $1",
      "",
      "$0"
    ],
    "description": "ブログ記事のテンプレート"
  }
}

Step 2: 執筆と同時プレビュー

Ctrl+K Vでサイドプレビューを開き、編集とプレビューを同時に確認しながら執筆を進めます。Markdown Preview Enhancedを使用している場合は、スクロール同期機能により、編集位置とプレビュー位置が自動的に連動します。

Step 3: リアルタイムリンティング

markdownlintが有効な状態では、問題のある箇所にリアルタイムで波線が表示されます。問題箇所にカーソルを合わせてCtrl+.を押すと、クイックフィックスが提案されます。

Step 4: 最終確認と目次生成

本文の執筆が完了したら、コマンドパレットから「Markdown All in One: Create Table of Contents」を実行して目次を生成します。markdown.extension.toc.updateOnSaveを有効にしておけば、以降の保存で目次が自動更新されます。

トラブルシューティング

VSCodeでMarkdownを編集する際によく発生する問題と解決策を紹介します。

プレビューが表示されない

原因: 拡張機能の競合または設定の問題

解決策:

1. VSCodeを再起動する
2. 拡張機能を無効化して標準プレビューが動作するか確認
3. markdown.preview.breaks設定を確認

markdownlintの警告が多すぎる

原因: プロジェクトのスタイルに合わないルールが有効になっている

解決策: .markdownlint.jsonで不要なルールを無効化

1
2
3
4
5

{
  "MD013": false,
  "MD033": false,
  "MD041": false
}

日本語の入力がおかしい

原因: IMEとVSCodeの相性問題

解決策: 以下の設定を追加

1
2
3
4
5
6
7
8

{
  "editor.suggest.snippetsPreventQuickSuggestions": false,
  "[markdown]": {
    "editor.quickSuggestions": {
      "other": "off"
    }
  }
}

まとめ

VSCodeでMarkdownを書くための環境構築について解説しました。要点を整理します。

VSCodeとこれらの拡張機能を組み合わせることで、以下の効果が期待できます。

• ショートカットによる執筆速度の向上
• リンターによる品質の均一化
• プレビュー機能による確認作業の効率化
• チーム設定の共有による協業の円滑化

Markdown執筆環境を整備することで、技術ドキュメントやブログ記事の執筆がより快適になります。本記事で紹介した設定を参考に、自身のワークフローに最適な環境を構築してください。

参考リンク

• Visual Studio Code - Markdown editing
• Markdown All in One - Visual Studio Marketplace
• markdownlint - Visual Studio Marketplace
• Markdown Preview Enhanced - Documentation
• CommonMark Spec
• GitHub Flavored Markdown Spec