Custom Float Cross-Reference Types

Overview

Cross-referenceable figures, tables and code listings are examples of float cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions.

You can define custom float cross-reference types using the custom key to the crossref option either in your document or project metadata. At a minimum, a custom type needs:

  • kind, which currently can only be float
  • key, the abbreviation used in the reference identifier (“In @fig-1, …”)
  • reference-prefix, used for the reference in output (“In Figure 1, …”)
  • caption-prefix, used in front of the caption text (“Figure 1: …”). If caption-prefix is unspecified, Quarto will use the value of reference-prefix.

For example, the following YAML defines a new cross-reference type for videos:

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

You can then use this new type with the Cross-Reference Div Syntax in a document:

::: {#vid-cern}

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

"CERN: The Journey of Discovery"

:::

In @vid-cern...

Which renders as:

Video 1: “CERN: The Journey of Discovery”

In Video 1…

You can find a complete listing of the options available for the custom key on the Cross-Reference Options reference page.

PDF Output

If your output format is PDF you’ll also need to specify latex-env, a name to be used for the float environment wrapped around the element in the intermediate TeX. For example, to use the custom video reference type in PDF you could add latex-env: video:

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

You can add a listing of your custom cross-references to your document by including a raw LaTeX \listof command. The name of the command is listof followed by the value of latex-env, followed by an s. For example, for the custom video type above, where the latex-env was video, the command is \listofvideos{}:

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

\listofvideos{}

By default, the title of the listing (e.g “List of Videos”) is constructed from the reference-prefix value. You can specify something else with the latex-list-of-description value.

Example: Supplemental Figures

As another example of a custom cross-reference type consider a document with supplemental figures. For instance, you might require:

  • Supplemental figures have their own counter, distinct from that of figures.
  • Supplemental figures have labels that look like “Figure S1”, “Figure S2” etc.
  • Supplemental figures appear in their own “List of Supplementary Figures” listing.

You could define this supplemental figure type with the following:

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

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.