Tableaux dans Quarto : Markdown, knitr::kable et gt

Mettez vos données en forme sous forme de tableaux propres dans un document Quarto — des tables Markdown à pipes au gt de qualité publication.

Apprenez à créer des tableaux dans Quarto — des tables Markdown à pipes, knitr::kable() pour un data frame, le package gt pour un rendu de qualité publication, et des légendes de tableau à références croisées. Chaque tableau est montré en train de s’afficher en direct, à côté du code source exact qui l’a produit.

Date de publication

8 juillet 2026

Modifié

9 juillet 2026

AstucePoints clés
  • Les tables à pipes écrites à la main sont le moyen le plus rapide de placer un petit tableau fixe dans un rapport — le : dans la ligne d’en-tête contrôle l’alignement des colonnes.
  • knitr::kable() transforme n’importe quel data frame R en un tableau propre. Utilisez-le dès que les nombres proviennent de votre code, et non de votre clavier.
  • Le package gt est l’option moderne, de qualité publication — titres, bandeaux, nombres mis en forme et style — et il remplace des outils plus anciens comme xtable et pander.
  • Référencez un tableau en donnant à sa cellule un #| label: qui commence par tbl- plus un #| tbl-cap:, puis en le référençant avec @tbl-…. Quarto le numérote et crée le lien dans le texte à votre place.
  • Tout est montré en fonctionnement ici : chaque tableau ci-dessous s’affiche juste à côté du code source exact qui l’a produit — copiez n’importe quel bloc et exécutez-le.

Introduction

Vous venez de calculer un résumé — la consommation moyenne de carburant par nombre de cylindres, un tableau de coefficients de modèle, un dictionnaire de données — et il faut maintenant qu’il ressemble à un élément de rapport, pas à un vidage de console. Quarto vous offre trois voies, et la bonne dépend de l’origine du tableau.

Si le tableau est petit et fixe, vous le saisissez en Markdown. S’il provient de R, vous passez le data frame à knitr::kable(). S’il doit être présenté à des lecteurs qui attendent un tableau soigné, de style revue, vous optez pour gt. Cette leçon parcourt les trois, plus l’élément qui donne à un tableau sa place dans un article : une légende numérotée à références croisées.

Comme il s’agit d’un guide des fonctionnalités de Quarto, chaque exemple est auto-démonstratif — vous voyez le code source, et immédiatement en dessous le tableau que Quarto a produit à partir de ce code source. La référence complète des options se trouve dans la documentation des tableaux Quarto ; cette leçon en est le chemin pratique.

Tables Markdown à pipes

Pour un petit tableau écrit à la main, écrivez une table à pipes : des colonnes séparées par |, et une ligne de séparation faite de tirets sous l’en-tête. Quarto affiche les tables Markdown à pipes standard d’emblée.

Les caractères : dans la ligne de séparation définissent l’alignement de chaque colonne :

  • --- — alignement par défaut
  • :--- — aligné à gauche
  • ---: — aligné à droite
  • :---: — centré

Source :

| Package | Speed  | Output quality     |
|:--------|:------:|-------------------:|
| kable   | fast   | good               |
| gt      | fast   | publication-grade  |

: R packages for tables in Quarto

Rendu :

Packages R pour les tableaux dans Quarto
Package Vitesse Qualité de sortie
kable rapide bonne
gt rapide qualité publication

La ligne commençant par : sous le tableau est la légende. Remarquez comment « Package » est aligné à gauche, « Vitesse » centré et « Qualité de sortie » poussé à droite — exactement ce que la position des : demandait.

Mettez-le en forme avec les classes Bootstrap

Ajoutez un attribut {.class} après la légende pour restyliser le tableau avec les classes de tableau Bootstrap. Les deux que vous utiliserez le plus sont .striped (ombrage alterné des lignes) et .hover (surbrillance de la ligne au survol).

Source :

| Package | Speed  | Output quality     |
|:--------|:------:|-------------------:|
| kable   | fast   | good               |
| gt      | fast   | publication-grade  |

: R packages for tables in Quarto {.striped .hover}

Rendu :

Packages R pour les tableaux dans Quarto
Package Vitesse Qualité de sortie
kable rapide bonne
gt rapide qualité publication

Contrôler la largeur des colonnes

Par défaut, Quarto dimensionne les colonnes selon leur contenu. Pour reprendre la main, ajoutez l’attribut tbl-colwidths — une liste de largeurs relatives (traitées comme des pourcentages).

Source :

| Package | Speed  | Output quality     |
|:--------|:------:|-------------------:|
| kable   | fast   | good               |
| gt      | fast   | publication-grade  |

: R packages for tables in Quarto {tbl-colwidths="[50,20,30]"}

Rendu :

Packages R pour les tableaux dans Quarto
Package Vitesse Qualité de sortie
kable rapide bonne
gt rapide qualité publication

Pour appliquer les mêmes largeurs à chaque tableau d’un document, définissez tbl-colwidths une seule fois dans l’en-tête YAML au lieu de le faire par tableau :

---
title: "My report"
format: html
tbl-colwidths: [50, 20, 30]
---

Tableaux à partir d’un data frame avec knitr::kable()

Écrire des tables à pipes à la main convient pour quelques lignes fixes, mais dès que les nombres proviennent de R, vous voulez les générer — retapez-les à la main et ils se désynchroniseront de votre analyse. Passez le data frame à knitr::kable() et il produit une table Markdown que Quarto met ensuite en forme.

Ici, nous résumons mtcars en R de base et transmettons le résultat à kable(). Le chunk utilise #| echo: fenced, qui affiche la cellule de code complète — la clôture ```{r} et ses options incluses — afin que vous voyiez le code source exact et le tableau rendu :

```{r}
library(knitr)
agg <- aggregate(mpg ~ cyl, data = mtcars, FUN = mean)
agg$mpg <- round(agg$mpg, 1)
kable(agg, col.names = c("Cylinders", "Mean MPG"))
```
Cylinders Mean MPG
4 26.7
6 19.7
8 15.1

Le tableau ci-dessus est un résultat réel : la consommation de carburant passe d’environ 26.7 MPG (miles par gallon) pour les voitures à 4 cylindres à 15.1 pour celles à 8 cylindres. Modifiez les données ou l’agrégation et le tableau se met à jour au rendu suivant — c’est tout l’intérêt de le calculer plutôt que de le taper.

Note

kable() gère un tableau à la fois et couvre la grande majorité des besoins en rapports. Lorsque vous avez besoin d’un contrôle plus fin — notes de bas de page, en-têtes groupés, mise en forme conditionnelle — passez à gt, juste après.

Tableaux de qualité publication avec gt

Le package gt produit une sortie selon la « grammaire des tableaux » : un titre et un sous-titre, une colonne d’étiquettes de lignes (stub), des colonnes renommées, des nombres mis en forme et du style — le remplaçant moderne et activement développé d’anciens utilitaires comme xtable et pander. Il s’affiche nativement en HTML depuis un document Quarto.

Commencez par gt(), puis ajoutez les éléments par couches. Ici, nous ajoutons un en-tête et des étiquettes de colonnes lisibles :

```{r}
library(gt)
cars_head <- head(mtcars[, c("mpg", "cyl", "hp")])
gt(cars_head, rownames_to_stub = TRUE) |>
  tab_header(
    title = "Fuel economy",
    subtitle = "First rows of the mtcars dataset"
  ) |>
  cols_label(mpg = "MPG", cyl = "Cylinders", hp = "Horsepower")
```
Fuel economy
First rows of the mtcars dataset
MPG Cylinders Horsepower
Mazda RX4 21.0 6 110
Mazda RX4 Wag 21.0 6 110
Datsun 710 22.8 4 93
Hornet 4 Drive 21.4 6 110
Hornet Sportabout 18.7 8 175
Valiant 18.1 6 105

rownames_to_stub = TRUE promeut les noms de lignes (les modèles de voitures) dans une colonne d’étiquettes à gauche (stub), tab_header() ajoute le bandeau titré, et cols_label() renomme les colonnes pour l’affichage sans toucher aux données sous-jacentes. À partir de là, gt monte en puissance avec les bandeaux, les notes de bas de page et la mise en forme des nombres — mais, même ainsi, cela se lit déjà comme un tableau tiré d’un article plutôt que comme une impression de console.

Référencer un tableau par son numéro

Un rapport qui se lit comme un article renvoie à ses tableaux par leur numéro — « voir le tableau 1 » — et conserve ce numéro exact lorsque vous insérez un tableau au-dessus. Quarto s’occupe de la numérotation et des liens à votre place si vous suivez deux règles de la documentation sur les références croisées :

  1. Donnez à la cellule de code un #| label: qui commence par tbl-.
  2. Ajoutez un #| tbl-cap: — le texte de la légende.

Ensuite, référencez-le n’importe où avec @tbl-….

```{r}
#| label: tbl-mpg-by-cyl
#| 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"))
```
Table 1: Average miles-per-gallon by cylinder count
Cylinders Mean MPG
4 26.7
6 19.7
8 15.1

Désormais, écrire @tbl-mpg-by-cyl dans votre prose produit un lien numéroté et actif. Par exemple — Table 1 montre que la consommation de carburant baisse régulièrement à mesure que le nombre de cylindres augmente. Quarto a transformé ce @tbl-… en « Tableau 1 » et l’a relié, et si vous ajoutez un autre tableau au-dessus, le numéro se met à jour automatiquement.

Référencer une table Markdown

Une table écrite à la main fonctionne de la même manière : placez un identifiant {#tbl-…} dans la légende au lieu d’une option de cellule.

Source :

| Cylinders | Mean MPG |
|:----------|---------:|
| 4         | 26.7     |
| 6         | 19.7     |
| 8         | 15.1     |

: Average MPG by cylinder count {#tbl-md-mpg}

See @tbl-md-mpg for the summary.

Rendu :

Table 2: MPG moyen par nombre de cylindres
Cylindres MPG moyen
4 26.7
6 19.7
8 15.1

Voir Table 2 pour le résumé.

Regrouper des sous-tableaux dans une seule figure

Pour afficher deux tableaux liés côte à côte sous un même numéro, donnez à une seule cellule un #| label: principal, plus une liste #| tbl-subcap: et un #| layout-ncol:. Chaque tableau que votre code imprime devient un sous-tableau désigné par une lettre.

```{r}
#| label: tbl-panel
#| tbl-cap: "Two views of the mtcars dataset"
#| tbl-subcap:
#|   - "First rows"
#|   - "Last rows"
#| layout-ncol: 2
library(knitr)
kable(head(mtcars[, c("mpg", "cyl", "hp")]))
kable(tail(mtcars[, c("mpg", "cyl", "hp")]))
```
Table 3: Two views of the mtcars dataset
(a) First rows
mpg cyl hp
Mazda RX4 21.0 6 110
Mazda RX4 Wag 21.0 6 110
Datsun 710 22.8 4 93
Hornet 4 Drive 21.4 6 110
Hornet Sportabout 18.7 8 175
Valiant 18.1 6 105
(b) Last rows
mpg cyl hp
Porsche 914-2 26.0 4 91
Lotus Europa 30.4 4 113
Ford Pantera L 15.8 8 264
Ferrari Dino 19.7 6 175
Maserati Bora 15.0 8 335
Volvo 142E 21.4 4 109

Table 3 porte désormais les deux tableaux, et vous pouvez pointer vers l’une ou l’autre moitié — Table 3 (a) pour les premières lignes, Table 3 (b) pour les dernières.

Tables en grille pour un contenu de cellule riche

Les tables à pipes ne contiennent que du texte brut. Lorsqu’une cellule a besoin d’une liste, de plusieurs paragraphes ou d’un autre contenu de bloc, utilisez une table en grille — les bordures + et = permettent à une cellule de contenir n’importe quel Markdown. La ligne de = sépare l’en-tête du corps.

Source :

+-----------+-------------------------+
| Package   | Good for                |
+===========+=========================+
| kable     | - quick data frames     |
|           | - light reports         |
+-----------+-------------------------+
| gt        | - polished tables       |
|           | - titles & footnotes    |
+-----------+-------------------------+

: When to use each package

Rendu :

Quand utiliser chaque package
Package Bon pour
kable
  • data frames rapides
  • rapports légers
gt
  • tableaux soignés
  • titres et notes

Les tables en grille sont délicates à aligner à la main — l’éditeur visuel de RStudio/Positron les écrit pour vous si vous préférez ne pas compter les espaces.

Déplacer la légende

Par défaut, la légende se place au-dessus du tableau. Réglez tbl-cap-location sur top, bottom ou margin — par document dans le YAML, ou par tableau sous forme d’attribut :

---
tbl-cap-location: bottom
---

Problèmes fréquents

Une référence @tbl- s’affiche littéralement comme ?@tbl-name (un lien cassé). Quarto n’a pas trouvé cette étiquette. Deux choses doivent concorder : le #| label: de la cellule doit commencer par tbl- et correspondre exactement à la référence, et la cellule doit aussi porter un #| tbl-cap: — un tableau étiqueté sans légende n’est pas enregistré comme référençable. Vérifiez l’orthographe et ajoutez la légende.

Un data frame s’affiche en texte monospace gris au lieu d’un tableau. Un mtcars seul (ou un print()) dans une cellule de code déverse la représentation console. Encadrez-le : kable(mtcars) ou gt(mtcars). Ce n’est qu’alors que Quarto obtient une table Markdown/HTML à mettre en forme.

Un tableau gt est parfait en HTML mais casse en PDF ou Word. gt s’affiche nativement en HTML ; les autres formats passent par une étape de capture d’écran (le package webshot2 plus Chromium) qui n’est pas toujours installée. Si vous ciblez le PDF ou Word et rencontrez des soucis, knitr::kable() est le choix le plus portable — il produit une table native dans tous les formats de sortie de Quarto.

Questions fréquentes

Passez le data frame à knitr::kable() dans une cellule de code {r} : kable(head(mtcars)). Quarto met en forme le résultat sous forme de tableau dans le document rendu. Pour un tableau plus soigné, de qualité publication, utilisez plutôt le package gt : gt(head(mtcars)).

knitr::kable() est léger et portable — il produit une table native dans tous les formats de sortie de Quarto (HTML, PDF, Word) et convient parfaitement aux rapports rapides. gt est un système plus riche, de qualité publication, avec titres, bandeaux, notes de bas de page et mise en forme des nombres ; il s’affiche nativement en HTML et constitue le remplaçant moderne de xtable/pander. Utilisez kable pour la vitesse et la portabilité, et gt lorsque le tableau est un livrable.

Pour une table Markdown, ajoutez en dessous une ligne commençant par : (: Ma légende). Pour un tableau calculé, définissez l’option de cellule #| tbl-cap:. Les deux placent par défaut une légende au-dessus du tableau ; changez la position avec tbl-cap-location: bottom (ou top/margin).

Donnez au tableau une étiquette qui commence par tbl- — #| label: tbl-summary pour une cellule de code, ou {#tbl-summary} dans une légende Markdown — et assurez-vous qu’il possède une légende. Écrivez ensuite @tbl-summary dans votre prose ; Quarto le rend sous la forme d’un « Tableau 1 » numéroté et cliquable, et renumérote automatiquement lorsque des tableaux sont ajoutés ou déplacés.

Ajoutez l’attribut tbl-colwidths après la légende — {tbl-colwidths="[50,20,30]"} — avec une largeur relative par colonne (traitée comme un pourcentage). Pour appliquer les mêmes largeurs à chaque tableau du document, définissez tbl-colwidths: [50, 20, 30] une seule fois dans l’en-tête YAML.

Tâche. Vous disposez d’un data frame R results et vous voulez qu’il apparaisse sous la forme d’un tableau légendé auquel vous pourrez faire référence ailleurs comme « Tableau 1 ». Écrivez la cellule de code (avec ses options) qui produit un tableau référençable, et montrez comment vous y feriez référence dans le texte.

Il vous faut deux options de cellule — l’une pour donner au tableau un nom que Quarto peut retrouver, l’autre pour lui donner une légende. L’étiquette doit commencer par un préfixe précis de trois lettres. Référencez-la avec le symbole @.

```{r}
#| label: tbl-results
#| tbl-cap: "Model results"
library(knitr)
kable(results)
```

See @tbl-results for the full results.

Le #| label: commence par tbl-, donc Quarto traite la cellule comme une référence croisée de tableau ; le #| tbl-cap: fournit la légende. Écrire @tbl-results dans la prose produit un « Tableau 1 » numéroté et lié — et si vous ajoutez un tableau au-dessus, le numéro se met à jour tout seul.

Vous écrivez une cellule de code avec #| label: tbl-costs et kable(costs), mais sans #| tbl-cap:. Dans le texte, vous écrivez @tbl-costs. Que se passe-t-il au rendu ?

A. Il s’affiche comme « Tableau 1 » et le lien fonctionne correctement. B. La référence est cassée (rendue comme ?@tbl-costs) parce qu’un tableau référençable a besoin d’une légende. C. Le tableau disparaît entièrement.

B. Un tableau étiqueté ne devient référençable qu’une fois qu’il possède aussi un #| tbl-cap:. Sans la légende, Quarto n’enregistre pas l’étiquette, donc @tbl-costs ne peut pas être résolue et s’affiche comme un ?@tbl-costs cassé. Ajoutez le #| tbl-cap: et la référence fonctionne.

Conclusion

Trois voies, une seule décision : tapez une table à pipes pour un petit tableau fixe, appelez knitr::kable() quand les nombres proviennent de R et que vous voulez de la portabilité, et utilisez gt quand le tableau est un livrable soigné. Ajoutez une étiquette tbl- plus une légende et Quarto le numérote et le relie à votre place, de sorte que votre rapport renvoie à ses tableaux comme le fait un article. Choisissez la voie qui correspond à l’origine des données, et laissez le rendu tout garder synchronisé.

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 tableau de cette page a été produit par le code source montré juste au-dessus — copiez n’importe quel bloc et exécutez-le pour les reproduire. The runtime is the judge.

Réutilisation

Citation

BibTeX
@online{2026,
  author = {},
  title = {Tableaux dans Quarto : Markdown, knitr::kable et gt},
  date = {2026-07-08},
  url = {https://www.datanovia.com/learn/programming/quarto/tables},
  langid = {fr}
}
Veuillez citer ce travail comme suit :
“Tableaux dans Quarto : Markdown, knitr::kable et gt.” 2026. July 8. https://www.datanovia.com/learn/programming/quarto/tables.