Struct HeadingElem

pub struct HeadingElem {
    pub body: Content,
    /* private fields */
}

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).

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}.

Example

#set heading(numbering: "1.a)")

= Introduction
In recent years, ...

== Preliminaries
To start, ...

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.

Fields

body: Content

Implementations

impl HeadingElem

pub fn new(body: Content) -> Self

Create a new instance of the element.

pub fn with_level(self, level: Smart<NonZeroUsize>) -> Self

Builder-style setter for the level field.

pub fn with_depth(self, depth: NonZeroUsize) -> Self

Builder-style setter for the depth field.

pub fn with_offset(self, offset: usize) -> Self

Builder-style setter for the offset field.

pub fn with_numbering(self, numbering: Option<Numbering>) -> Self

Builder-style setter for the numbering field.

pub fn with_supplement(self, supplement: Smart<Option<Supplement>>) -> Self

Builder-style setter for the supplement field.

pub fn with_outlined(self, outlined: bool) -> Self

Builder-style setter for the outlined field.

pub fn with_bookmarked(self, bookmarked: Smart<bool>) -> Self

Builder-style setter for the bookmarked field.

pub fn with_hanging_indent(self, hanging_indent: Smart<Length>) -> Self

Builder-style setter for the hanging-indent field.

pub fn push_level(&mut self, level: Smart<NonZeroUsize>)

Setter for the level field.

pub fn push_depth(&mut self, depth: NonZeroUsize)

Setter for the depth field.

pub fn push_offset(&mut self, offset: usize)

Setter for the offset field.

pub fn push_numbering(&mut self, numbering: Option<Numbering>)

Setter for the numbering field.

pub fn push_supplement(&mut self, supplement: Smart<Option<Supplement>>)

Setter for the supplement field.

pub fn push_outlined(&mut self, outlined: bool)

Setter for the outlined field.

pub fn push_bookmarked(&mut self, bookmarked: Smart<bool>)

Setter for the bookmarked field.

pub fn push_hanging_indent(&mut self, hanging_indent: Smart<Length>)

Setter for the hanging-indent field.

pub fn level(&self, styles: StyleChain<'_>) -> Smart<NonZeroUsize>

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

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

#show heading.where(level: 2): set text(red)

= Level 1
== Level 2

#set heading(offset: 1)
= Also level 2
== Level 3

pub fn depth(&self, styles: StyleChain<'_>) -> NonZeroUsize

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

This is set by the heading syntax, such that [== Heading] creates a heading with logical depth of 2, but actual level {offset + 2}. If you construct a heading manually, you should typically prefer this over setting the absolute level.

pub fn offset(&self, styles: StyleChain<'_>) -> usize

The starting offset of each heading’s {level}, used to turn its relative {depth} into its absolute {level}.

= Level 1

#set heading(offset: 1, numbering: "1.1")
= Level 2

#heading(offset: 2, depth: 2)[
  I'm level 4
]

pub fn numbering<'a>(&'a self, styles: StyleChain<'a>) -> &'a Option<Numbering>

How to number the heading. Accepts a numbering pattern or function.

#set heading(numbering: "1.a.")

= A section
== A subsection
=== A sub-subsection

pub fn supplement(&self, styles: StyleChain<'_>) -> Smart<Option<Supplement>>

A supplement for the heading.

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

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

#set heading(numbering: "1.", supplement: [Chapter])

= Introduction <intro>
In @intro, we see how to turn
Sections into Chapters. And
in @intro[Part], it is done
manually.

pub fn outlined(&self, styles: StyleChain<'_>) -> bool

Whether the heading should appear in the [outline].

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

#outline()

#heading[Normal]
This is a normal heading.

#heading(outlined: false)[Hidden]
This heading does not appear
in the outline.

pub fn bookmarked(&self, styles: StyleChain<'_>) -> Smart<bool>

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

The default value of {auto} indicates that the heading will only appear in the exported PDF’s outline if its outlined property is set to {true}, that is, if it would also be listed in Typst’s [outline]. Setting this property to either {true} (bookmark) or {false} (don’t bookmark) bypasses that behavior.

#heading[Normal heading]
This heading will be shown in
the PDF's bookmark outline.

#heading(bookmarked: false)[Not bookmarked]
This heading won't be
bookmarked in the resulting
PDF.

pub fn hanging_indent(&self, styles: StyleChain<'_>) -> Smart<Length>

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

The default value of {auto} indicates that the subsequent heading lines will be indented based on the width of the numbering.

#set heading(numbering: "1.")
#heading[A very, very, very, very, very, very long heading]

pub fn level_in(styles: StyleChain<'_>) -> Smart<NonZeroUsize>

Access the level field in the given style chain.

pub fn depth_in(styles: StyleChain<'_>) -> NonZeroUsize

Access the depth field in the given style chain.

pub fn offset_in(styles: StyleChain<'_>) -> usize

Access the offset field in the given style chain.

pub fn numbering_in(styles: StyleChain<'_>) -> &Option<Numbering>

Access the numbering field in the given style chain.

pub fn supplement_in(styles: StyleChain<'_>) -> Smart<Option<Supplement>>

Access the supplement field in the given style chain.

pub fn outlined_in(styles: StyleChain<'_>) -> bool

Access the outlined field in the given style chain.

pub fn bookmarked_in(styles: StyleChain<'_>) -> Smart<bool>

Access the bookmarked field in the given style chain.

pub fn hanging_indent_in(styles: StyleChain<'_>) -> Smart<Length>

Access the hanging-indent field in the given style chain.

pub fn set_level(level: Smart<NonZeroUsize>) -> Property

Create a style property for the level field.

pub fn set_depth(depth: NonZeroUsize) -> Property

Create a style property for the depth field.

pub fn set_offset(offset: usize) -> Property

Create a style property for the offset field.

pub fn set_numbering(numbering: Option<Numbering>) -> Property

Create a style property for the numbering field.

pub fn set_supplement(supplement: Smart<Option<Supplement>>) -> Property

Create a style property for the supplement field.

pub fn set_outlined(outlined: bool) -> Property

Create a style property for the outlined field.

pub fn set_bookmarked(bookmarked: Smart<bool>) -> Property

Create a style property for the bookmarked field.

pub fn set_hanging_indent(hanging_indent: Smart<Length>) -> Property

Create a style property for the hanging-indent field.

impl HeadingElem

pub fn resolve_level(&self, styles: StyleChain<'_>) -> NonZeroUsize

Trait Implementations

impl Capable for HeadingElem

fn vtable(capability: TypeId) -> Option<NonNull<()>>

Get the pointer to the vtable for the given capability / trait.

impl Clone for HeadingElem

fn clone(&self) -> HeadingElem

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Construct for HeadingElem

fn construct(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Content>

Construct an element from the arguments.

impl Debug for HeadingElem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Fields for HeadingElem

type Enum = Fields

An enum with the fields of the element.

fn has(&self, id: u8) -> bool

Whether the element has the given field set.

fn field(&self, id: u8) -> Result<Value, FieldAccessError>

Get the field with the given field ID.

fn field_with_styles( &self, id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID in the presence of styles.

fn field_from_styles( id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID from the styles.

fn materialize(&mut self, styles: StyleChain<'_>)

Resolve all fields with the styles and save them in-place.

fn fields(&self) -> Dict

Get the fields of the element.

impl Hash for HeadingElem

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for HeadingElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for HeadingElem

fn data() -> &'static NativeElementData

Get the element data for the native Rust element.

fn elem() -> Element

where Self: Sized,

Get the element for the native Rust element.

fn pack(self) -> Content

where Self: Sized,

Pack the element into type-erased content.

impl PartialEq for HeadingElem

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Repr for HeadingElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for HeadingElem

fn set(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Styles>

Parse relevant arguments into style properties for this element.