Hugoサイトの目次(TOC)制御:PaperModテーマでの設定方法
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のブログでは3つの選択肢があります。 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がそれを適切な場所に表示してくれます。 ...