TOCはどうやって表示できるようにするのが良いのだろうか？

Hugoでブログに目次（Table of Contents, TOC）は重要です。TOCがあることで記事の読みやすさを向上できるからです。

でも、このときに疑問があります。

  • このTOCの制御する方法とは？
  • また複数の選択肢があった場合にどこでやるのが良いのだろうか？

こういう事を考えてみたいと思います。

TOCの制御方法はPaperModの機能で実現するのが良い。

この記事の結論としてはPaperModの機能で実現するのが良いとしました。

config/_default/hugo.toml に以下の設定を加える方法です。

[params]
  UseHugoToc = true
  showtoc = true

なぜこのような設定にしたのでしょうか？

その結論を得るための前提の方法の洗い出し、各選択肢の比較と最終的にPaperModの機能で良いとした理由を記述します。

HugoのブログのTOC表示の選択肢は3つある。

Hugoのブログでは３つの選択肢があります。

  • Hugo自身の設定
  • Hugoテーマ（本サイトではPaperMod）の機能
  • コンテンツ変換ツールでTOCをMarkdownに挿入する
    • 私の場合、 ox-hugo でEmacs Org modeからMarkdownへ変換しています。

色々ありますね。

ox-hugoでのTOC生成を試し、却下した

当初、私は ox-hugo の機能を使ってTOCを生成しようと考えました。 Orgファイルのプロパティとして以下の設定を加える方法です。

#+TOC: headlines 3

しかし、この方法にはいくつかの課題がありました。

課題点

  • 生成されるMarkdownファイルに、TOCがHTMLの = <div class“ox-hugo-toc”>…</div> == のように直接書き込まれてしまう。
  • これにより、Markdownファイルが冗長になる。
  • Hugoやテーマ側での動的なTOC制御（サイドバーでの追従表示など）が効かなくなる。

Hugoの強みは、コンテンツ（Markdown）とプレゼンテーション（テーマ）を分離できる点にあります。 コンテンツファイルに直接HTMLを埋め込むこの方法は、その思想とは少しずれていると感じました。

また、この試行錯誤をしたときにはHugo自体にTOCを生成する機能があるとは知りませんでした。

最終的な解決策：HugoとPaperModのTOC機能を利用する

そこで、TOCの生成と表示はHugoとテーマ側に一任する方針に切り替えました。 本サイトで利用しているPaperModテーマには、TOCを制御する機能があります。

設定は config/_default/hugo.toml ファイルで行います。

[params]
  UseHugoToc = true
  showtoc = true
  • UseHugoToc = true : Hugoの組み込みTOC生成機能を使用することをPaperModに伝えます。
  • showtoc = true : 記事ページでTOCを表示します。

この設定により、各記事のMarkdownファイルに特別な記述が不要になります。 また、Hugoが自動で見出しを解析してTOCを生成し、PaperModがそれを適切な場所に表示してくれます。

また記事個別設定も可能です。 個別のMarkdownファイルのフロントマターで toc: false を設定すればよいのです。

TOC制御はHugo自身の機能、テーマ、ox-hugoの優先順位で実現を検討するのが良い。

基本的にはコンテンツそれ自体には手を加えない。フレームワークでやれることはフレームワークに任せるという方針で考えると上記の結論になります。

これはHugoとテーマがTOCに関する機能が十分にあるためです。

  • Hugo自身にTOC制御機能がそもそも備わっていること
  • テーマ：PaperMOdにその利用要否を制御する機能があること

この2つのTOCに関する機能に任せるのです。

そのため、 ox-hugo を使ってOrg modeからHugoサイトを構築する場合でも、TOCの制御はHugo本体やテーマの機能に任せる方が、良いと結論づけました。 他にもTOCのようなプレゼンテーションに関わる要素は、この方針にするほうがよりクリーンでメンテナンス性の高い構成になると思われます。

結果として、 hugo.toml で一元的に設定する方針が最もサイト全体のTOCの挙動を管理しやすくなると思いました。

それぞれのツールの役割分担を意識することが、快適なサイト運営に繋がると感じています。