本文へ移動
ブログに戻る
2026年11月18日水曜日

GitHub の README に Markdown で目次と見出しリンクを作る方法

GitHub の README にクリックできる目次を作ります。コピー用の例で子項目と同名見出しを扱い、表示されたファイルからアンカーを取得します。見出しを変えた場合のリンク修正や、別ファイルから移動する書き方も確認できます。

GitHub の README に Markdown で目次と見出しリンクを作る方法

README の冒頭に箇条書きを置き、[Quick start](#quick-start) のように書くと、見出し ## Quick start へリンクできます。 角括弧の中が読者に見える名前で、ハッシュの後ろが移動先のアンカーです。

GitHub は Markdown ファイルの見出しからアウトラインも生成します。他のプロジェクトの README を読むときは、そこから各節に移動できます。自分の README を開いた読者に、よく使う節をすぐに見つけてほしい場合は、本文の冒頭に目次を書きます。GitHub の README ガイド

目次付き README の例をコピーする

この例は子項目を一つ、同じ名前の見出しを二つ含みます。コードブロックの中身を Markdown ファイルに貼り付け、四つのリンクを試してください。

# Field Notes

## Contents

- [Quick start](#quick-start)
  - [Import a notebook](#import-a-notebook)
- [Examples for writers](#examples)
- [Examples for reviewers](#examples-1)

## Quick start

Open a notebook and add your first entry.

### Import a notebook

Choose an existing folder of Markdown notes.

## Examples

Writers can group entries by trip.

## Examples

Reviewers can scan entries by date.

Import a notebook は Quick start の下にインデントしています。本文でも、H3 の小節は H2 の節に属します。二つの節の見出しはどちらも Examples です。目次では対象の読者が伝わる名前にして、別々のアンカーを指定します。

表示された見出しからアンカーを取得する

単純な見出しでは、GitHub は英字を小文字にし、空白をハイフンに置き換えます。疑問符などの記号や書式の印は取り除かれます。同じアンカーがすでにあると、番号が付きます。例の二つの移動先は #examples と #examples-1 です。GitHub のセクションリンクのルール

日本語や句読点、インライン書式がある場合は、表示されたファイルで実際のリンクを確認できます。GitHub で見出しにカーソルを合わせ、横に出るリンクアイコンを押して、アドレス欄のハッシュ以降をコピーします。同じフォルダーの別ファイルからリンクする場合は、[Quick start](README.md#quick-start) のようにファイル名を前に付けます。

違う場所に移動するリンクを直す

起きたこと確認する箇所
ファイルの先頭にとどまるハッシュがあるか、表示された見出しから取ったアンカーと一致するかを確認する。
二つの項目が最初の Examples に飛ぶ二つ目の見出しからリンクを取り直す。この例では末尾が -1。
編集後に移動できなくなった名前や順番を変えた見出しのアンカーを確認し、以前のリンクを更新する。
子項目が親と同じ位置に並ぶ箇条書きをインデントする。見出しのレベルと目次のインデントは別々に設定する。
サイトを変えるとリンクが動かない読者が実際にファイルを開くサイトでアンカーをコピーする。

編集後は、表示された README の目次を一つずつ押して確かめます。同名の見出しを移動した場合は、意図した節が開くか確認します。目次にはセットアップ、使い方、トラブル対応など、読者が探す節から入れます。長い節は小見出しへのリンクもあると探しやすくなります。

文書の構成を画像で共有する

下の PNG は、同じ原稿を使って Markdown2Image からダウンロードしました。見出しの階層と目次のインデントが見えます。スライドで文書構成を共有する場合は画像の横に README のリンクを置くと、読者は原文を開いて目的の節へ移動できます。Markdown2Image で例をプレビュー

目次の子項目と二つの Examples が表示された README の画像

元の PNG を開く