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.