@fig-, @tbl-, @sec-, @eq- — numéros automatiques et liens actifs, chacun montré en action." /> Renvois dans Quarto : figures, tableaux, sections – Datanovia

Renvois dans Quarto : figures, tableaux, sections et équations

Numérotez et liez automatiquement figures, tableaux, sections et équations

Apprenez à faire des renvois dans Quarto — étiquetez une figure, un tableau, une section ou une équation et référencez-les par leur numéro avec @fig-, @tbl-, @sec- et @eq-. Quarto numérote tout et garde les liens actifs, pour que votre rapport se lise comme un article.

Date de publication

8 juillet 2026

Modifié

9 juillet 2026

AstucePoints clés
  • Un seul motif pour tout : donnez à l’élément une étiquette préfixée (#fig-, #tbl-, #sec-, #eq-, #lst-), puis écrivez @fig-…, @tbl-…, @sec-…, @eq-… dans le texte. Quarto insère le numéro et un lien.
  • Le numéro est automatique et dynamique. Réordonnez vos figures ou insérez un tableau au-dessus d’un autre, relancez le rendu, et chaque renvoi se met à jour — vous ne tapez plus jamais « Figure 1 » à la main.
  • Une figure ou un tableau doit avoir une légende pour être référençable. Une étiquette préfixée sans légende n’est pas enregistrée, et @fig-… s’affiche en lien cassé ?@fig-….
  • Les renvois de section nécessitent number-sections: true dans le document ; sans cela, il n’y a aucun numéro vers lequel pointer. Cette page l’active, et c’est pourquoi ses titres sont numérotés.
  • Changez l’apparence d’un renvoi avec la syntaxe entre crochets : [Fig @fig-x] pour un préfixe personnalisé, [-@fig-x] pour le numéro seul, [@fig-a; @fig-b] pour en regrouper plusieurs.
Scatter plot of car weight against miles per gallon with a smooth downward azure trend line, rendered in a Quarto document.
Figure 1: A cross-referenceable figure: labelled and captioned, so the surrounding text can point at it by an automatic number.

1 Introduction

Un rapport qui se lit comme un article renvoie à ses figures, tableaux, sections et équations par leur numéro — « voir la figure 2 », « le modèle de l’équation 1 » — et ces numéros restent corrects quand vous ajoutez, supprimez ou réordonnez le contenu. Le faire à la main est un piège : une seule figure insérée et chaque « Figure N » qui suit devient faux. Quarto s’occupe de la numérotation et des liens à votre place, pour chaque type d’élément, à partir d’une seule petite convention.

La convention tient en deux étapes : étiquetez l’élément avec un préfixe propre à son type, puis référencez-le avec @ suivi de cette étiquette. Cette leçon parcourt les quatre que vous utilisez le plus — figures, tableaux, sections et équations — ainsi que les sous-renvois et les éléments plus spécialisés (listes de code, encadrés, théorèmes, diagrammes, vidéos). Le schéma complet se trouve dans la documentation des renvois de Quarto ; voici le chemin pratique pour s’y retrouver.

Parce que c’est un guide de fonctionnalité Quarto, la leçon se démontre elle-même : chaque renvoi que vous voyez se résoudre ci-dessous pointe vers un élément réel et étiqueté sur cette page même. Lisez le source, puis regardez le numéro que Quarto en a produit. (Cette page définit aussi number-sections: true pour que les renvois de section fonctionnent — c’est pourquoi ses titres portent des numéros.)

2 Le motif de base : étiqueter, puis référencer

Chaque renvoi repose sur les deux mêmes gestes. D’abord, attachez une étiquette dont le préfixe indique à Quarto de quel type d’élément il s’agit. Ensuite, écrivez @ suivi de cette étiquette partout où vous voulez que le numéro apparaisse. Quarto les met en correspondance au moment du rendu, attribue le numéro et insère un hyperlien.

Le préfixe est ce qui sélectionne le compteur — les figures se comptent séparément des tableaux, les tableaux des équations, et ainsi de suite :

Table 1: Les préfixes de renvoi
Élément Préfixe d’étiquette Renvoi Rendu
Figure #fig- @fig-… Figure 1
Tableau #tbl- @tbl-… Tableau 1
Section #sec- @sec-… Section 1
Équation #eq- @eq-… Équation 1
Liste de code #lst- @lst-… Liste 1
Encadré / théorème #tip-, #thm-, … @tip-…, @thm-… Astuce 1 / Théorème 1

Deux règles s’appliquent à tous. Utilisez des traits d’union, pas des tirets bas, dans les étiquettes — un tiret bas peut perturber le rendu dans certains formats de sortie. Et un élément flottant (une figure ou un tableau) doit avoir une légende pour être référençable : c’est la légende qui enregistre le numéro.

3 Faire un renvoi vers une figure

Tout bloc de code qui dessine un graphique devient une figure. Donnez-lui une label commençant par fig- et une fig-cap, et il devient référençable. Voici le source, puis son rendu :

```{r}
#| label: fig-fuel
#| fig-cap: "Heavier cars burn more fuel: mileage falls steadily as weight rises."
#| fig-alt: "Scatter plot of car weight against miles per gallon; points trend downward from top-left to bottom-right."
#| fig-width: 7
#| fig-height: 4

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4", size = 2.5) +
  labs(x = "Weight (1000 lbs)", y = "Miles per gallon") +
  theme_minimal()
```
library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4", size = 2.5) +
  labs(x = "Weight (1000 lbs)", y = "Miles per gallon") +
  theme_minimal()
Scatter plot of car weight against miles per gallon; points trend downward from top-left to bottom-right.
Figure 2: Heavier cars burn more fuel: mileage falls steadily as weight rises.

Écrivez maintenant @fig-fuel dans le texte et Quarto le transforme en lien numéroté. La relation est sans équivoque (Figure 2) — et ce numéro a été inséré par Quarto, pas tapé à la main.

Une image Markdown fonctionne de la même façon : placez après elle un id préfixé par #fig- entre accolades, et donnez-lui un texte de légende (le texte entre crochets). C’est la forme que vous utilisez pour une capture d’écran ou un fichier de diagramme :

![A workflow diagram.](workflow.png){#fig-workflow}

The pipeline has three stages (@fig-workflow).

Pour tout ce qui concerne la légende, le dimensionnement et la disposition des figures, voir la leçon dédiée aux figures.

4 Faire un renvoi vers un tableau

Les tableaux suivent exactement le même motif avec un préfixe tbl-. Donnez au bloc de code un #| label: commençant par tbl- et un #| tbl-cap:, puis référencez-le avec @tbl-…. Ici, nous résumons mtcars en R de base et le mettons en tableau avec knitr::kable() :

```{r}
#| label: tbl-mpg
#| tbl-cap: "Average miles-per-gallon by cylinder count."

library(knitr)
agg <- aggregate(mpg ~ cyl, data = mtcars, FUN = mean)
agg$mpg <- round(agg$mpg, 1)
kable(agg, col.names = c("Cylinders", "Mean MPG"))
```
library(knitr)
agg <- aggregate(mpg ~ cyl, data = mtcars, FUN = mean)
agg$mpg <- round(agg$mpg, 1)
kable(agg, col.names = c("Cylinders", "Mean MPG"))
Table 2: Average miles-per-gallon by cylinder count.
Cylinders Mean MPG
4 26.7
6 19.7
8 15.1

Écrire @tbl-mpg produit maintenant un lien numéroté : la consommation de carburant baisse régulièrement à mesure que le nombre de cylindres augmente (Table 2). Un tableau Markdown écrit à la main est aussi référençable — placez {#tbl-…} dans sa ligne de légende plutôt qu’une option de bloc. La leçon sur les tableaux couvre kable, gt et la légende en détail.

5 Faire un renvoi vers une section

Les sections sont le seul type avec une exigence supplémentaire. Pour référencer un titre, ajoutez-lui un id préfixé par #sec- et activez number-sections dans le document — sans numéro, il n’y a rien vers quoi pointer.

## Methods {#sec-methods}

We describe the model in @sec-methods.
---
title: "My report"
number-sections: true
---

Cette page a number-sections: true défini, donc ses renvois de section se résolvent. Les deux sections ci-dessus portent les ids #sec-figures et #sec-tables ; les référencer donne Section 3 et Section 4 — de vrais liens numérotés qui suivent les titres même si vous réordonnez le document. Voir la documentation des sections pour les détails.

6 Faire un renvoi vers une équation

Étiquetez une équation en bloc en plaçant {#eq-…} immédiatement après le $$ de fermeture, sur la même ligne. Référencez-la ensuite avec @eq-….

The simple linear model (@eq-line) fits a straight line:

$$
y = \beta_0 + \beta_1 x
$$ {#eq-line}

Ce qui donne — le modèle linéaire simple (Équation 1) ajuste une droite :

\[ y = \beta_0 + \beta_1 x \tag{1}\]

Quarto numérote l’équation à droite et transforme @eq-line en lien vers elle.

7 Sous-renvois : référencer chaque panneau

Quand une figure contient plusieurs panneaux, vous pouvez référencer l’ensemble ou n’importe quel panneau isolé. Donnez au bloc une étiquette fig- et une liste fig-subcap (une légende par panneau) avec layout-ncol ; Quarto étiquette les panneaux (a), (b) et rend chacun référençable.

```{r}
#| label: fig-views
#| fig-cap: "Two views of what drives fuel efficiency."
#| fig-subcap:
#|   - "By weight"
#|   - "By horsepower"
#| layout-ncol: 2
#| fig-width: 5
#| fig-height: 4

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4") + theme_minimal()
ggplot(mtcars, aes(hp, mpg)) +
  geom_point(color = "#3a86d4") + theme_minimal()
```
library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4") + theme_minimal()
ggplot(mtcars, aes(hp, mpg)) +
  geom_point(color = "#3a86d4") + theme_minimal()
(a) By weight
(b) By horsepower
Figure 3: Two views of what drives fuel efficiency.

Désormais @fig-views pointe vers la paire, tandis que @fig-views-1 et @fig-views-2 pointent vers les panneaux individuels : le poids se trouve dans Figure 3 (a) et la puissance dans Figure 3 (b). La même idée s’applique aux tableaux (tbl-subcap) et au regroupement de fichiers image dans un div {#fig-…} avec des ids #fig-… internes.

8 Changer l’apparence d’un renvoi

Par défaut, un renvoi s’affiche « Figure 2 ». La syntaxe entre crochets vous permet de changer la formulation sans toucher à l’étiquette — utile pour une charte éditoriale qui abrège, ou une phrase qui dit déjà « Figure » :

Table 3: Contrôler le texte du renvoi
Syntaxe Rendu
@fig-fuel Figure N (préfixe par défaut)
[Fig @fig-fuel] Fig N (préfixe personnalisé)
[-@fig-fuel] N (numéro seul)
[@fig-fuel; @fig-views] regroupées en un seul renvoi

Parce que les étiquettes de cette page sont réelles, ces formes se résolvent en direct. Par défaut : Figure 2. Préfixe personnalisé : Fig 2. Numéro seul, pratique après avoir déjà écrit le mot « Figure » : 2. Et groupé, ce qui condense une liste en un seul renvoi soigné : Figure 2, Figure 3.

9 Faire un renvoi vers d’autres éléments

Le même motif étiquette-puis-@ s’étend au-delà des quatre grands. Voici ceux que vous rencontrez moins souvent, avec la syntaxe nécessaire.

9.1 Encadrés

Donnez à un encadré un id avec le bon préfixe et référencez-le comme n’importe quoi d’autre. En voici un vrai :

::: {#tip-crossref .callout-tip}
## A referenceable tip
Add an id starting with `#tip-` to make a callout cross-referenceable.
:::

See @tip-crossref for the trick.
Astuce 1: Une astuce référençable

Ajoutez un id commençant par #tip- pour rendre un encadré référençable.

Voir Tip 1 pour l’astuce. Chaque type d’encadré a son propre préfixe :

Table 4: Les préfixes de renvoi des encadrés
Type d’encadré Préfixe
note #nte-
tip #tip-
warning #wrn-
important #imp-
caution #cau-

9.2 Listes de code

Pour référencer un bloc de code par son numéro, ajoutez un lst-label (avec un préfixe lst-) et un lst-cap au bloc, puis utilisez @lst-… :

```{r}
#| lst-label: lst-summary
#| lst-cap: "Summarise fuel economy by cylinder count."

aggregate(mpg ~ cyl, data = mtcars, FUN = mean)
```

The code in @lst-summary produces the per-cylinder means.

9.3 Théorèmes, diagrammes et vidéos

  • Les théorèmes et démonstrations utilisent un div avec une étiquette #thm- (et ses variantes #lem- pour un lemme, #cor- pour un corollaire, #def- pour une définition, #prp- pour une proposition). Mettez le nom du théorème dans le premier titre ; référencez avec @thm-…. Un div .proof n’est pas numéroté, il ne peut donc pas être référencé.
  • Les diagrammes créés avec un bloc {mermaid} ou {dot} deviennent des figures : enveloppez-les dans un div ::: {#fig-…} avec une légende et référencez avec @fig-….
  • Les vidéos fonctionnent de la même façon — un div ::: {#fig-…} autour d’un shortcode , référencé comme une figure. Si vous voulez que les vidéos aient leur propre compteur « Vidéo 1 » au lieu de partager celui des figures, définissez un type de renvoi personnalisé :
---
crossref:
  custom:
    - kind: float
      reference-prefix: Video
      key: vid
---

Un type personnalisé avec key: vid s’étiquette alors #vid-… et se référence @vid-…. Le même mécanisme produit des figures supplémentaires (« Figure S1 », « Figure S2 ») avec un compteur distinct.

Note

Pour la sortie PDF, Quarto peut aussi émettre une liste de toutes les figures, tableaux ou listes de code avec les commandes LaTeX \listoffigures, \listoftables et \listoflistings, et vous pouvez les retitrer avec les options lof-title / lot-title / lol-title.

10 Problèmes fréquents

Un renvoi s’affiche littéralement ?@fig-name (un lien cassé). Quarto n’a pas pu résoudre cette étiquette. Pour une figure ou un tableau, deux choses doivent coïncider : la label commence par le bon préfixe (fig-, tbl-) et l’élément a une légende. Une figure étiquetée sans fig-cap n’est pas enregistrée comme référençable, il n’y a donc rien vers quoi @fig-name peut pointer. Ajoutez la légende et vérifiez que l’orthographe correspond exactement.

@sec-… ne produit pas de numéro. Les renvois de section nécessitent number-sections: true dans le document et un id préfixé par #sec- sur le titre. S’il en manque un, le renvoi ne peut pas se résoudre en numéro.

Un renvoi casse après un renommage. Le renvoi @ doit correspondre à l’étiquette caractère pour caractère. Si vous renommez l’étiquette d’un bloc, mettez à jour chaque @… qui pointe vers elle. Préférez les traits d’union aux tirets bas dans les étiquettes — les tirets bas peuvent causer des problèmes de rendu dans certains formats.

11 Questions fréquentes

Donnez à la figure une étiquette commençant par fig- (par ex. #| label: fig-trend pour un bloc de code, ou {#fig-trend} sur une image Markdown) et une légende, puis écrivez @fig-trend dans votre texte. Quarto insère le bon numéro et un lien, et renumérote automatiquement si vous réordonnez le document.

L’étiquette n’a pas pu être résolue. Les deux causes habituelles sont une légende manquante (un élément étiqueté fig-/tbl- en a besoin pour être enregistré) et une étiquette qui ne correspond pas exactement au renvoi. Ajoutez la légende et vérifiez l’orthographe.

Ajoutez un id préfixé par #sec- au titre — ## Methods {#sec-methods} — et définissez number-sections: true dans l’en-tête YAML du document. Ensuite @sec-methods s’affiche comme une « Section N » numérotée et liée. Sans number-sections, il n’y a aucun numéro vers lequel pointer.

Chaque type d’élément a son propre préfixe d’étiquette et son propre compteur : fig- pour les figures, tbl- pour les tableaux, sec- pour les sections, eq- pour les équations, lst- pour les listes de code, et des préfixes d’encadré/théorème comme tip-, nte-, thm-, def-. Vous en référencez n’importe lequel avec @ suivi de l’étiquette, par ex. @tbl-summary.

Utilisez la syntaxe entre crochets autour du renvoi : [Fig @fig-x] donne un préfixe personnalisé (« Fig 2 »), [-@fig-x] donne juste le numéro (« 2 »), et [@fig-a; @fig-b] regroupe plusieurs renvois en un seul. L’étiquette elle-même reste inchangée.

Exercice 1. Vous avez un bloc de code qui dessine une boîte à moustaches de iris$Sepal.Length par Species. Écrivez les options de bloc qui le rendent référençable via @fig-sepal, puis écrivez une phrase qui le référence.

Deux options de bloc sont requises pour un renvoi de figure : une label qui commence par le préfixe de figure, et une légende. Le renvoi lui-même est @ suivi de l’étiquette.

```{r}
#| label: fig-sepal
#| fig-cap: "Sepal length differs across the three iris species."
#| fig-alt: "Boxplot of sepal length grouped by species; virginica is highest, setosa lowest."

library(ggplot2)
ggplot(iris, aes(Species, Sepal.Length)) +
  geom_boxplot(fill = "#3a86d4") +
  theme_minimal()
```

Puis dans le texte : Setosa flowers have the shortest sepals (@fig-sepal). La label préfixée fig- et la fig-cap sont toutes deux requises pour que @fig-sepal produise un numéro.

Exercice 2. Écrivez une équation en bloc étiquetée pour l’aire d’un cercle et une phrase qui la référence par son numéro.

The area of a circle (@eq-area) grows with the square of the radius:

$$
A = \pi r^2
$$ {#eq-area}

L’id {#eq-area} se place immédiatement après le $$ de fermeture ; @eq-area produit ensuite le lien numéroté.

Vous écrivez ## Methods {#sec-methods} et le référencez avec @sec-methods, mais le renvoi ne produit pas de numéro. Quelle en est la cause la plus probable ?

A. Il vous faut une légende sur la section. B. number-sections: true n’est pas défini dans le document. C. Les renvois de section ne sont pas pris en charge en HTML.

B. Les renvois de section nécessitent number-sections: true dans l’en-tête YAML — sans cela, il n’y a aucun numéro vers lequel pointer. (Les sections ne prennent pas de légende, et HTML les prend entièrement en charge.)

12 Conclusion

Les renvois dans Quarto, c’est une seule convention appliquée partout : étiquetez l’élément avec un préfixe de type — #fig-, #tbl-, #sec-, #eq-, #lst- — puis référencez-le avec @ et cette étiquette. Quarto attribue le numéro, insère le lien et garde les deux corrects à mesure que le document évolue. Retenez les deux pièges : les figures et les tableaux ont besoin d’une légende pour être référençables, et les renvois de section nécessitent number-sections: true. Mettez cela en place et votre rapport cite ses propres figures, tableaux et équations comme le fait un article — automatiquement.

13 Leçons connexes

Cette page vous a-t-elle été utile ?

Recevez les nouvelles leçons R & Python par e-mail

Pratique, reproductible, sans spam. Désinscription à tout moment.

Double opt-in. Nous ne partageons jamais votre e-mail.

Partager cette pageXLinkedInRedditHN
Note

Cette leçon est reproductible : chaque figure, tableau et renvoi de cette page a été produit par le source montré juste au-dessus, exécuté au moment de la génération — copiez n’importe quel bloc et exécutez-le pour reproduire ces résultats. The runtime is the judge.

Réutilisation

Citation

BibTeX
@online{2026,
  author = {},
  title = {Renvois dans Quarto : figures, tableaux, sections et
    équations},
  date = {2026-07-08},
  url = {https://www.datanovia.com/learn/programming/quarto/cross-references},
  langid = {fr}
}
Veuillez citer ce travail comme suit :
“Renvois dans Quarto : figures, tableaux, sections et équations.” 2026. July 8. https://www.datanovia.com/learn/programming/quarto/cross-references.