Table of contents

Usage

Create your Markdown the way you normally would with the appropriate headings. Here is some example content:

<!-- Your front matter up here -->

## Introduction

One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.

## My Heading

He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.

### My Subheading

A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops

Hugo will take this Markdown and create a table of contents from ## Introduction, ## My Heading, and ### My Subheading and then store it in the page variable.TableOfContents.

The built-in .TableOfContents variables outputs a <nav id="TableOfContents"> element with a child <ul>, whose child <li> elements begin with appropriate HTML headings. See the available settings to configure what heading levels you want to include in TOC.

Template example: basic TOC

The following is an example of a very basic single page template:

{{ define "main" }}
  <main>
    <article>
      <header>
        <h1>{{ .Title }}</h1>
      </header>
      {{ .Content }}
    </article>
    <aside>
      {{ .TableOfContents }}
    </aside>
  </main>
{{ end }}

Template example: TOC partial

The following is a partial template that adds slightly more logic for page-level control over your table of contents. It assumes you are using a toc field in your content’s front matter that, unless specifically set to false, will add a TOC to any page with a .WordCount (see Page Variables) greater than 400. This example also demonstrates how to use conditionals in your templating:

{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
    <header>
    <h2>{{ .Title }}</h2>
    </header>
    {{ .TableOfContents }}
</aside>
{{ end }}

Usage with AsciiDoc

Hugo supports table of contents with AsciiDoc content format.

In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable .TableOfContents in the same way as described for Markdown. See example below:

// <!-- Your front matter up here -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] configuration key
:toclevels: 4

== Introduction

One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.

== My Heading

He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.

=== My Subheading

A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops

Hugo will take this AsciiDoc and create a table of contents store it in the page variable .TableOfContents, in the same as described for Markdown.