Headings

Updated Apr 28, 2026

Headings automatically generate anchor IDs for linking.

Auto-generated IDs

## My Heading

Renders as <h2 id="my-heading">My Heading</h2>. IDs are generated using GitHub-compatible slugging.

Override the auto-generated ID with [#custom-id] syntax:

## My Heading [#custom-id]

This generates <h2 id="custom-id">My Heading</h2>. Link to it with #custom-id. This heading itself uses [#custom-ids].

Use h2–h4 for content structure. The h1 is reserved for the page title.

Deeper headings (h5, h6) are supported but won't appear in the table of contents.

Control whether headings appear in the table of contents using annotations.

Hide a heading from the TOC while keeping it visible in the rendered output:

## Visible Heading [!toc]

The heading renders normally on the page but is excluded from the table of contents.

Create a TOC-only heading that appears in the table of contents but not in the rendered output:

## Hidden Heading [toc]

The heading appears in the TOC for navigation but is removed from the page content.

Headings with IDs show a link icon on hover. Click to copy the anchor URL for sharing.

Insert a table of contents anywhere in your content using the ::toc directive:

::toc

Limit the depth with maxLevel:

::toc{maxLevel=2}

Renders as: