解説記事や技術ドキュメントなど文章が長くなってくると、読者が途中で迷子になったり、読みたいトピックをすぐに見つけられなかったりすることがありますよね。
Hugoには、記事の中の「見出し（h2, h3 など）」を自動抽出し、リンクが適切に設定された「目次（Table of Contents）」を作成する機能が標準で備わっています。

今回はその目次機能の設定方法から、テンプレートへの組み込み、CSSでのデザイン調整までを一貫して解説します！

1. 設定ファイル（hugo.toml）での準備

まずは hugo.toml を開いて、目次の作り方をHugoに教えてあげましょう。
以下の設定を追加します。

[markup]
  [markup.tableOfContents]
    startLevel = 2    # 目次に含める見出しの開始レベル（h2から）
    endLevel = 3      # 目次に含める見出しの終了レベル（h3まで）
    ordered = false   # true = 番号付きリスト(ol), false = 箇条書きリスト(ul)
  • startLevel/endLevel: defaultではh2, h3が含まれます。h4まで含めたい場合は endLevel = 4 にします。
  • ordered: false にすると <ul> タグ、true にすると <ol> タグで出力されます。

2. テンプレートでの表示

設定ができたら、実際に目次を表示させたい場所に以下のコードを書きます。
通常は記事ページ（このテーマの場合は layouts/page.html）の、記事本文（{{ .Content }}）の直前あたりに入れることが多いです。

{{ .TableOfContents }}

たったこれだけ！
これだけで、記事内の見出しを拾って、リンク付きのリストを表示してくれます。

3. デザインを整える (CSS)

デフォルトのままだとただのリストなので、CSSで少し見やすくしてあげましょう。
Hugoが出力する目次には、自動的にIDやクラスが付与されます（設定によりますが、デフォルトでは <nav id="TableOfContents"> で囲まれます）。

CSS例（static/css/style.css）:

#TableOfContents {
    background-color: #f9f9f9;
    padding: 20px;
    border-radius: 5px;
    border: 1px solid #ddd;
    margin-bottom: 30px;
}

#TableOfContents ul {
    padding-left: 20px;
}

#TableOfContents li {
    list-style-type: disc;
    margin-bottom: 5px;
}
#TableOfContents li {
    list-style-type: disc;
    margin-bottom: 5px;
}

/* 「目次」というタイトルを追加 */
#TableOfContents::before {
    content: "目次";
    display: block;
    font-weight: bold;
    margin-bottom: 10px;
}

ポイント: 「目次」という文字を追加する方法

Hugoの機能 ({{ .TableOfContents }}) だけだと、「目次」というタイトル文字は出力されません。
上記のように CSSの ::before を使うと、テンプレートを汚さずにシンプルにタイトルを追加できるのでオススメです！

その他の方法

CSS以外にも、以下のような方法があります。好みや運用スタイルに合わせて選んでみてください。

A. テンプレートファイルに直接書く

layouts/page.html などを直接編集する方法です。HTMLタグを自由に組めるので、デザインの自由度が高いです。

{{ if .TableOfContents }}
  <div class="toc-container">
    <p class="toc-title">目次</p>
    {{ .TableOfContents }}
  </div>
{{ end }}

B. ショートコードを作成する

「記事の好きな場所に目次を置きたい！」という場合に便利です。
layouts/shortcodes/toc.html を作成します。

<div class="custom-toc">
  <p>目次</p>
  {{ .Page.TableOfContents }}
</div>

記事内では {{< toc >}} と書くだけで呼び出せます。

便利な自動目次（TOC）機能で記事をさらに読みやすく

Hugoに組み込まれている .TableOfContents は、長文記事・マニュアルのユーザビリティを大きく向上させてくれる機能です。記事内の見出しの階層に合わせて目次リンクが自動生成されるため、わざわざ手動でリストを作成・更新する手間から完全に解放されます。

CSSによるデザイン調整やショートコード化との組み合わせを試して、ぜひご自身のサイトにぴったりの読みやすい目次を作ってみてください！📑