July 17, 2019

goHugo Table of Contents

Quick explanation of using Hugo’s shortcodes for a Table of Contents.

Hugo (already) builds a table of contents during execution. It looks like it’s up to the theme to invoke it … and the Binario theme doesn’t by default. The instructions given invoke it on all posts - this is not what I want, since, my old posts won’t be laid out correctly for it. In my last post I learned to use Hugo’s ShortCodes to add HTML fragments to posts. I can invoke a new ShortCode with {{<TofC>}} and create a file /themes/???/layouts/shortcodes/TofC.html containing …

<aside style="float: right;">
    {{ .Page.TableOfContents }}
</aside>

… to get a table of contents where I want it.

To demonstrate this, I added a table of contents to my Mermaid post and an older post about using GoGS. In both cases, I had to change the ## section headers to # to get the lists correct.¹

Either Pandoc or a MarkDown linter told me that only page titles should use # and that section headings should use ##. I hadn’t cared until now, so, I went along with whatever until now.
^[return]