Table of contents

A table of contents is a quick summary of the document, where links to headings are displayed in a visual hierarchy.

• paged documents also display the corresponding page number.
• slides documents constrain the maximum height, making it vertically scrollable.

A ToC can be displayed through the .tableofcontents function, with the following optional parameters:

Parameter	Description	Accepts	Default
title	Title that precedes the ToC. If unset, it's automatically localized.	Inline content	Automatically localized if .doclang's locale is supported. (e.g. Table of Contents for English)
maxdepth	Maximum level of headings to display. e.g. maxdepth = 2 collects # This and ## This, but not ### This.	Integer	3
focus	If set, adds focus to the item with the same text as this argument. Inline style (strong, emphasis, etc.) is ignored when comparing the text content.	Inline content	(none)

.tableofcontents maxdepth:{2}

# A

...

## A.A

...

## A.B

...

# B

...

# C

## C.A

### C.A.A

...

 

Layout themes greatly influence the look of table of contents:

minimal theme

Ignoring specific headings

Decorative headings are not numbered and do not appear in table of contents.
A heading is marked as decorative if a ! is appended to the last # sign. For example #!, ##!, ###!, etc.

##! A decorative heading

Decorative headings can appear in table of contents if the optional includeunnumbered parameter is enabled:

.tableofcontents includeunnumbered:{yes}

Custom numbering

A custom numbering format can be set via .numbering. See Numbering for more.

Focusing & markers

If focus:{A.B} is added to the previous example:

Focusing may be particularly useful in slides with mini-ToCs at the beginning of each new chapter.
In that case you may consider defining a function like this:

.function {chapter}
    name:
    .tableofcontents maxdepth:{0} focus:{.name}
    .marker {.name}

That can be invoked by .chapter {My chapter}.

What .marker does is creating an invisible level-0 heading (which isn't usually possible with the standard #-based heading syntax).
Setting maxdepth:{0} displays only markers in the ToC, ignoring other headings.