Cross References

Introduction

Cross-references in Quarto enable seamless navigation across different entities like figures, tables, sections, and equations, significantly improving the readability and accessibility of documents.

Cross-references require unique labels for each entity. For example, #fig-element labels a figure, and #tbl-element labels a table. This allows for easy referencing elsewhere in the document.

You will learn how to:

• Cross-reference figures, tables, and code listings.
• Create custom cross-references.
• Use subreferences for nested elements.
• Include computed values in captions.
• Customize the appearance of cross-references.
• List all figures, tables, and code listings in a document.
• Cross-reference callouts, theorems, and proofs.
• Cross-reference sections, diagrams, and videos.
• Cross-reference supplemental figures.

Example for figures:

![Elephant](elephant.png){#fig-elephant}

To refer to this figure elsewhere, use:

See @fig-elephant for an illustration.

Note

Avoid underscores to prevent LaTeX rendering issues.

Cross-Referenceable Entities

• Figures, Tables and Code Listings
• Supports figures and tables generated from executable code cells using Knitr or Jupyter.
• Callouts, Theorems and Proofs and Equations
• Sections

Customize the appearance :

Type	Syntax	Output
Default	@fig-elephant	Figure 1
Custom Prefix	[Fig @fig-elephant]	Fig 1
No Prefix	[-@fig-elephant]	1

Group cross-references using the following syntax:

As illustrated in [@fig-elephant; @fig-panther; @fig-rabbit].

Lists

For PDFs:

• Use \listoffigures, \listoftables and \listoflistings to produce listings of all figure, table, etc.
• Customize titles with lof-title, lot-title, and lol-title options.

Example:

---
title: "My Document"
crossref:
  lof-title: "List of Figures"
format: pdf
---

\listoffigures

Note

The default titles for the lists use the form displayed above (i.e. ‘List of <Type>’).

Figures

Read more about cross-referencing figures and subfigures at Figures.

Tables

Read more about cross-referencing tables and subtables at Tables.

Code Listings

To make a code block reference-able, use a #lst- prefix and lst-cap for the caption:

```{#lst-customers .sql lst-cap="Customers Query"}
SELECT * FROM Customers
```
Refer to it with (@lst-customers).

For a cross-reference using div syntax, wrap the code and caption in a ::: {#lst-} div:

::: {#lst-customers}

```{.sql}
SELECT * FROM Customers
```

Customers Query
:::

For cross-referencing executable code blocks, use lst-label for the identifier with a lst- prefix and lst-cap for the caption. The value of lst-cap provides the caption for the code listing:

```{python}
#| lst-label: lst-import
#| lst-cap: Import pyplot

import matplotlib.pyplot as plt
```

@lst-import...

Rendering results:

Listing 1: Import pyplot

import matplotlib.pyplot as plt

Listing 1…

For code cells generating figures or tables, use lst-, label, and fig-cap/tbl-cap for cross-referencing the code and its output:

```{python}
#| label: fig-plot
#| fig-cap: Figure caption
#| lst-label: lst-plot
#| lst-cap: Listing caption

plt.plot([1,23,2,4])
plt.show()
```

The code in @lst-plot produces the figure in @fig-plot.

Output:

Listing 2: Listing caption

plt.plot([1,23,2,4])
plt.show()

Figure 1: Figure caption

The code in Listing 2 produces the plot in Figure 1.

Callouts

To reference a callout, use an ID with a callout prefix (refer to Table 1) and refer to it with @. Example: add #tip-example to the callout and reference it:

::: {#tip-example .callout-tip}
## Cross-Referencing a Tip

Add an ID starting with `#tip-` to reference a tip.
:::

See @tip-example...

Output:

Tip 1: Cross-Referencing a Tip

Add an ID starting with #tip- to reference a tip.

See Tip 1…

The prefixes for each type of callout are:

Table 1: Prefixes for callout cross-references

Callout Type	Prefix
note	#nte-
tip	#tip-
warning	#wrn-
important	#imp-
caution	#cau-

Theorems and Proofs

To include a referencable theorem, use a div with a #thm- label and provide a theorem name in the first heading. You can add any content inside the div:

::: {#thm-line}

## Line equation

The equation of any straight line can be written as:

$$
y = mx + b
$$
:::

See @thm-line.

Output:

Theorem 1 (Line equation) The equation of any straight line can be written as:

\[ y = mx + b \]

See Theorem 1.

Supported theorem variations and their label prefix:

Label Prefix	Printed Name	LaTeX Environment
#thm-	Theorem	theorem
#lem-	Lemma	lemma
#cor-	Corollary	corollary
#prp-	Proposition	proposition
#cnj-	Conjecture	conjecture
#def-	Definition	definition
#exm-	Example	example
#exr-	Exercise	exercise
#sol-	Solution	solution
#rem-	Remark	remark

Create a proof by adding the .proof class to a div:

::: {.proof}
By induction.
:::

Note

proof is not numbered (and therefore cannot be cross-referenced). As with theorems you can optionally include a heading as the first element of the div.

Equations

Label equations with #eq- immediately after to make them referenceable:

Linear equations (@eq-linear) are of the form:
 
$$
y = mx + b
$$ {#eq-linear}

Output:

Linear equations (Equation 1) are of the form:

\[ y = mx + b \tag{1}\]

Sections

1. Add #sec- to headings for section references:

## Introduction {#introduction}

Refer to @sec-introduction for more details.

AND

2. Enable the number-sections option in the document’s metadata for visible numbering:

---
title: "My Document"
number-sections: true
---

Diagrams

1. Add fig- prefix to a div ID for cross-referencing.
2. Reference it as figures using @ prefix. For example, Figure 2 is created using:

::: {#fig-simple}

```{dot}
graph {
  A -- B
}
```

Simple graphviz graph
:::

Figure 2: This is a simple graphviz graph

Videos

Use div syntax to add a video and caption, and then reference it as a figure:

::: {#fig-cern}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

The video 'CERN: The Journey of Discovery'

:::

In @fig-cern...

Which renders as:

If you would rather give videos a label and counter distinct from figures, consider defining Custom Cross-Reference Types.

Subreferences

Note

When your sub-content is either all figures or all tables there is abbreviated syntax, see the Cross References page for Subfigures and Subtables for details.

Use nested divs to create elements with subreferences:

• Outer div: Main reference (fig-subrefs) with a general caption.
• Inner divs: Specific references (fig-first, fig-second) with individual captions.

:::: {#fig-subrefs}

::: {#fig-first}
CONTENT 1

First caption
:::

::: {#fig-second}
CONTENT 2

Second caption
:::

Main caption
::::

This renders as:

CONTENT 1

(a) First caption

CONTENT 2

(b) Second caption

Figure 3: Main caption

Both the main element and the sub elements can be referenced directly in the text, e.g. 

@fig-subrefs, @fig-first, @fig-second

This renders as: Figure 3, Figure 3 (a), Figure 3 (b).

Combined with layout attributes, you can create complex layouts of mixed content where each element can be referenced. For example:

:::: {#fig-complex layout="[[1, 1], [1]]"}

::: {#fig-elephant}

![](images/elephant.jpg)

An image file
:::

::: {#fig-scatterplot}

```{r}
#| echo: false
plot(1:10)
```

A computational figure
:::

::: {#fig-diagram}

```{dot}
//| fig-height: 2
digraph {
  rankdir = "LR";
  Transform -> Visualize
}
```

A diagram
:::

Example figure combining different types of content
::::

This renders as:

Computed Captions

If you want to include computed values in a caption, use the cross-reference div syntax, along with an inline code expression:

Python

::: {#fig-box}

```{python}
#| echo: false
import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5, 10]
p = plt.boxplot(x)
plt.show()
```

This dataset has `{python} len(x)` observations.

:::

R

::: {#fig-box}

```{r}
#| echo: false


x <- c(1, 2, 3, 4, 5, 10)
boxplot(x)

```

This dataset has `{r} length(x)` observations.

:::

Custom Cross-Reference

• Float cross-references like figures, tables, and code listings can float in the document with captions.
• Define custom floats in YAML with:
  • kind: Must be float.
  • key: Abbreviation for reference ID (e.g., vid for video).
  • reference-prefix: Text for output reference (e.g., ‘In Figure 1, …’).
  • caption-prefix: Text for the caption (e.g., ‘Figure 1: …’). Defaults to reference-prefix if unspecified.

Video

Example:

crossref:
  custom:
    - kind: float
      reference-prefix: Video
      key: vid

Reference with:

::: {#vid-cern}



'CERN: The Journey of Discovery'
:::

In @vid-cern.

Output:

Video 1: ‘CERN: The Journey of Discovery’

In Video 1…

PDF output

• Add latex-env in YAML to name the float environment in TeX for custom references, like video for videos:

  format: pdf
  crossref:
    custom:
      - kind: float
        reference-prefix: Video
        key: vid
        latex-env: video
  
  \listofvideos{}

• Use \listof command in LaTeX for listing custom references, appending s to latex-env, like \listofvideos{} for videos.

• The listing title defaults to the reference-prefix, but you can customize it with latex-list-of-description.

Supplemental Figures

For supplemental figures in a document:

• They should have a separate counter from regular figures.
• Labels should be ‘Figure S1’, ‘Figure S2’, etc.
• Include a ‘List of Supplementary Figures’ section.

Define this type as follows:

crossref:
  custom:
    - kind: float
      key: suppfig
      latex-env: suppfig
      reference-prefix: Figure S
      space-before-numbering: false
      latex-list-of-description: Supplementary Figure

Note

Note the use of space-before-numbering: false, which prevents a space between the reference-prefix or caption-prefix and the counter, so that labels will appear as ‘Figure S1’, ‘Figure S2’ etc.

References

• Quarto Cross References
• Quarto Custom Cross References