A table of contents provides a quick overview of your document by displaying links to headings in a visual hierarchy. Readers can click on any entry to jump directly to that section. You can see a table of contents right now in the right sidebar, or at the end of the page if you’re on a mobile device.

You can display a table of contents through the .tableofcontents ^{docs ↗} function.

Basic usage

The function accepts the following optional parameters:

Parameter	Description	Accepts	Default
`title`	Title that precedes the table of contents. If unset, it is automatically localized.	Inline content	Automatically localized if `.doclang`’s locale is supported (e.g., `Table of Contents` for English)
`maxdepth`	Maximum heading level to display. For example, `maxdepth:{2}` collects `#` and `##` headings, but not `###` or deeper.	Integer	`3`

Example 1

.tableofcontents maxdepth:{2}

## A

...

### A.A

...

### A.B

...

## B

...

## C

### C.A

#### C.A.A

...

Behavior by document type

The table of contents adapts to different document types:

In paged and slides documents, each entry also displays the corresponding page number.
In slides documents, the table of contents has a constrained height and becomes vertically scrollable when content overflows.

Theming

Layout themes greatly influence the appearance of the table of contents.

Example 2

Table of contents with minimal theme — ‘minimal’ theme

Ignoring specific headings

Sometimes you want certain headings to appear in your document but not in the table of contents. Decorative headings serve this purpose: they are not numbered and are excluded from the table of contents.

To mark a heading as decorative, append ! to the last # sign:

##! A decorative heading

Custom numbering

You can customize how headings are numbered in the table of contents via the .numbering function. See Numbering for more information.

Heading options

The heading that precedes the table of contents can be customized with the following parameters:

Parameter	Description	Accepts	Default
`headingdepth`	Depth of the heading that precedes the table of contents.	Integer	Depends on document type (1 for most, 3 for `docs`)
`breakpage`	Whether the heading triggers an automatic page break.	Boolean	`yes`
`numberheading`	Whether the heading should be numbered and have its position tracked in the document hierarchy.	Boolean	`no`
`indexheading`	Whether the heading should be included in the table of contents itself. Implicitly enables `numberheading`.	Boolean	`no`

Focusing entries

The focus parameter highlights a specific entry in the table of contents, drawing attention to the current section.

Example 3

Adding focus:{A.B} to the previous example highlights that entry:

.tableofcontents maxdepth:{2} focus:{A.B}

This feature is particularly useful in presentations, where you might want to show a mini table of contents at the beginning of each chapter to orient your audience.

For slide presentations, you can combine focus with markers to create elegant chapter navigation. The .marker function creates an invisible level-0 heading, which is not normally possible with the standard #-based syntax.

Here is a practical pattern for chapter slides:

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

You can then invoke it with .chapter {My chapter} at the start of each section. Setting maxdepth:{0} ensures only markers appear in the table of contents, creating a clean chapter-level overview rather than showing all headings.

On this page

Table of contents