{"route":"/en-US-v0.14.1/reference/model/heading/","title":"Heading","description":"Documentation for the `heading` function.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"example","name":"Example","children":[]},{"id":"syntax","name":"Syntax","children":[]},{"id":"accessibility","name":"Accessibility","children":[]},{"id":"html-export","name":"HTML export","children":[]},{"id":"parameters","name":"Parameters","children":[{"id":"parameters-level","name":"level","children":[]},{"id":"parameters-depth","name":"depth","children":[]},{"id":"parameters-offset","name":"offset","children":[]},{"id":"parameters-numbering","name":"numbering","children":[]},{"id":"parameters-supplement","name":"supplement","children":[]},{"id":"parameters-outlined","name":"outlined","children":[]},{"id":"parameters-bookmarked","name":"bookmarked","children":[]},{"id":"parameters-hanging-indent","name":"hanging-indent","children":[]},{"id":"parameters-body","name":"body","children":[]}]}],"body":{"kind":"func","content":{"path":[],"name":"heading","title":"Heading","keywords":[],"oneliner":"A section heading.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

A section heading.

\n

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

\n

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

\n

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

\n

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

\n

Example

\n
#set heading(numbering: "1.a)")\n\n= Introduction\nIn recent years, ...\n\n== Preliminaries\nTo start, ...\n
\"Preview\"
\n

Syntax

\n

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

\n

Accessibility

\n

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

\n

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

\n

HTML export

\n

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

\n

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

"}],"self":false,"params":[{"name":"level","details":[{"kind":"html","content":"

The absolute nesting depth of the heading, starting from one. If set\nto auto, it is computed from offset + depth.

\n

This is primarily useful for usage in show rules\n(either with where selectors or by accessing the\nlevel directly on a shown heading).

"},{"kind":"example","content":{"body":"
#show heading.where(level: 2): set text(red)\n\n= Level 1\n== Level 2\n\n#set heading(offset: 1)\n= Also level 2\n== Level 3\n
\"Preview\"
","title":null}}],"types":["auto","int"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"depth","details":[{"kind":"html","content":"

The relative nesting depth of the heading, starting from one. This is\ncombined with offset to compute the actual level.

\n

This is set by the heading syntax, such that == Heading creates a\nheading with logical depth of 2, but actual level offset + 2. If you\nconstruct a heading manually, you should typically prefer this over\nsetting the absolute level.

"}],"types":["int"],"strings":[],"default":"1","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"offset","details":[{"kind":"html","content":"

The starting offset of each heading's level, used to turn its\nrelative depth into its absolute level.

"},{"kind":"example","content":{"body":"
= Level 1\n\n#set heading(offset: 1, numbering: "1.1")\n= Level 2\n\n#heading(offset: 2, depth: 2)[\n  I'm level 4\n]\n
\"Preview\"
","title":null}}],"types":["int"],"strings":[],"default":"0","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"numbering","details":[{"kind":"html","content":"

How to number the heading. Accepts a\nnumbering pattern or function taking multiple numbers.

"},{"kind":"example","content":{"body":"
#set heading(numbering: "1.a.")\n\n= A section\n== A subsection\n=== A sub-subsection\n
\"Preview\"
","title":null}}],"types":["none","str","function"],"strings":[],"default":"none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"supplement","details":[{"kind":"html","content":"

A supplement for the heading.

\n

For references to headings, this is added before the referenced number.

\n

If a function is specified, it is passed the referenced heading and\nshould return content.

"},{"kind":"example","content":{"body":"
#set heading(numbering: "1.", supplement: [Chapter])\n\n= Introduction <intro>\nIn @intro, we see how to turn\nSections into Chapters. And\nin @intro[Part], it is done\nmanually.\n
\"Preview\"
","title":null}}],"types":["none","auto","content","function"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"outlined","details":[{"kind":"html","content":"

Whether the heading should appear in the outline.

\n

Note that this property, if set to true, ensures the heading is also\nshown as a bookmark in the exported PDF's outline (when exporting to\nPDF). To change that behavior, use the bookmarked property.

"},{"kind":"example","content":{"body":"
#outline()\n\n#heading[Normal]\nThis is a normal heading.\n\n#heading(outlined: false)[Hidden]\nThis heading does not appear\nin the outline.\n
\"Preview\"
","title":null}}],"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"bookmarked","details":[{"kind":"html","content":"

Whether the heading should appear as a bookmark in the exported PDF's\noutline. Doesn't affect other export formats, such as PNG.

\n

The default value of auto indicates that the heading will only\nappear in the exported PDF's outline if its outlined property is set\nto true, that is, if it would also be listed in Typst's outline.\nSetting this property to either true (bookmark) or false (don't\nbookmark) bypasses that behavior.

"},{"kind":"example","content":{"body":"
#heading[Normal heading]\nThis heading will be shown in\nthe PDF's bookmark outline.\n\n#heading(bookmarked: false)[Not bookmarked]\nThis heading won't be\nbookmarked in the resulting\nPDF.\n
\"Preview\"
","title":null}}],"types":["auto","bool"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"hanging-indent","details":[{"kind":"html","content":"

The indent all but the first line of a heading should have.

\n

The default value of auto uses the width of the numbering as indent\nif the heading is aligned at the start of the text\ndirection, and no indent for center and other alignments.

"},{"kind":"example","content":{"body":"
#set heading(numbering: "1.")\n= A very, very, very, very, very, very long heading\n\n#show heading: set align(center)\n== A very long heading\\ with center alignment\n
\"Preview\"
","title":null}}],"types":["auto","length"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"body","details":[{"kind":"html","content":"

The heading's title.

"}],"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["content"],"scope":[]}}}