Position the TOC

By default, the table of contents is inserted directly below the document title, author, and revision lines when the toc attribute is set and its value is left empty or set to auto. This location can be changed by assigning one of the built-in positional values to the toc attribute. The values are:

  • left

  • right

  • preamble

  • macro

  • auto (default)

Display the TOC as a side column

When converting to HTML, you can position the TOC to the left or right of the main content column by assigning the value left or right to the toc attribute, respectively. The sidebar column containing the TOC is both fixed and scrollable.

Example 1. Assign the left value to toc
= The Intrepid Chronicles
Kismet Lee; B. Steppenwolf; Pax Draeke
:toc: left

== Certain Peril

Daylight trickles across the cobblestones...

=== A Recipe for Potion

We have to harvest the leaves by the light of the teal moons...

==== Searching for Ginseng

Crawling through the twisted understory...

== Dawn on the Plateau

Hanging from...

The result of Example 1 is displayed below.

Display the table of contents as a side column

This positioning is achieved using CSS and depends on support from the stylesheet.

The side positions (left and right) have a width requirement. These positions are only honored if there’s sufficient room on the screen to fit the sidebar column (typically at least 768px). If sufficient room available is not available (i.e., the screen width falls below the breakpoint), the TOC automatically shifts back to the center, appearing directly below the document title.
The TOC is always placed in the center in an embeddable HTML document, regardless of the value of the toc attribute.

Display the TOC beneath the preamble

When toc is assigned the built-in value preamble, the TOC is placed immediately below the preamble.

Example 2. Assign the preamble value to toc
= The Intrepid Chronicles
Kismet Lee; B. Steppenwolf; Pax Draeke
:toc: preamble

This adventure begins on a frigid morning.
We've run out of coffee beans, but leaving our office means venturing into certain peril.

== Certain Peril

Daylight trickles across the cobblestones...

== Dawn on the Plateau

Hanging from...

The result of Example 2 is displayed below.

Display the table of contents below the preamble
When using the preamble value, the TOC will not appear if your document does not have a preamble. To fix this problem, set the toc attribute to an empty value (i.e., leave the value empty) or assign it the value auto.

Use the TOC macro to position the TOC

To place the TOC in specific location in the document, assign the macro value to the toc attribute. Then, enter the table of contents block macro (i.e., TOC macro) on the line in your document where you want the TOC to appear. The TOC macro should only be used once in a document.

If the toc document attribute isn’t assigned the value macro, any TOC macro in the document will be ignored.

Example 3. Assign the macro value to toc
= The Intrepid Chronicles
Kismet Lee; B. Steppenwolf; Pax Draeke
:toc: macro (1)

== Certain Peril

toc::[] (2)

Daylight trickles across the cobblestones...

== Dawn on the Plateau

Hanging from...
1 The toc attribute must be set to macro to enable the use of the TOC macro.
2 In this example, the TOC macro is placed below the first section’s title, indicating that this is the location where the TOC will be displayed once the document is rendered.

The result of Example 3 is displayed below.

Display the table of contents using the TOC macro

Embeddable HTML, editor and previewer limitations

When AsciiDoc is converted to embeddable HTML (i.e., the header_footer option is false), there are only three valid values for the toc attribute:

  • auto

  • preamble

  • macro

All of the following environments convert AsciiDoc to embeddable HTML:

  • the file viewer on GitHub and GitLab

  • the AsciiDoc preview in an editor like Atom, Brackets or AsciidocFX

  • the Asciidoctor browser extensions

The side column placement (left or right) isn’t available in this mode. That’s because the embeddable HTML doesn’t have the outer framing (or the CSS) necessary to support a side column TOC.