Headings

The .heading {content} {depth} ^{docs ↗} function creates a heading with fine-grained control over its behavior.

Unlike standard Markdown headings (#, ##, etc.), this function allows explicit control over numbering, page breaks, table of contents indexing, and custom identifiers.

Parameters

Parameter	Description	Accepts	Default
`content`	Inline content of the heading.	Inline content	Required
`depth`	Importance level of the heading (1 for H1, 6 for H6).	Integer (1-6)	Required
`ref`	Custom identifier for cross-referencing. If unset, the ID is automatically generated.	String	Unset
`numbered`	Whether the heading is numbered and has its position tracked in the document hierarchy. Actual numbering depends on the active `.numbering` configuration.	Boolean	`yes`
`indexed`	Whether the heading appears in the table of contents and navigation sidebar.	Boolean	`yes`
`breakpage`	Whether the heading triggers an automatic page break.	Boolean	`yes`

Basic usage

Example 1

This is equivalent to ## My heading in standard Markdown.

.heading {My heading} depth:{2}

My heading

Controlling numbering

You can create headings that are not tracked by the numbering system:

.heading {Appendix} depth:{1} numbered:{no}

Unlike decorative headings (#!), this approach lets you independently control whether the heading appears in the table of contents.

Controlling table of contents indexing

By default, headings appear in the table of contents and navigation sidebar of plain and paged documents. You can exclude a heading while still allowing it to be numbered:

.heading {Secret section} depth:{2} indexed:{no}

Conversely, you can include an unnumbered heading in the table of contents:

.heading {Acknowledgments} depth:{1} numbered:{no} indexed:{yes}

Disabling page breaks

By default, headings trigger automatic page breaks (when .autopagebreak is enabled). You can disable this for individual headings:

.heading {Continued} depth:{1} breakpage:{no}

Custom identifiers

You can assign a custom identifier for cross-referencing:

.heading {Introduction} depth:{2} ref:{intro}

Decorative headings

To prevent a heading from being numbered and from appearing in the table of contents, append a ! after the last # sign. For example: #!, ##!, ###!, etc.

Example 2

```markdown
.center
    #! My document

## Introduction

.loremipsum
```

A heading with all optional flags disabled via .heading is equivalent to a decorative heading:
.heading {My decorative heading} depth:{2} numbered:{no} indexed:{no} breakpage:{no}