Table of Contents

Hugo can automatically parse the Markdown content and auto-create a Table of Contents. See its documentation on Table of Contents. So ox-hugo doesn’t generate the Org-parsed TOC by default.

The advantage of using Hugo-generated TOC is that it does not clutter the Markdown source.

Though, the advantage of Org-generated TOC is that you get finer control on:

  • Where to include the TOC — Location of the #+toc keyword in the Org content.
  • How many headlines to include in the TOC — Example: #+toc: headlines 2 or :EXPORT_OPTIONS: toc:2.
  • Whether you want all the headlines in the TOC to be numbered or not — See org-hugo-export-with-section-numbers.
  • Whether you want only some headlines numbered (both in post body and the TOC) — Set the UNNUMBERED property of that headline to t.

If you’d like to use the Org-generated TOC instead of the Hugo-generated one, you can do it one of these many ways:

  1. The default is to use the Hugo-generated TOC. But that can be changed by setting org-hugo-export-with-toc variable to a non-nil value, like t or 2.
  2. Org-generated TOC can be enabled per-post by either setting EXPORT_OPTIONS subtree property (for subtree-based exports) or the OPTIONS keyword (for file-based exports) to a non-nil value, like toc:t or toc:2.
  3. Above two options will insert the TOC between the front-matter and the Markdown content. If you’d like to insert the Org-generated TOC anywhere else in the post, you can do it using the #+toc keyword.. Example: #+toc: headlines 2.

See Org manual Table of Contents section for more info.

Note that ox-hugo does not support #+toc: listings and #+toc: tables.

Excluding Org-generated TOC from Hugo summaries #

As mentioned above, if you use Hugo-generated TOC, the advantage is that the TOC is not inserted physically in the content Markdown file.

But with the Org-generated TOC, it will be. The disadvantage of that is that the .Summary in Hugo will consider the TOC! So your TOC will show up in places you don’t expect.. like summaries in post lists, in twitter cards, etc.

But.. there’s a way to fix that, because ox-hugo inserts a special comment <!--endtoc--> at the end of the inserted TOC.

Using that special comment, this summary_minus_toc.html partial tries to get the “summary you mean”. This partial is used by the ox-hugo test site.

Note that you would need to use the summary_minus_toc.html partial wherever you do not intend to have TOC included in the summary (for example, in the Opengraph og:description meta tag).

Fork me on GitHub