Figures dans Quarto : légendes, dimensions, mise en page et références croisées

Q: Comment ajouter une légende à une figure dans Quarto ?

Pour une figure issue de code, définissez l’option de bloc fig-cap : #| fig-cap: "Your caption". Pour une image Markdown, le texte entre crochets est la légende : ![Your caption](image.png). La légende s’affiche sous la figure par défaut et est incluse dans la numérotation automatique « Figure N ».

Q: Quelle est la différence entre fig-cap et fig-alt ?

fig-cap est la légende visible que tout le monde lit sur la page ; fig-alt est le texte alternatif que les lecteurs d’écran annoncent et que la recherche d’images indexe — il n’est pas affiché. Ce sont des options distinctes et vous devez définir les deux : une légende descriptive pour les lecteurs voyants et une description littérale de l’image pour fig-alt.

Q: Comment référencer une figure par son numéro ?

Donnez au bloc une étiquette commençant par fig- (par ex. #| label: fig-trend) et une légende, puis écrivez @fig-trend dans votre texte. Quarto insère le numéro correct et un lien, et renumérote automatiquement si vous réorganisez le document. La même chose fonctionne pour une image Markdown avec un identifiant {#fig-…} et une légende.

Q: Comment placer deux figures côte à côte dans Quarto ?

Ajoutez #| layout-ncol: 2 à un seul bloc de code qui trace deux graphiques, et éventuellement #| fig-subcap pour légender chaque panneau. Pour deux fichiers image, enveloppez-les dans un div ::: {layout-ncol=2}. Utilisez layout-nrow pour une grille, ou un tableau layout comme [[1,1],[1]] pour un agencement personnalisé.

Q: Comment changer la taille d’une figure ?

Pour une figure de code, définissez #| fig-width: et #| fig-height: en pouces — cela contrôle la taille à laquelle le graphique et son texte sont dessinés. Pour une image Markdown, utilisez un attribut width= ({width=300}, {width=80%}, {width=4in}) et la hauteur se met à l’échelle automatiquement. Pour mettre à l’échelle une image finie sur la page sans la redessiner, utilisez out-width.

Ajouter, légender, dimensionner et référencer des figures dans un document Quarto

Apprenez à travailler avec les figures dans Quarto — ajoutez un graphique ou une image, définissez une légende et un texte alternatif, contrôlez la largeur et la mise en page, placez des figures côte à côte et référencez-les par leur numéro. Chaque option est montrée en action, à côté de son code source.

Date de publication

8 juillet 2026

Modifié

9 juillet 2026

Points clés

Deux façons d’ajouter une figure : la générer à partir d’un bloc de code (reproductible — elle se met à jour quand les données changent), ou insérer un fichier image avec la syntaxe Markdown ![]().
Une légende, c’est fig-cap ; le texte alternatif, c’est fig-alt. La légende est l’étiquette visible que tout le monde lit ; le texte alternatif est ce que les lecteurs d’écran annoncent et ce que la recherche d’images indexe. Définissez les deux.
Dimensionnez une figure de code avec fig-width / fig-height (en pouces — cela contrôle la taille à laquelle le texte et les points sont dessinés), dimensionnez une image Markdown avec width=.
Référencez une figure par son numéro en donnant à son bloc une étiquette préfixée par fig- plus une légende, puis en écrivant @fig-label dans le texte — le numéro se met à jour automatiquement si vous réorganisez.
Disposez les figures côte à côte avec layout-ncol, en grille avec layout-nrow, ou selon n’importe quel agencement avec un tableau layout.

Scatter plot of car weight against miles per gallon with a smooth downward azure trend line. — Figure 1: A Quarto figure — captioned and cross-referenceable, generated from the code so it updates whenever the data does.

Introduction

Vous avez un graphique, et il vous faut maintenant l’intégrer dans le rapport — légendé, à la bonne taille, désigné par son numéro dans le texte qui l’entoure, et lisible par une personne utilisant un lecteur d’écran. Quarto gère tout cela à partir de quelques options de bloc et d’une syntaxe Markdown compacte, de sorte que la figure et le texte qui en parle restent synchronisés.

Cette leçon est auto-démonstrative : chaque figure rendue ci-dessous a été produite par le code source exact affiché juste au-dessus. Lisez le code source, puis regardez ce qu’il produit. La référence complète des options se trouve dans la documentation des figures de Quarto ; voici le sous-ensemble pratique auquel vous recourez au quotidien.

Il existe deux sources pour une figure, et elles se comportent un peu différemment :

À partir d’un bloc de code — un bloc {r} (ou {python}) dont la sortie est la figure. C’est le choix reproductible par défaut : modifiez les données ou le code et régénérez, et la figure se met à jour.
À partir d’un fichier image — une image que vous possédez déjà (une capture d’écran, un schéma, un logo), insérée avec la syntaxe Markdown ![alt](path).

Nous couvrons les deux, en commençant par la voie du code, car c’est de là que proviennent la plupart de vos figures.

Ajouter une figure à partir du code

Tout bloc de code qui trace un graphique devient une figure. Les options de bloc qui commencent par fig- contrôlent son apparence. Voici une figure légendée, dimensionnée et pourvue d’un texte alternatif — d’abord le code source, puis ce qu’il produit :

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

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()
```

Ce bloc définit quatre choses : un label (utilisé pour les références croisées, ci-dessous), un fig-cap (la légende visible), un fig-alt (le texte d’accessibilité) et la taille de dessin. Voici le résultat :

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 on the x-axis against miles per gallon on the y-axis; points trend downward from top-left to bottom-right. — Figure 2: Heavier cars burn more fuel: mileage falls steadily as weight rises.

Quarto l’a numérotée automatiquement (c’est Figure 2) et a placé la légende en dessous — le comportement par défaut. Tout le reste de cette leçon s’appuie sur ces quatre options ; la liste complète figure dans la référence des options de figure à l’exécution.

La légende et le texte alternatif ont des rôles différents

fig-cap et fig-alt sont faciles à confondre car tous deux décrivent la figure, mais ils s’adressent à des lecteurs différents :

fig-cap est la légende — visible par tous, imprimée sous (ou au-dessus de) la figure, et reprise dans la numérotation « Figure N ». Rédigez-la pour un lecteur qui parcourt le document.
fig-alt est le texte alternatif — non affiché sur la page, mais lu à voix haute par les lecteurs d’écran et utilisé par la recherche d’images. Rédigez-le comme une description littérale de ce que montre l’image.

Définissez les deux sur chaque figure. Omettre fig-alt est une lacune d’accessibilité que Quarto et Lighthouse signaleront, et cela vous coûte de la visibilité dans la recherche d’images pour votre contenu gratuit.

Dimensionner une figure

Pour une figure de code, fig-width et fig-height définissent la taille en pouces à laquelle R dessine le graphique. C’est le levier important : il contrôle la taille apparente du texte des axes, des points et des lignes par rapport au panneau. Un fig-width trop grand rend le texte minuscule ; trop petit, il devient à l’étroit.

```{r}
#| label: fig-small
#| fig-cap: "The same plot drawn at a smaller size — note the relative text size."
#| fig-width: 4
#| fig-height: 3

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4") +
  theme_minimal()
```

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4") +
  theme_minimal()

Figure 3: The same plot drawn at a smaller size — note the relative text size.

fig-width / fig-height modifient la façon dont le graphique est dessiné. Une option distincte, out-width (par ex. #| out-width: "60%"), met à l’échelle l’image finie sur la page sans la redessiner — recourez-y uniquement pour ajuster une figure à la colonne, pas pour corriger la taille du texte.

Référencer une figure par son numéro

Parler de « la figure ci-dessous » ne tient plus dès que vous réorganisez le document. Référencez plutôt les figures par un numéro automatique. Deux exigences : l’étiquette label du bloc doit commencer par fig-, et la figure doit avoir une légende. Écrivez ensuite @fig-label dans la prose et Quarto insère le numéro à jour et un lien. Consultez la documentation des références croisées pour le schéma complet.

@fig-weight-mpg renvoie à la première figure que nous avons créée :

The relationship is unmistakable (@fig-weight-mpg).

Ce qui se rend ainsi : La relation est indéniable (Figure 2). Réorganisez les figures et ce numéro suit le changement au rendu suivant — vous ne saisissez plus jamais « Figure 1 » à la main.

La même chose fonctionne pour une image Markdown : donnez-lui un identifiant préfixé par #fig- et Quarto la traite comme une figure numérotée.

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

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

Placer des figures côte à côte

Pour afficher plusieurs graphiques ensemble, ajoutez layout-ncol à un seul bloc qui trace plus d’un graphique. Donnez à fig-cap une légende globale et à fig-subcap une légende par panneau — Quarto les étiquette (a), (b) :

```{r}
#| label: fig-two-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()

Comme ce bloc possède une étiquette préfixée par fig-, chaque panneau est adressable individuellement : @fig-two-views-1 et @fig-two-views-2, ou @fig-two-views pour le groupe.

Pour une grille, utilisez layout-nrow à la place de (ou avec) layout-ncol. Pour un contrôle total, passez un tableau layout — une liste de lignes, chaque ligne étant une liste de largeurs de colonnes relatives. Ici, deux graphiques partagent la ligne du haut et un troisième occupe toute la ligne du bas :

```{r}
#| label: fig-custom-layout
#| fig-cap: "A custom layout: two plots on top, one spanning the bottom."
#| layout: [[1,1], [1]]
#| fig-width: 5
#| fig-height: 3.5

library(ggplot2)
ggplot(mtcars, aes(wt, mpg))   + geom_point(color = "#3a86d4") + theme_minimal()
ggplot(mtcars, aes(hp, mpg))   + geom_point(color = "#3a86d4") + theme_minimal()
ggplot(mtcars, aes(disp, 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()
ggplot(mtcars, aes(disp, mpg)) + geom_point(color = "#3a86d4") + theme_minimal()

Figure 5: A custom layout: two plots on top, one spanning the bottom.

Figure 6: A custom layout: two plots on top, one spanning the bottom.

Figure 7: A custom layout: two plots on top, one spanning the bottom.

Le tableau [[1,1], [1]] signifie deux lignes : la première avec deux colonnes égales, la seconde avec une seule colonne pleine largeur. Utilisez des pourcentages pour des répartitions inégales ([[70,30], [100]]) et une valeur négative pour insérer un espace entre les panneaux ([[40,-20,40], [100]]).

Déplacer la légende

Par défaut, la légende se place sous la figure. Définissez fig-cap-location sur top, bottom ou margin pour la déplacer — par bloc, ou une seule fois dans l’en-tête du document pour l’appliquer partout :

```{r}
#| label: fig-cap-top
#| fig-cap: "This caption sits above the figure."
#| fig-cap-location: top
#| fig-width: 7
#| fig-height: 3.6

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4") + theme_minimal()
```

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = "#3a86d4") + theme_minimal()

Figure 8: This caption sits above the figure.

Ajouter une figure à partir d’un fichier image

Lorsque la figure est un fichier que vous possédez déjà plutôt que quelque chose que vous calculez, utilisez la syntaxe d’image de Markdown : ![alt text](path). Les exemples ci-dessous sont du code que vous copiez dans votre propre document — remplacez elephant.png par votre fichier. Le motif d’inclusion et d’attributs est le même que celui documenté dans le guide des figures de Quarto.

L’inclusion de base, où le texte entre crochets sert à la fois de légende et de texte alternatif :

![A hand-drawn elephant.](elephant.png)

Dimensionnez-la avec un attribut width entre accolades — Quarto met la hauteur à l’échelle en conséquence. Utilisez des pixels, un pourcentage de la colonne, ou des pouces :

![](elephant.png){width=300}
![](elephant.png){width=80%}
![](elephant.png){width=4in}

Définissez le titre, l’alignement et un texte alternatif distinct sous forme d’attributs. Ici, le texte entre crochets devient un titre au survol, fig-align la positionne, et fig-alt fournit la description (distincte) destinée au lecteur d’écran :

![](elephant.png "An elephant"){fig-align="left" fig-alt="A pencil drawing of an elephant." width=40%}

Faites-en un lien en enveloppant l’image dans un lien Markdown normal :

[![An elephant.](elephant.png)](https://en.wikipedia.org/wiki/Elephant)

Laissez les lecteurs cliquer pour zoomer en ajoutant la classe .lightbox — aucune configuration supplémentaire, selon la documentation des figures lightbox :

![An elephant.](elephant.png){.lightbox}

Pour regrouper des fichiers image côte à côte et donner au groupe une seule légende, enveloppez-les dans un div layout-ncol ; un identifiant préfixé par #fig- sur le div rend le groupe référençable et les identifiants internes font de chaque panneau une sous-figure :

::: {#fig-elephants layout-ncol=2}

![Surus](surus.png){#fig-surus}

![Hanno](hanno.png){#fig-hanno}

Two famous elephants.
:::

Les mêmes tableaux layout / layout-nrow présentés pour les figures de code fonctionnent aussi sur ces divs.

Mettre en page n’importe quel contenu, pas seulement des figures

Le div layout-ncol ne se limite pas aux images — placez n’importe quel contenu en colonnes. C’est pratique pour une liste sur deux colonnes ou un bloc code-à-côté-des-notes :

::: {layout-ncol=2}
### Pros
- Fast
- Simple

### Cons
- Less flexible
:::

Avantages

Rapide
Simple

Inconvénients

Moins flexible

Problèmes fréquents

@fig-… affiche « ?@fig-… » au lieu d’un numéro. Une référence croisée a besoin à la fois d’une étiquette préfixée par fig- et d’une légende. Un bloc avec #| label: fig-x mais sans fig-cap produit une figure ordinaire sans numéro, il n’y a donc rien à référencer. Ajoutez le fig-cap (ou, pour une image Markdown, assurez-vous que l’identifiant commence par fig- et que l’image comporte un texte de légende).

Le texte de la figure est minuscule ou flou. C’est presque toujours un problème de fig-width, pas de out-width. fig-width/fig-height définissent la taille à laquelle R dessine, donc un grand fig-width réduit à la largeur de la colonne rétrécit tout le texte. Définissez fig-width proche du nombre de pouces que la figure occupera réellement (7 est une bonne valeur par défaut pour un graphique pleine largeur), et utilisez out-width uniquement pour l’ajustement final sur la page.

Le texte alternatif est manquant. fig-alt est distinct de fig-cap — rédiger une légende ne vous donne pas de texte alternatif. Chaque figure a besoin de son propre fig-alt (une description littérale de l’image) pour l’accessibilité et le référencement des images ; une figure de code qui en est dépourvue échoue au contrôle d’accessibilité.

Questions fréquentes

Comment ajouter une légende à une figure dans Quarto ?

Pour une figure issue de code, définissez l’option de bloc fig-cap : #| fig-cap: "Your caption". Pour une image Markdown, le texte entre crochets est la légende : ![Your caption](image.png). La légende s’affiche sous la figure par défaut et est incluse dans la numérotation automatique « Figure N ».

Quelle est la différence entre fig-cap et fig-alt ?

fig-cap est la légende visible que tout le monde lit sur la page ; fig-alt est le texte alternatif que les lecteurs d’écran annoncent et que la recherche d’images indexe — il n’est pas affiché. Ce sont des options distinctes et vous devez définir les deux : une légende descriptive pour les lecteurs voyants et une description littérale de l’image pour fig-alt.

Comment référencer une figure par son numéro ?

Donnez au bloc une étiquette commençant par fig- (par ex. #| label: fig-trend) et une légende, puis écrivez @fig-trend dans votre texte. Quarto insère le numéro correct et un lien, et renumérote automatiquement si vous réorganisez le document. La même chose fonctionne pour une image Markdown avec un identifiant {#fig-…} et une légende.

Comment placer deux figures côte à côte dans Quarto ?

Ajoutez #| layout-ncol: 2 à un seul bloc de code qui trace deux graphiques, et éventuellement #| fig-subcap pour légender chaque panneau. Pour deux fichiers image, enveloppez-les dans un div ::: {layout-ncol=2}. Utilisez layout-nrow pour une grille, ou un tableau layout comme [[1,1],[1]] pour un agencement personnalisé.

Comment changer la taille d’une figure ?

Pour une figure de code, définissez #| fig-width: et #| fig-height: en pouces — cela contrôle la taille à laquelle le graphique et son texte sont dessinés. Pour une image Markdown, utilisez un attribut width= ({width=300}, {width=80%}, {width=4in}) et la hauteur se met à l’échelle automatiquement. Pour mettre à l’échelle une image finie sur la page sans la redessiner, utilisez out-width.

Testez vos connaissances

Tâche 1. Vous avez un bloc de code qui trace une boîte à moustaches de iris$Sepal.Length par Species. Écrivez les options de bloc qui (a) la légendent, (b) lui donnent un texte alternatif, et (c) vous permettent d’y faire référence dans le texte par see @fig-sepal. Rédigez ensuite la phrase qui la référence.

Indice

Trois options de bloc font le travail : une pour l’étiquette (elle doit commencer par fig-), une pour la légende, une pour le texte alternatif. C’est l’étiquette et la légende ensemble qui font que la référence croisée se résout.

Solution

```{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 la prose : Setosa flowers have the shortest sepals (@fig-sepal). L’étiquette label préfixée par fig- et le fig-cap sont tous deux nécessaires pour que @fig-sepal produise un numéro.

Tâche 2. Affichez la même boîte à moustaches iris à côté d’un nuage de points de Sepal.Length en fonction de Petal.Length, côte à côte, avec une légende sur chaque panneau.

Solution

```{r}
#| label: fig-iris-pair
#| fig-cap: "Two views of the iris measurements."
#| fig-subcap:
#|   - "Sepal length by species"
#|   - "Sepal vs petal length"
#| layout-ncol: 2

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

layout-ncol: 2 place les panneaux côte à côte ; fig-subcap les étiquette (a) et (b).

Vérification rapide

Vous écrivez un bloc avec #| label: fig-costs mais sans légende, puis vous le référencez avec @fig-costs. Qu’est-ce qui apparaît dans le document rendu ?

A. Un numéro de figure et un lien corrects B. Une référence non résolue comme ?@fig-costs — car une figure référençable a aussi besoin d’une légende C. Rien du tout

Afficher la réponse

B. Une étiquette préfixée par fig- est nécessaire mais pas suffisante — sans fig-cap, la figure n’est pas numérotée, il n’y a donc rien vers quoi @fig-costs puisse pointer et Quarto émet une référence non résolue. Ajoutez la légende pour corriger cela.

Conclusion

Les figures dans Quarto se résument à une poignée d’options que vous connaissez maintenant : fig-cap pour la légende, fig-alt pour l’accessibilité, fig-width/fig-height pour la taille, une étiquette label préfixée par fig- plus @fig-label pour les références croisées numérotées, et layout-ncol / layout-nrow / layout pour l’agencement. Générez les figures à partir du code quand vous le pouvez — elles restent reproductibles — et insérez des fichiers image avec ![]() quand vous ne le pouvez pas. Légendez et pourvoyez d’un texte alternatif chacune d’elles, et laissez Quarto gérer la numérotation.

Leçons connexes

Choisir un IDE — le rendu et l’aperçu en un clic de RStudio sont l’endroit le plus simple pour itérer sur ces figures. · Nuage de points en R — construisez les figures ggplot2 que vous légendez et référencez ici. · Thèmes ggplot2 — mettez en forme un graphique avant qu’il n’entre dans le rapport.
Pour aller plus loin : Créer des documents avec Quarto — la série complète. · Science computationnelle & IA — le pilier.

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

Note

Cette leçon est reproductible : chaque figure de cette page a été produite par le code affiché, 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

CC BY-NC-SA 4.0

Citation

BibTeX

@online{2026,
  author = {},
  title = {Figures dans Quarto~: légendes, dimensions, mise en page et
    références croisées},
  date = {2026-07-08},
  url = {https://www.datanovia.com/learn/programming/quarto/figures},
  langid = {fr}
}

Veuillez citer ce travail comme suit :

“Figures dans Quarto : légendes, dimensions, mise en page et références croisées.” 2026. July 8. https://www.datanovia.com/learn/programming/quarto/figures.