TOC Depth

Per-heading control over how deep the table of contents goes.

What the toc-depth extension is for, how to enable it, and the smallest attribute that trims a section out of the contents.
Author

Mickaël CANOUIL, Ph.D.

Quarto’s toc-depth is a single number for the whole document. Set it to two and every fourth-level heading disappears, including the ones worth listing; set it to four and the contents fill with detail nobody needs.

toc-depth makes it per heading. An appendix can be listed without its subsections, a reference section can be listed in full, and a changelog can be left out of the contents entirely, all in one document.

Installation

quarto add mcanouil/quarto-toc-depth@0.6.1

This will install the extension under the _extensions subdirectory. If you are using version control, you will want to check in this directory.

Or install it from your editor with Quarto Wizard:

Visual Studio Code Positron VSCodium

Quick start

Enable the filter:

filters:
  - toc-depth

Then annotate the headings that need it:

## Appendix {toc-depth=1}

## Notes {toc-depth=0}

toc-depth=1 lists the heading but none of its subsections. toc-depth=0 leaves the heading out of the contents altogether, and unnumbers it.

The depth is counted from the heading that carries it, not from the top of the document.

Set a document-wide default and annotate only the exceptions:

extensions:
  toc-depth:
    default: 1

See the Reference for the rules, and the Examples for a contents list you can compare against the page.

Where it works

The filter applies Pandoc’s unlisted and unnumbered classes, which is the mechanism Quarto itself uses, so it works wherever those are honoured: HTML and RevealJS, LaTeX and PDF, Typst, and Word for numbering.

A format with no generated contents, plain markdown or PowerPoint, is unaffected.

Back to top