Offset Headings

Shift heading levels, per heading or per document.

What the offset-headings extension is for, how it differs from shift-heading-level-by, and the smallest attribute that moves a heading.
Author

Mickaël CANOUIL, Ph.D.

A section written to stand alone starts at level one, and dropping it into a larger document puts it above everything around it. Pandoc’s shift-heading-level-by moves all of them by the same amount, and it runs after every filter has finished, so no extension can see the result and no single heading can be treated differently.

offset-headings does the shifting during filtering instead. One heading, one subtree, or the whole document, with the offsets composing rather than replacing one another.

Installation

quarto add mcanouil/quarto-offset-headings@0.4.2

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:
  - offset-headings

Shift one heading and everything under it:

## Section {offset-headings-by="1"}

### Subsection

Both move down a level; the cascade is on by default.

Or shift the whole document:

extensions:
  offset-headings:
    by: 1

The two add together, so a per-heading offset adjusts the document offset rather than replacing it.

See the Reference for every option, and the Examples for headings at levels you can inspect.

Where it works

Every output format. The filter rewrites Pandoc’s heading elements, so HTML, PDF, Typst, and Word all get the same levels.

Warning

Quarto applies a shift-heading-level-by: -1 of its own to Typst, and to PDF when sections are numbered, whenever a document has no level one heading. That runs after every filter and lands on top of these levels. Set shift-heading-level-by: 0 to stop it; the Reference explains why that is the only reliable fix.

Back to top