Heading

A section heading.

With headings, you can structure your document into sections. Each heading has a level, which starts at one and is unbounded upwards. This level indicates the logical role of the following content (section, subsection, etc.) A top-level heading indicates a top-level section of the document (not the document's title). To insert a title, use the title element instead.

Typst can automatically number your headings for you. To enable numbering, specify how you want your headings to be numbered with a numbering pattern or function.

Independently of the numbering, Typst can also automatically generate an outline of all headings for you. To exclude one or more headings from this outline, you can set the outlined parameter to false.

When writing a show rule that accesses the body field to create a completely custom look for headings, make sure to wrap the content in a block (which is implicitly sticky for headings through a built-in show-set rule). This prevents headings from becoming "orphans", i.e. remaining at the end of the page with the following content being on the next page.

Example

Syntax

Headings have dedicated syntax: They can be created by starting a line with one or multiple equals signs, followed by a space. The number of equals signs determines the heading's logical nesting depth. The offset field can be set to configure the starting depth.

Accessibility

Headings are important for accessibility, as they help users of Assistive Technologies (AT) like screen readers to navigate within your document. Screen reader users will be able to skip from heading to heading, or get an overview of all headings in the document.

To make your headings accessible, you should not skip heading levels. This means that you should start with a first-level heading. Also, when the previous heading was of level 3, the next heading should be of level 3 (staying at the same depth), level 4 (going exactly one level deeper), or level 1 or 2 (new hierarchically higher headings).

HTML export

As mentioned above, a top-level heading indicates a top-level section of the document rather than its title. This is in contrast to the HTML <h1> element of which there should be only one per document.

For this reason, in HTML export, a title element will turn into an <h1> and headings turn into <h2> and lower (a level 1 heading thus turns into <h2>, a level 2 heading into <h3>, etc).

#heading(
  level: auto | int,
  depth: int,
  offset: int,
  numbering: none | str | function,
  supplement: none | auto | content | function,
  outlined: bool,
  bookmarked: auto | bool,
  hanging-indent: auto | length,
  body
) -> content

Parameters