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 headings to include in the TOC — Example: #+toc: headlines 2 or :EXPORT_OPTIONS: toc:2.
• Whether you want all the headings in the TOC to be numbered or not — See org-hugo-export-with-section-numbers.
• Whether you want only some headings numbered (both in post body and the TOC) — Set the UNNUMBERED property of that heading to t.
• Whether you want to list the sub-headings only from the current heading in the post — Example: #+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 Org Info: Table of Contents 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 Org Info: Table of Contents for more information.

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.

• You can find examples of where this partial can be used in opengraph.html and twitter_cards.html partials, also used in the 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).

Hiding bullets when TOC has numbered headings #

Add this to the CSS to hide bullets in table of contents when the headings are numbered. Export options set like #+options: toc:t num:t will cause this.

/* Hide bullets in TOC when headings are numbered. */
.toc.has-section-numbers ul {
  list-style: none;
}