quarto-web/docs/authoring/cross-references-custom.qmd at 49effe0e330bcb104e995025b510988f45a9c323 · quarto-dev/quarto-web · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
---
title: Custom Float Cross-Reference Types
crossref:
  custom:
    - kind: float
      reference-prefix: Video
      key: vid
---

{{< include /docs/_require-1.4.qmd >}}

## Overview

Cross-referenceable [figures](#figures), [tables](#tables) and [code listings](#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, ...")

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

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

You can then use this new type with the [Cross-Reference Div Syntax](cross-references-divs.qmd) in a document:

``` {.markdown shortcodes="false"}
::: {#vid-cern}

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

"CERN: The Journey of Discovery"

:::

In @vid-cern...
```

Which renders as:

::: {#vid-cern}
{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

"CERN: The Journey of Discovery"
:::

In @vid-cern...

There are some additional options that give you more control over the appearance of the cross-reference:

- `caption-prefix`, the text used to construct the caption title shown under the float ("Figure 1: ..."). If unspecified, Quarto will use the value of `reference-prefix`.

- `caption-location`, the position of the the caption. Options are: `top`, `bottom` (default) or `margin`.

- `space-before-numbering`, whether there is a space between the prefix and number. Set to `false` to omit the space (e.g. "Figure1").


You can find a complete listing of the options available for the `custom` key on the [Cross-Reference Options](/docs/reference/metadata/crossref.qmd#custom) reference page.

## Localisation

Custom cross-reference kinds inherit the same localisation pattern as built-in floats.
A custom kind with `key: vid` is localised by setting `crossref-vid-title` and `crossref-vid-prefix` under `language:`:

``` yaml
---
lang: es
language:
  crossref-vid-title: "Vídeo"
  crossref-vid-prefix: "Vídeo"
crossref:
  custom:
    - kind: float
      reference-prefix: Video
      key: vid
---
```

The per-language subkeys form also works, which is useful when a single project is rendered in more than one language:

``` yaml
language:
  es:
    crossref-vid-prefix: "Vídeo"
  fr:
    crossref-vid-prefix: "Vidéo"
```

See [Cross-Reference Titles and Prefixes](language.qmd#cross-reference-titles-and-prefixes) for the full pattern.

## 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 you could add `latex-env: video`:

``` yaml
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{}`:

``` yaml
---
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:

```yaml
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.