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 does not generate the TOC using Org by default.

The only 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.
  • Whether you want to list the sub-headings only from the current heading in the postExample: #+toc: headlines 1 local.
  • Whether you want to list the sub-headings from a specified heading in the current post using the :target attribute. See the Org Manual – Table of Contents section for its example.

If you want to use the Org-generated TOC instead of the Hugo-generated one, do one of the following:

  1. As the default is to use the Hugo-generated TOC, the Org-generated TOC has to be enabled explicitly. To do this for all your ox-hugo generated posts, set the 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 the 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 the Table of Contents section in the Org manual for more info.

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

“Table of Contents” heading #

The “Table of Contents” heading is inserted as a plain HTML div element. Users can customize the looks of that div by setting CSS rules for .ox-hugo-toc .heading.

Here is an example CSS rule for that:

.ox-hugo-toc .heading {
    font-size: 1.8em;
    font-weight: bold;
    text-align: center;

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