Struct ParElem

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

A logical subdivison of textual content.

Typst automatically collects inline-level elements into paragraphs. Inline-level elements include [text], horizontal spacing, boxes, and inline equations.

To separate paragraphs, use a blank line (or an explicit [parbreak]). Paragraphs are also automatically interrupted by any block-level element (like [block], [place], or anything that shows itself as one of these).

The par element is primarily used in set rules to affect paragraph properties, but it can also be used to explicitly display its argument as a paragraph of its own. Then, the paragraph’s body may not contain any block-level content.

Boxes and blocks

As explained above, usually paragraphs only contain inline-level content. However, you can integrate any kind of block-level content into a paragraph by wrapping it in a [box].

Conversely, you can separate inline-level content from a paragraph by wrapping it in a [block]. In this case, it will not become part of any paragraph at all. Read the following section for an explanation of why that matters and how it differs from just adding paragraph breaks around the content.

What becomes a paragraph?

When you add inline-level content to your document, Typst will automatically wrap it in paragraphs. However, a typical document also contains some text that is not semantically part of a paragraph, for example in a heading or caption.

The rules for when Typst wraps inline-level content in a paragraph are as follows:

• All text at the root of a document is wrapped in paragraphs.

• Text in a container (like a block) is only wrapped in a paragraph if the container holds any block-level content. If all of the contents are inline-level, no paragraph is created.

In the laid-out document, it’s not immediately visible whether text became part of a paragraph. However, it is still important for various reasons:

• Certain paragraph styling like first-line-indent will only apply to proper paragraphs, not any text. Similarly, par show rules of course only trigger on paragraphs.

• A proper distinction between paragraphs and other text helps people who rely on assistive technologies (such as screen readers) navigate and understand the document properly. Currently, this only applies to HTML export since Typst does not yet output accessible PDFs, but support for this is planned for the near future.

• HTML export will generate a <p> tag only for paragraphs.

When creating custom reusable components, you can and should take charge over whether Typst creates paragraphs. By wrapping text in a [block] instead of just adding paragraph breaks around it, you can force the absence of a paragraph. Conversely, by adding a [parbreak] after some content in a container, you can force it to become a paragraph even if it’s just one word. This is, for example, what non-tight lists do to force their items to become paragraphs.

Example

#set par(
  first-line-indent: 1em,
  spacing: 0.65em,
  justify: true,
)

We proceed by contradiction.
Suppose that there exists a set
of positive integers $a$, $b$, and
$c$ that satisfies the equation
$a^n + b^n = c^n$ for some
integer value of $n > 2$.

Without loss of generality,
let $a$ be the smallest of the
three integers. Then, we ...

Fields

body: Content

Implementations

impl ParElem

pub fn new(body: Content) -> Self

Create a new instance of the element.

pub fn with_leading(self, leading: Length) -> Self

Builder-style setter for the leading field.

pub fn with_spacing(self, spacing: Length) -> Self

Builder-style setter for the spacing field.

pub fn with_justify(self, justify: bool) -> Self

Builder-style setter for the justify field.

pub fn with_linebreaks(self, linebreaks: Smart<Linebreaks>) -> Self

Builder-style setter for the linebreaks field.

pub fn with_first_line_indent(self, first_line_indent: FirstLineIndent) -> Self

Builder-style setter for the first-line-indent field.

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

Builder-style setter for the hanging-indent field.

pub fn push_leading(&mut self, leading: Length)

Setter for the leading field.

pub fn push_spacing(&mut self, spacing: Length)

Setter for the spacing field.

pub fn push_justify(&mut self, justify: bool)

Setter for the justify field.

pub fn push_linebreaks(&mut self, linebreaks: Smart<Linebreaks>)

Setter for the linebreaks field.

pub fn push_first_line_indent(&mut self, first_line_indent: FirstLineIndent)

Setter for the first-line-indent field.

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

Setter for the hanging-indent field.

pub fn leading(&self, styles: StyleChain<'_>) -> <Length as Resolve>::Output

The spacing between lines.

Leading defines the spacing between the bottom edge of one line and the top edge of the following line. By default, these two properties are up to the font, but they can also be configured manually with a text set rule.

By setting top edge, bottom edge, and leading, you can also configure a consistent baseline-to-baseline distance. You could, for instance, set the leading to {1em}, the top-edge to {0.8em}, and the bottom-edge to {-0.2em} to get a baseline gap of exactly {2em}. The exact distribution of the top- and bottom-edge values affects the bounds of the first and last line.

pub fn spacing(&self, styles: StyleChain<'_>) -> <Length as Resolve>::Output

The spacing between paragraphs.

Just like leading, this defines the spacing between the bottom edge of a paragraph’s last line and the top edge of the next paragraph’s first line.

When a paragraph is adjacent to a [block] that is not a paragraph, that block’s above or below property takes precedence over the paragraph spacing. Headings, for instance, reduce the spacing below them by default for a better look.

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

Whether to justify text in its line.

Hyphenation will be enabled for justified paragraphs if the text function’s hyphenate property is set to {auto} and the current language is known.

Note that the current alignment still has an effect on the placement of the last line except if it ends with a justified line break.

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

How to determine line breaks.

When this property is set to {auto}, its default value, optimized line breaks will be used for justified paragraphs. Enabling optimized line breaks for ragged paragraphs may also be worthwhile to improve the appearance of the text.

#set page(width: 207pt)
#set par(linebreaks: "simple")
Some texts feature many longer
words. Those are often exceedingly
challenging to break in a visually
pleasing way.

#set par(linebreaks: "optimized")
Some texts feature many longer
words. Those are often exceedingly
challenging to break in a visually
pleasing way.

pub fn first_line_indent(&self, styles: StyleChain<'_>) -> FirstLineIndent

The indent the first line of a paragraph should have.

By default, only the first line of a consecutive paragraph will be indented (not the first one in the document or container, and not paragraphs immediately following other block-level elements).

If you want to indent all paragraphs instead, you can pass a dictionary containing the amount of indent as a length and the pair {all: true}. When all is omitted from the dictionary, it defaults to {false}.

By typographic convention, paragraph breaks are indicated either by some space between paragraphs or by indented first lines. Consider

• reducing the paragraph spacing to the leading using {set par(spacing: 0.65em)}
• increasing the block spacing (which inherits the paragraph spacing by default) to the original paragraph spacing using {set block(spacing: 1.2em)}

#set block(spacing: 1.2em)
#set par(
  first-line-indent: 1.5em,
  spacing: 0.65em,
)

The first paragraph is not affected
by the indent.

But the second paragraph is.

#line(length: 100%)

#set par(first-line-indent: (
  amount: 1.5em,
  all: true,
))

Now all paragraphs are affected
by the first line indent.

Even the first one.

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

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

#set par(hanging-indent: 1em)

#lorem(15)

pub fn leading_in(styles: StyleChain<'_>) -> <Length as Resolve>::Output

Access the leading field in the given style chain.

pub fn spacing_in(styles: StyleChain<'_>) -> <Length as Resolve>::Output

Access the spacing field in the given style chain.

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

Access the justify field in the given style chain.

pub fn linebreaks_in(styles: StyleChain<'_>) -> Smart<Linebreaks>

Access the linebreaks field in the given style chain.

pub fn first_line_indent_in(styles: StyleChain<'_>) -> FirstLineIndent

Access the first-line-indent field in the given style chain.

pub fn hanging_indent_in(styles: StyleChain<'_>) -> <Length as Resolve>::Output

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

pub fn set_leading(leading: Length) -> Property

Create a style property for the leading field.

pub fn set_spacing(spacing: Length) -> Property

Create a style property for the spacing field.

pub fn set_justify(justify: bool) -> Property

Create a style property for the justify field.

pub fn set_linebreaks(linebreaks: Smart<Linebreaks>) -> Property

Create a style property for the linebreaks field.

pub fn set_first_line_indent(first_line_indent: FirstLineIndent) -> Property

Create a style property for the first-line-indent field.

pub fn set_hanging_indent(hanging_indent: Length) -> Property

Create a style property for the hanging-indent field.

Trait Implementations

impl Capable for ParElem

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

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

impl Clone for ParElem

fn clone(&self) -> ParElem

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Construct for ParElem

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

Construct an element from the arguments.

impl Debug for ParElem

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

Formats the value using the given formatter.

impl Fields for ParElem

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 ParElem

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 ParElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for ParElem

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 NativeScope for ParElem

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl PartialEq for ParElem

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 ParElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for ParElem

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

Parse relevant arguments into style properties for this element.