【コピペで使える】Markdown目次の作り方完全ガイド｜手動アンカー・VS Code自動生成・GitHub仕様まで徹底解説

長文のMarkdown（マークダウン）文書やGitHubのREADME、技術仕様書、社内Wikiを作成していると、「文章が長すぎて目的の項目を探しにくい」「読者が迷わないように冒頭に目次（TOC: Table of Contents）を設置したい」「見出しを修正するたびに手動で目次を書き直すのが大変」「VS Codeで目次を一瞬で自動生成・自動更新したい」と感じることがありませんか？

Markdown文書に適切な目次を設置すると、文書全体の構造が一目で把握できるようになり、読者が読みたい情報へワンクリックでジャンプできるため、読みやすさとユーザビリティが劇的に向上します。さらに、GitHubのREADMEやオープンソースのドキュメントでも、目次が整備されているかどうかでプロジェクトの完成度や信頼性が大きく評価されます。

本記事では、手動によるページ内アンカーリンクの書き方（日本語見出し・スラッグ化ルール）から、VS Codeの神拡張機能「Markdown All in One」を使った目次の自動生成・保存時自動更新設定、GitHub・Qiita・Zenn・Notion等の主要ツールの目次仕様、目次リンクが飛ばない・動かない時のトラブルシューティングまでを初心者にもわかりやすく徹底解説します！

1. 【結論】Markdownで目次（TOC）を作る3つの方法と使い分け

Markdown文書で目次（Table of Contents: TOC）を作成・表示する方法は、大きく分けて以下の3つのアプローチが存在します。

1. 手動作成方式（標準Markdown記法）：箇条書きリンク記法（[見出し名](#アンカー名)）を用いて手書きで作成する手法。どの環境でも確実に動作する汎用性の高さが強み。
2. エディタ拡張機能による自動生成方式（VS Code等）：VS Codeなどの高機能エディタで拡張機能（Markdown All in Oneなど）を使い、見出し一覧から目次をワンクリックで自動挿入・自動同期する手法。
3. プラットフォーム標準の目次・アウトライン機能：GitHubのOutline機能、Qiitaの[TOC]構文、Zennのサイドバー目次、Notionの目次ブロックなど、Webサービス側が自動レンダリングしてくれる手法。

・手法別の特徴とメリット・デメリット比較表

・用途に応じたおすすめの選び方

2. 【手動作成編】Markdown標準記法で目次（アンカーリンク）を作る手順

まずは、どんなテキストエディタやWebフォームでも使える「Markdown標準記法による手動目次の作り方」をマスターしましょう。

・手動目次の基本構造（リスト記法 × ページ内リンク）

Markdownにおける手動目次は、「箇条書きリスト記法（- または *）」の中に「ページ内アンカーリンク記法（[リンク文字列](#アンカー名)）」を記述し、文書内の見出し（# 見出し名）と紐付けることで成立します。

## 目次
- [1. はじめに](#1-はじめに)
- [2. インストール手順](#2-インストール手順)
  - [2.1 前提条件](#21-前提条件)
  - [2.2 実行コマンド](#22-実行コマンド)
- [3. まとめ](#3-まとめ)

## 1. はじめに
ここははじめにのセクションです。

## 2. インストール手順
ここはインストール手順のセクションです。

### 2.1 前提条件
ここは前提条件です。

### 2.2 実行コマンド
ここは実行コマンドです。

## 3. まとめ
ここはまとめです。

・【コピペ用】手動目次の最小構成テンプレート

以下のテンプレートをコピーして、文書の冒頭に貼り付けてご利用ください。見出しの階層に合わせて半角スペース2個（または4個）でインデントすると、綺麗な階層構造の目次になります。

# ドキュメントタイトル

## 📌 目次
- [1. 概要・特徴](#1-概要特徴)
- [2. 使い方・操作手順](#2-使い方操作手順)
  - [2.1 初期設定](#21-初期設定)
  - [2.2 基本コマンド](#22-基本コマンド)
- [3. よくある質問（FAQ）](#3-よくある質問faq)
- [4. まとめ](#4-まとめ)

---

## 1. 概要・特徴
...

## 2. 使い方・操作手順
...

### 2.1 初期設定
...

### 2.2 基本コマンド
...

## 3. よくある質問（FAQ）
...

## 4. まとめ
...

・【超重要】見出しからアンカーID（スラッグ）が生成される4つのルール

手動で目次を作成する際に最もつまずきやすいのが、「見出しのテキストからどのようにアンカー名（URLフラグメント / スラッグ）が生成されるのか」という変換ルールです。

GitHub Flavored Markdown (GFM) や一般的なMarkdownパーサーでは、見出しから以下の4つの変換ルールに従ってアンカーIDが自動生成されます。

・日本語見出しでアンカーリンクを正しく動作させるコツ

日本語の見出しをアンカーにする場合、GitHubやVS Codeでは日本語のまま（例：#インストール手順）指定して動作します。

## 目次
- [インストール手順へ](#インストール手順)

## インストール手順
ここにインストール内容を記述します。

ただし、一部の古いWebシステムや特殊なMarkdown変換環境では、日本語部分をURLエンコード（パーセントエンコーディング：例：#%E3%82%A4%E3%83%B3%E3%82%B9...）しないとリンクが正しく認識されないケースがあります。モダンな環境（GitHub, VS Code, Qiita, Zenn, MkDocs等）ではUTF-8の日本語文字列をそのまま記述して問題ありません。

・HTMLアンカー（id属性 / name属性）を使って確実にジャンプさせる方法

「見出しの記号ルールが複雑でアンカーがうまく合わない」「プラットフォームに依存せず100%確実にジャンプさせたい」「見出し以外の文中や表の位置へ飛ばしたい」という場合は、HTMLタグの id 属性を使ったカスタムアンカーを設置するのが最も確実です。

## 目次
- [詳細な設定手順へジャンプ](#custom-setup-section)

---

<!-- 飛び先にid属性を付与したspanまたはaタグを配置 -->
<h2 id="custom-setup-section">2. 詳細な設定手順（※記号が多くても安心）</h2>
または
## 2. 詳細な設定手順 <span id="custom-setup-section"></span>

ここに設定手順の内容を記述します。

HTMLタグによる id 指定を行えば、自動生成ルールに関係なく、指定したID（例：custom-setup-section）へ確実にスクロール移動させることができます。

3. 【VS Code編】目次を一発自動生成＆保存時に自動更新する神テクニック

日常的に長文ドキュメントやREADMEを書く方にとって、見出しを追加・削除・リネームするたびに手動で目次を修正するのは非常に骨の折れる作業です。

そこでおすすめなのが、VS Code（Visual Studio Code）の大人気拡張機能「Markdown All in One」を活用した「目次の全自動生成 ＆ 保存時自動更新」テクニックです。

・必須拡張機能「Markdown All in One」の導入手順

「Markdown All in One」は、全世界で800万回以上ダウンロードされているVS Code定番のMarkdown総合支援ツールです。

1. VS Codeを起動し、左側の拡張機能アイコン（ショートカット：Ctrl+Shift+X / Cmd+Shift+X）をクリックします。
2. 検索バーに Markdown All in One と入力します。
3. 作者「Yu Zhang」の拡張機能が表示されたら、「インストール（Install）」ボタンをクリックします。

・コマンドパレットから目次を一瞬で自動挿入する操作手順

Markdown All in Oneをインストールすれば、コマンド1回でファイル内の全見出しをスキャンし、完璧なインデント構造の目次を自動生成してくれます。

1. 目次を挿入したい位置（文書の冒頭など）にカーソルを置きます。
2. コマンドパレットを開きます（ショートカット：Ctrl+Shift+P / Cmd+Shift+P）。
3. 検索窓に toc と入力し、表示された候補から Markdown All in One: Create Table of Contents を選択してEnterを押します。

これだけで、以下のようにコメントタグ（<!-- TOC -->）で囲まれた目次が一瞬で自動挿入されます！

<!-- TOC -->
- [1. はじめに](#1-はじめに)
- [2. インストールとセットアップ](#2-インストールとセットアップ)
  - [2.1 前提環境](#21-前提環境)
  - [2.2 設定ファイルの作成](#22-設定ファイルの作成)
- [3. まとめ](#3-まとめ)
<!-- /TOC -->

・【超便利】保存時に目次を自動更新する神設定（settings.json）

Markdown All in Oneの真骨頂は、「ファイルを保存（Ctrl+S / Cmd+S）するたびに、目次を最新の見出し構成へと自動同期してくれる機能」です！

この設定を有効にしておけば、本文中で見出しの名前を変えたり、見出しの順番を入れ替えたり、新しい見出しを追加しても、ファイルを保存するだけで目次が自動的に書き換わります。

{
  // ファイル保存時に目次（TOC）を自動更新する
  "markdown.extension.toc.updateOnSave": true
}

・目次の深さ（H2〜H4等）や除外見出しを調整するカスタマイズ設定一覧

目次に含める見出しの階層（深さ）や、リストの記号、スラッグ化のアルゴリズムなどは settings.json で自由自在にカスタマイズ可能です。

{
  // 目次の自動更新を有効化
  "markdown.extension.toc.updateOnSave": true,
  // H2からH4までを目次に対象とする（H1文書タイトルは除外）
  "markdown.extension.toc.levels": "2..4",
  // GitHub互換のスラッグ生成
  "markdown.extension.toc.slugifyMode": "github"
}

・目次の手動更新・一括削除コマンド

自動更新設定を使っていない場合や、既存の目次をきれいに削除したい場合は、以下のコマンドを使用します。

• 目次の手動更新：コマンドパレット ➔ Markdown All in One: Update Table of Contents
• 目次の一括削除：コマンドパレット ➔ Markdown All in One: Delete Table of Contents（<!-- TOC --> タグごと綺麗に消去されます）

4. 【プラットフォーム別】GitHub・Qiita・Zenn・Notion等の目次仕様まとめ

Markdownを扱う主要なWebプラットフォームやナレッジ管理ツールにおける、目次（TOC）の対応状況と独自仕様を整理しました。

・GitHub（READMEの目次表示 ＆ アウトライン機能の仕様）

GitHubのリポジトリやMarkdownファイル（README.mdなど）では、以下の2つの方法で目次が機能します。

1. 本文内の手動 / VS Code自動目次：本文冒頭に配置した目次リンクをクリックすると、GitHub上でページ内スクロールして該当見出しへジャンプします。
2. GitHub公式アウトライン機能（Outline）：GitHub上でMarkdownファイルを表示すると、ファイル右上に「三本線＋リストマーク（Outline / 目次アイコン）」が自動表示されます。ここをクリックするとドキュメント全体の見出しツリーがポップアップ表示され、本文内に目次を記述していなくても任意の見出しへジャンプできます。

・Qiita（[TOC] 記法による自動目次生成）

Qiitaでは、記事本文の中に [TOC] または [[toc]] と記述するだけで、記事内の見出し（H1〜H6）を自動スキャンして目次を自動展開してくれます。

# 記事タイトル

[TOC]

## 1. はじめに
...

また、QiitaのWebビューではPC画面の右側に固定サイドバー目次が標準で常時表示されます。

・Zenn（見出しからの自動サイドバー目次）

Zennでは、[TOC] などの特殊構文を書く必要はなく、記事内の ## H2 および ### H3 見出しから右側サイドバーの目次が完全自動で生成されます（本文内に手動目次を書く必要はありません）。

・Notion（/table of contents による動的目次ブロック）

Notionでは、ページ内の任意の位置で /toc または /table of contents とタイプしてEnterを押すと、ページ内の見出し1〜見出し3をリアルタイムに反映する「目次ブロック（Table of Contents）」が作成されます。見出しを編集すると即座に目次ブロックの内容も自動更新されます。

・Obsidian / MkDocs / DocBaseの目次対応状況

• Obsidian：標準コアプラグイン「アウトライン（Outline）」を有効にすると、右サイドバーに全見出しがツリー表示されます。本文内に目次を埋め込みたい場合はコミュニティプラグイン「Table of Contents」や「Dynamic TOC」が便利です。（※詳細は Obsidianの使い方完全ガイド を参照）
• MkDocs / Material for MkDocs：ドキュメント内の見出しから右サイドバーの目次（Table of contents）が自動生成されます。また、Markdown拡張機能 toc を有効にすれば [TOC] による本文内展開も可能です。（※詳細は MkDocs完全ガイド を参照）
• DocBase：Qiitaと同様に [TOC] と記述することで本文中に目次が自動挿入されます。

5. 【トラブルシューティング】目次リンクが動かない・飛ばない時の7大原因と解決策

「目次のリンクをクリックしても該当の見出しにジャンプしない・飛ばない」「リンクの色は変わるのにスクロールしない」という場合によくある7つの原因と具体的な解決手順をまとめました。

・原因1：大文字・小文字やハイフン（-）の表記揺れ

見出しが英語の場合、アンカー側で大文字のまま記述しているとリンクが一致せずジャンプしません。

• ❌ 誤り：[はじめに](#Getting-Started) ➔ 大文字が含まれている
• ⭕ 正しい：[はじめに](#getting-started) ➔ すべて小文字にする

・原因2：見出しに含まれる記号（! ? : . 等）の削除忘れ

見出しに番号や記号（1. 【注意】 (必須) Q&A: 等）が含まれている場合、スラッグ化の過程で記号が削除されます。

• 見出し：## 1. インストール手順（Mac版）
• ❌ 誤り：[手順](#1.-インストール手順（mac版）) ➔ ピリオドや全角カッコが残っている
• ⭕ 正しい：[手順](#1-インストール手順mac版) ➔ ピリオドとカッコを削除し、半角スペースをハイフン化

・原因3：同一名の見出しによる連番サフィックス（-1, -2）の発生

ドキュメント内に同じテキストの見出しが複数存在する場合、2つ目以降の見出しには -1、-2 の連番が付加されます。

• 1つ目の ## 設定手順 ➔ アンカーは #設定手順
• 2つ目の ## 設定手順 ➔ アンカーは #設定手順-1
• 3つ目の ## 設定手順 ➔ アンカーは #設定手順-2

・原因4：# の後ろに半角スペースがない（見出し構文エラー）

見出し記号 # の直後に半角スペースがないと、Markdownパーサーが見出しとして認識せず、アンカーID自体が生成されません。

• ❌ 誤り：##見出しテキスト（スペースなし ➔ 通常のテキスト扱い）
• ⭕ 正しい：## 見出しテキスト（# の後に半角スペース必須）

・原因5：日本語見出しのパーセントエンコーディングによる不一致

エディタやブラウザによって、日本語のアンカーがURLエンコードされている場合とUTF-8生のままで処理される場合があります。手動リンクで解決しない場合は、前述の <h2 id="custom-id"> や <span id="custom-id"> による英数字IDの直接指定を試してください。

・原因6：Markdownプレビューと実環境（Web / GitHub）の挙動差

一部のシンプルなMarkdownプレビュー機能では、セキュリティ上の理由からページ内フラグメントジャンプが無効化されていることがあります。ローカルで飛ばない場合でも、GitHubにプッシュしたりブラウザのHTML表示で正常に動作することがあります。

・原因7：VS Codeの保存時自動更新が無効になっている

見出しを変更したのに目次が古いままになっている場合、settings.json の "markdown.extension.toc.updateOnSave": true が正しく設定されているか確認してください。

・デバッグ用チェックリスト表

6. 目次作成・管理を劇的に効率化するおすすめツール＆CLI

VS Code以外の環境や、CI/CD・ターミナル作業で目次を管理したい時に役立つ便利なツールをご紹介します。

・VS Code拡張機能（Markdown All in One / Markdown Preview Enhanced）

• Markdown All in One：目次の自動生成・保存時自動更新において圧倒的No.1の必須拡張機能。
• Markdown Preview Enhanced (MPE)：高度なサイドバイサイドプレビューを提供し、プレビュー画面内の動的目次（サイドバーTOC）や目次HTMLの書き出しに対応しています。

・CLIツール「doctoc」（READMEの目次を一括自動更新）

Node.js環境をお持ちの開発者であれば、npmパッケージの「doctoc（ドック・トック）」を使うと、ターミナルからコマンド1発でREADME.mdに目次を挿入・更新できます。Gitのpre-commitフックやGitHub Actionsに組み込んで、目次の更新漏れを完全防止する運用も大人気です。

# doctocをグローバルインストール
npm install -g doctoc

# 指定したMarkdownファイルに目次を自動生成・更新
doctoc README.md

# フォルダ内の全Markdownファイルを一括処理
doctoc .

・オンライン目次ジェネレーター（Webツール）

エディタに拡張機能を入れたくない場合やブラウザ上でサクッと目次を作成したい場合は、「Markdown TOC Generator」などの無料WebツールにMarkdownテキストを貼り付けるだけで、アンカー付き目次コードを一瞬で生成できます。

7. よくある質問（FAQ）

<details>
<summary><strong>📖 目次を展開する（クリックで開閉）</strong></summary>

- [1. はじめに](#1-はじめに)
- [2. 使い方](#2-使い方)
- [3. まとめ](#3-まとめ)

</details>

8. まとめ＆関連Markdown活用ガイド一覧

長文のMarkdownドキュメントやGitHubのREADMEにおいて、目次（TOC）は読者の利便性と文書の完成度を左右する極めて重要な要素です。