PDF向けMarkdown目次作成：印刷に適した見出し構造と設定

目次は単なる飾りではありません。数ページを超えるドキュメントにおいて、読者が目的の項目へすぐに到達できるか、PDF全体を迷いながらスクロールするかの決定的な分かれ目になります。

md2pdfは単一文書用の目次を自動生成し、複数章からなるブック用の目次も組み立てます。本ガイドでは目次の仕組み、役立つ見出しの書き方、目次を無効化すべきケースを解説します。

印刷の全体的な流れについてはGitHubのREADMEをPDFに変換する方法、複数章の製本は複数ファイルのMarkdownブック作成をご参照ください。

目次機能が実際に生成するもの

単一ドキュメントのプレビューにおいて、目次は本文の上に挿入されるHTMLナビゲーションブロックです。見出しへのリンクを一覧化し、プレビュー画面内での移動や、ブラウザの印刷エンジンによるクリック可能なPDF内リンクとして機能します。

これはPDFビューアのサイドバーに表示されるアウトライン（しおり）とは異なります。アウトラインの生成有無はブラウザやビューアの仕様に依存します。

ブック機能では、目次は各章と見出しから組み立てられる文書内の1ページとして正式にレイアウトされます。

md2pdfが目次を構築するルール

単一文書の目次は解析されたMarkdownから自動的に生成されます：

• ドキュメント内に少なくとも3つ以上の見出しが必要です。
• H1からH4までの見出しが含まれます。
• 重複した見出しテキストにも一意のアンカーIDが付与されます。
• コンバーターの切り替えスイッチはプレビューと印刷の両方を制御します。

# Project handbook

## Installation

### Requirements

## Configuration

### Environment variables

## Troubleshooting

代表的な見出し構造の例：

6個の見出しが含まれているため、H1を文書タイトル、H2を主要セクション、H3をサブセクションとする階層構造の目次が自動生成されます。

目次の項目として機能する見出しを書く

見出しには「節の内容を伝えること」と「目次の一行になること」という2つの役割があります。文脈なしでは意味が通じない見出しは避けるべきです。

Vague:  ## Overview
Useful: ## Configure GitHub access
Vague:  ## Errors
Useful: ## Recover from a failed export

具体的な名詞や動詞を使いましょう：

具体的な見出しは、読者が本文を開かなくても内容を把握できるようにします。一行に収まる長さを心がけ、単なる強調目的で見出しを使わないようにしてください。

主要セクションはH2から始める

文書全体のタイトルをH1とし、本文の各章はH2から始めるのが最も堅牢な規約です：

1. 目次の最上位が明確になる。 H1が文書そのものを指し示します。
2. 下位セクションが自然に入れ子になる。 H3やH4が整然と並びます。
3. 印刷スタイルの崩れを防ぐ。 H1が何個も連続する不自然な見た目を回避できます。

ファイルごとにH1が使われている既存リポジトリには、ブック作成ワークフローのほうが適しています。

重複見出し、付録、長大な文書への対応

同一の見出しテキストが存在する場合、IDは衝突しませんが、目次には同じ表記が並び読者を混乱させます。ソース側で文脈を補ってください。

長大な文書でH4が多すぎると目次が1ページを超えてしまうことがあります。重要な節をH2やH3に絞り込み、細かい注釈は本文にまとめましょう。

付録には番号だけでなく ## 付録A：エクスポート制限 のように内容を明記してください。

目次を含めるべきかどうかの判断

技術仕様書、マニュアル、学習用テキストなど、参照型のドキュメントでは目次が威力を発揮します。1〜2ページの短いメモや告知文ではオフにするほうがすっきりします。

出力されたPDF内の目次を確認する

保存したPDFを開き、リンクが正しい位置へ移動するか、改ページ位置が適切かを確認してください。表の調整についてはMarkdownの表をPDFに変換するをご覧ください。