Table of Contents

A table of contents (TOC) is an index of section and subsection titles that is automatically generated from the document’s structure.

Set the toc attribute

To enable the auto-generated TOC, you must set the toc attribute.

The toc attribute can be specified via the command line (-a toc),

TOC enabled via the CLI
$ asciidoctor -a toc adventure.adoc

or in the document header (:toc:).

TOC enabled via the document header
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc:

This journey begins on a bleary...

== Cavern Glow

The river rages through the cavern, rattling its content...

When no other options are specified, the TOC is inserted directly below the document header (document title, author, and revision lines), it has the title Table of Contents, and contains section 1 and section 2 level titles only.

Result: Setting the toc attribute

Fix image

Title

The toc-title attribute allows you to change the title of the table of contents.

Define a new TOC title
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc: (1)
:toc-title: Table of Adventures (2)

This journey begins on a bleary...

== Cavern Glow

The river rages through the cavern, rattling its content...
1 The toc attribute must be set in order to use toc-title.
2 The toc-title is set and assigned the value Table of Adventures in the document’s header.
Result: Define a new TOC title

Fix ex

Levels

By default, the TOC will display level 1 and level 2 section titles. You can set a different depth with the toclevels attribute.

Define a new toclevels value
= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon
:toc: (1)
:toclevels: 4 (2)

This journey begins on a bleary...

== Cavern Glow

The river rages through the cavern, rattling its content...

== The Ravages of Writing

Her finger socks had been vaporized by crystalline nuggets of...

=== A Recipe for Potion

Two fresh Burdockian leaves, harvested by the light of the teal moons...

==== Searching for Burdockian

Crawling through the twisted understory...
1 The toc attribute must be set in order to use toclevels.
2 toclevels is set and assigned the value 4 in the document header. The TOC will list the titles of the section 1, 2, 3, and 4 levels when the document is rendered.
Result: Define a new toclevels value

fix ex

Asciidoctor allows you to customize the title, number of levels, and document position of the table of contents. However, not all of the attributes are supported by all converters. See the TOC reference table to find out which attributes are available to each backend.