Struct RefElem 

pub struct RefElem {
    pub target: Label,
    pub supplement: Settable<Self, 1u8>,
    pub form: Settable<Self, 2u8>,
    pub citation: Option<Option<Packed<CiteElem>>>,
    pub element: Option<Option<Content>>,
}

A reference to a label or bibliography.

Takes a label and cross-references it. There are two kind of references, determined by its form: {"normal"} and {"page"}.

The default, a {"normal"} reference, produces a textual reference to a label. For example, a reference to a heading will yield an appropriate string such as “Section 1” for a reference to the first heading. The word “Section” depends on the lang setting and is localized accordingly. The references are also links to the respective element. Reference syntax can also be used to [cite] from a bibliography.

As the default form requires a supplement and numbering, the label must be attached to a referenceable element. Referenceable elements include headings, figures, equations, and footnotes. To create a custom referenceable element like a theorem, you can create a figure of a custom kind and write a show rule for it. In the future, there might be a more direct way to define a custom referenceable element.

If you just want to link to a labelled element and not get an automatic textual reference, consider using the [link] function instead.

A {"page"} reference produces a page reference to a label, displaying the page number at its location. You can use the page’s supplement to modify the text before the page number. Unlike a {"normal"} reference, the label can be attached to any element.

Example

#set page(numbering: "1")
#set heading(numbering: "1.")
#set math.equation(numbering: "(1)")

= Introduction <intro>
Recent developments in
typesetting software have
rekindled hope in previously
frustrated researchers. @distress
As shown in @results (see
#ref(<results>, form: "page")),
we ...

= Results <results>
We discuss our approach in
comparison with others.

== Performance <perf>
@slow demonstrates what slow
software looks like.
$ T(n) = O(2^n) $ <slow>

#bibliography("works.bib")

Syntax

This function also has dedicated syntax: A {"normal"} reference to a label can be created by typing an @ followed by the name of the label (e.g. [= Introduction <intro>] can be referenced by typing [@intro]).

To customize the supplement, add content in square brackets after the reference: [@intro[Chapter]].

Customization

When you only ever need to reference pages of a figure/table/heading/etc. in a document, the default form field value can be changed to {"page"} with a set rule. If you prefer a short “p.” supplement over “page”, the [page.supplement] field can be used for changing this:

#set page(
  numbering: "1",
  supplement: "p.",
>>> margin: (bottom: 3em),
>>> footer-descent: 1.25em,
)
#set ref(form: "page")

#figure(
  stack(
    dir: ltr,
    spacing: 1em,
    circle(),
    square(),
  ),
  caption: [Shapes],
) <shapes>

#pagebreak()

See @shapes for examples
of different shapes.

If you write a show rule for references, you can access the referenced element through the element field of the reference. The element may be {none} even if it exists if Typst hasn’t discovered it yet, so you always need to handle that case in your code.

#set heading(numbering: "1.")
#set math.equation(numbering: "(1)")

#show ref: it => {
  let eq = math.equation
  let el = it.element
  // Skip all other references.
  if el == none or el.func() != eq { return it }
  // Override equation references.
  link(el.location(), numbering(
    el.numbering,
    ..counter(eq).at(el.location())
  ))
}

= Beginnings <beginning>
In @beginning we prove @pythagoras.
$ a^2 + b^2 = c^2 $ <pythagoras>

Fields

target: Label

supplement: Settable<Self, 1u8>

form: Settable<Self, 2u8>

citation: Option<Option<Packed<CiteElem>>>

element: Option<Option<Content>>

Implementations

impl RefElem

pub fn new(target: Label) -> Self

Create a new instance of the element.

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

Builder-style setter for the supplement field.

pub fn with_form(self, form: RefForm) -> Self

Builder-style setter for the form field.

pub fn with_citation(self, citation: Option<Packed<CiteElem>>) -> Self

Builder-style setter for the citation field.

pub fn with_element(self, element: Option<Content>) -> Self

Builder-style setter for the element field.

impl RefElem

pub const target: Field<Self, 0u8>

pub const supplement: Field<Self, 1u8>

pub const form: Field<Self, 2u8>

pub const citation: Field<Self, 3u8>

pub const element: Field<Self, 4u8>

Trait Implementations

impl Clone for RefElem

fn clone(&self) -> RefElem

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Construct for RefElem

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

Construct an element from the arguments.

impl Debug for RefElem

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

Formats the value using the given formatter.

impl Hash for RefElem

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 NativeElement for RefElem

const ELEM: Element

The associated element.

fn pack(self) -> Content

Pack the element into type-erased content.

impl RequiredField<0> for RefElem

const FIELD: RequiredFieldData<Self, 0u8>

type Type = Label

impl Set for RefElem

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

Parse relevant arguments into style properties for this element.

impl SettableField<1> for RefElem

const FIELD: SettableFieldData<Self, 1u8>

type Type = Smart<Option<Supplement>>

impl SettableField<2> for RefElem

const FIELD: SettableFieldData<Self, 2u8>

type Type = RefForm

impl SynthesizedField<3> for RefElem

const FIELD: SynthesizedFieldData<Self, 3u8>

type Type = Option<Packed<CiteElem>>

impl SynthesizedField<4> for RefElem

const FIELD: SynthesizedFieldData<Self, 4u8>

type Type = Option<Content>

impl RefableProperty<1> for RefElem

impl RefableProperty<2> for RefElem