Cross-references

Label a block, caption it, and point at it.

Cross-referencing compiled Typst blocks with label, cap, and alt, for figures, tables, listings, and custom reference types.

A compiled block is a Quarto cross-reference target like any other. Three options do the work:

A figure

```{typst}
//| label: fig-shapes
//| cap: "A circle and a square, drawn by Typst."
//| alt: "A blue circle beside an orange square."
#stack(
  dir: ltr,
  spacing: 1em,
  circle(radius: 1cm, fill: blue.lighten(60%)),
  rect(width: 2cm, height: 2cm, fill: orange.lighten(60%)),
)
```

See @fig-shapes.

A blue circle beside an orange square.

Figure 1: A circle and a square, drawn by Typst.

See Figure 1.

A table

The prefix of the label decides the type, so a tbl- label gives a table, numbered in its own series:

```{typst}
//| label: tbl-formats
//| cap: "How each writer receives a block."
//| alt: "A table of three output formats and how each one receives a block."
#table(
  columns: 2,
  [*Writer*], [*Receives*],
  [html], [image],
  [latex], [image],
  [typst], [native or image],
)
```

@tbl-formats lists them.
Table 1: How each writer receives a block.

A table of three output formats and how each one receives a block.

Table 1 lists them.

Every Quarto prefix works the same way, lst- and the custom types a document declares included.

Prefix-specific captions

cap and alt apply to any label. The prefixed forms, fig-cap, tbl-cap, lst-cap, and their alt counterparts, say the same thing for one type:

//| label: fig-example
//| fig-cap: "A caption for a figure."
//| fig-alt: "Alternative text for a figure."

A prefixed option takes precedence over the generic one when the label matches its type. Write cap and alt unless a document already uses the prefixed names.

Important

Reference the filter by name, with no at: stage. Pinning it to one stage breaks cross-referencing, because the labels must be in place before Quarto numbers them.

Back to top