Reference

Every rule the toc-depth extension applies.

The complete toc-depth behaviour: the heading attribute, the document default, how the cascade works, and what each format does with it.

Enabling the filter

filters:
  - toc-depth

The attribute

## Section {toc-depth=1}
The attribute accepted on any heading.
Attribute Type Description
toc-depth non-negative integer How many levels below this heading appear in the contents. 0 removes the heading itself.

The depth is relative to the heading that carries it. toc-depth=2 on a level-two heading lists that heading and its level-three children, and stops there, whatever level the heading sits at.

What each value does.
Value Effect on the heading Effect on its subtree
0 Removed from the contents, and unnumbered. Removed and unnumbered, all the way down.
1 Listed. Not listed.
2 Listed. Direct children listed; anything deeper is not.
n Listed. Listed down to n - 1 levels below it.

The document default

extensions:
  toc-depth:
    default: 1
Document and project options.
Option Type Default Description
default non-negative integer Applied to a heading with no explicit toc-depth that no other heading’s depth already covers.

An attribute on a heading always beats the document default. A heading already inside another heading’s depth follows that depth instead, so the default applies where the cascade does not reach.

The cascade

A heading’s depth applies to the headings beneath it, until one of them sets its own.

An explicit toc-depth replaces the depth in force rather than nesting inside it, and the heading carrying it is listed whatever its parent asked for.

# Parent {toc-depth=1}

## Child A

## Child B {toc-depth=3}

### Grandchild B1

## Child C

Child A is hidden, inherited from Parent. Child B carries its own attribute, so it is listed, and Grandchild B1 with it.

Child C is listed too. One depth is in force at a time, and the depth Parent set is not restored once Child B has replaced it, so a heading after an override falls back to the document default, or to Quarto’s own behaviour when there is none. Annotate the headings that follow an override when they need a depth of their own.

Quarto’s own toc-depth

Quarto has a document option of the same name, and it is applied first.

toc-depth: 3

That option decides how deep the contents can go at all; this extension then removes entries within it. The two compose in one direction only: a heading attribute can narrow what Quarto would have listed, and cannot widen it beyond Quarto’s own limit.

Caution

toc-depth=3 on a level two heading asks for its level four descendants, and Quarto’s default of 3 has already excluded everything below level three. Raise the document option when a heading attribute asks for more than it allows.

Validation

Validation rules.
Rule On failure
The attribute is a number. Warns, and the heading is treated as carrying no attribute.
default is a number. Warns, and the document default is left unset.
The value is not negative. Warns, and the value is clamped to 0.

A fractional value is accepted as written and compared against whole levels, so 2.5 does what 3 does.

Format support

The filter sets Pandoc’s unlisted and unnumbered classes on headings, which is the mechanism Quarto uses itself.

What each format does with the classes.
Format Contents Numbering
HTML, RevealJS Yes Yes
LaTeX, PDF Yes Yes
Typst Yes Yes
Word No: Word fills the contents in from the heading styles when it opens the file Yes
Markdown, PowerPoint No contents to affect

Limitations

  • The extension controls what the contents list, not how it is laid out.
  • toc-depth=0 also unnumbers the heading. The two go together in Pandoc’s model and cannot be separated here.
  • Word honours the numbering but not the contents: the file carries a field, and Word fills it in from the heading styles, which unlisted leaves alone.
Back to top