Options de sortie HTML dans Quarto : table des matières, thème, outils de code et fichiers autonomes

Q: Comment ajouter une table des matières à un document HTML Quarto ?

Ajoutez toc: true sous format: html: dans l’en-tête YAML. Quarto construit automatiquement la table des matières à partir des titres de vos sections. Ajustez-la avec toc-depth (le nombre de niveaux de titre), toc-location (left, right ou body) et toc-title (l’intitulé au-dessus de la liste).

Q: Comment changer le thème d’un document HTML Quarto ?

Définissez theme: sous format: html: sur l’un des 25 thèmes Bootswatch intégrés — par exemple theme: flatly. Pour le mode clair et sombre, passez une paire : theme: {light: cosmo, dark: darkly}. Pour personnaliser davantage, ajoutez votre propre fichier .scss après le thème de base dans une liste.

Q: Comment permettre aux lecteurs de télécharger ou de masquer le code de mon rapport ?

Définissez code-tools: true sous format: html:. Cela ajoute un menu Code au niveau du document (un bouton ) qui permet aux lecteurs d’afficher ou de masquer tout le code d’un coup et de consulter le code source complet du .qmd. Combinez-le avec code-fold: true pour replier le code derrière une bascule Code par bloc.

Q: Comment masquer le code tout en conservant la sortie dans Quarto ?

Définissez echo: false — pour l’ensemble du document sous format: html:, ou pour un seul bloc avec l’option de cellule #| echo: false. Le code s’exécute et sa sortie (figure, tableau, résultat affiché) apparaît toujours ; seul le code source est masqué. Pour conserver le code tout en le glissant derrière une bascule, utilisez plutôt code-fold: true.

Configurez un document HTML Quarto — table des matières, thème, outils de code et un unique fichier portable

Découvrez les principales options de sortie HTML de Quarto — ajoutez une table des matières, choisissez un thème Bootswatch, affichez les boutons de copie et d’outils de code, numérotez les sections et produisez un unique fichier .html autonome que vous pouvez envoyer par e-mail. Tout se règle dans l’en-tête YAML.

Date de publication

8 juillet 2026

Modifié

9 juillet 2026

Points clés

Chaque option HTML se trouve dans l’en-tête YAML, sous format: html:. Réglez-la une fois en haut et elle s’applique à l’ensemble du document.
toc: true ajoute une table des matières ; toc-location, toc-depth et toc-title contrôlent son emplacement, sa profondeur et son intitulé. La table des matières de cette page — à droite, intitulée « Sur cette page » — a été produite exactement ainsi.
theme: choisit une apparence Bootswatch (cosmo, flatly, darkly, …) et accepte une paire clair/sombre. Cette page utilise cosmo en mode clair et darkly en mode sombre.
Les options de code — code-copy, code-fold et code-tools — ajoutent un bouton de copie, une bascule Code repliable et un menu Code au niveau du document. Chacune est montrée en action ci-dessous.
embed-resources: true regroupe chaque image, style et script dans un unique fichier .html autonome que vous pouvez envoyer par e-mail — le remplacement moderne de l’ancienne option self-contained.
Tout est montré en action ici : chaque option ci-dessous apparaît à côté du YAML ou du bloc exact qui l’a produite — copiez n’importe quel bloc et exécutez-le.

Introduction

Vous avez rédigé votre analyse dans un fichier .qmd, et il se compile proprement. Vous voulez maintenant qu’il se lise comme une véritable page web — une table des matières navigable sur le côté, un thème qui ne soit pas le simple rendu par défaut de Pandoc, un bouton de copie sur chaque bloc de code et un unique fichier que vous pouvez joindre à un e-mail sans traîner un dossier d’images éparses.

Tout cela relève de la configuration, pas du code. Vous le réglez dans l’en-tête YAML en haut du document, sous format: html:, et Quarto l’applique à toute la page. Cette leçon parcourt les options les plus courantes, et comme il s’agit d’un guide de fonctionnalités, chacune est auto-démonstrative — la page que vous lisez a été construite avec ces réglages exacts, vous pouvez donc voir chaque option en action et lire le code source qui l’a produite. La liste complète se trouve dans la documentation des bases HTML de Quarto ; c’est le chemin pratique pour la parcourir.

Commencer avec le format html

Le minimum est une ligne format: html. Tout le reste est une sous-option imbriquée en dessous. Un document qui se contente de cela produit un fichier HTML propre, sur une seule page, avec des valeurs par défaut raisonnables :

---
title: "My report"
format: html
---

Pour commencer à personnaliser, développez html en un bloc et ajoutez des options en dessous. C’est la forme utilisée par chaque section ci-dessous :

---
title: "My report"
format:
  html:
    toc: true
    theme: cosmo
---

Le reste de cette leçon remplit ce bloc.

Ajouter une table des matières

Définissez toc: true et Quarto construit une table des matières à partir des titres de vos sections et lie chaque entrée à sa section. Quelques options complémentaires l’ajustent, toutes documentées sous table des matières :

format:
  html:
1    toc: true
2    toc-depth: 3
3    toc-location: right
4    toc-title: "On this page"
5    toc-expand: 1

1: Activer la table des matières.
2: Inclure les niveaux de titre 1 à 3 (la valeur par défaut est 3).
3: La placer à right (également left, ou body pour l’afficher en ligne en haut).
4: Définir l’intitulé affiché au-dessus de la liste (la valeur par défaut est « Table of contents »).
5: Combien de niveaux sont dépliés au départ ; les niveaux plus profonds se déplient automatiquement à mesure que le lecteur fait défiler la page.

Vous n’avez pas à imaginer le résultat : la liste à droite de cette page, intitulée « Sur cette page », est une table des matières en direct — l’en-tête de ce document définit toc: true, toc-location: right et toc-title: "Sur cette page". Chaque option ci-dessus fait son travail en ce moment même.

Numéroter les sections

Pour un rapport qui fait référence à la « Section 3.1 », définissez number-sections: true. Quarto préfixe alors chaque titre d’un numéro hiérarchique automatique et maintient la numérotation correcte à mesure que vous ajoutez ou réorganisez des sections :

format:
  html:
    number-sections: true
    number-depth: 2      # only number levels 1–2, leave deeper headings unnumbered

Cette page laisse délibérément la numérotation des sections désactivée — les titres que vous voyez n’ont pas de « 1 », « 2 », « 3 » devant eux. Activez-la et chaque titre ## afficherait « 1 Introduction », « 2 Ajouter une table des matières », et ainsi de suite. Associez-la aux références croisées (voir les leçons figures et tables) lorsque vous voulez pointer vers une section numérotée depuis votre texte.

Choisir un thème

L’apparence de la page provient de theme:, qui sélectionne l’un des 25 thèmes Bootswatch intégrés — cosmo, flatly, litera, darkly, solar, et d’autres. Une valeur unique thématise l’ensemble du document :

format:
  html:
    theme: flatly

Pour prendre en charge à la fois le mode clair et le mode sombre, passez une paire clair/sombre — le lecteur obtient une bascule, et Quarto échange les thèmes en conséquence :

format:
  html:
    theme:
      light: cosmo
      dark: darkly

Vous pouvez aussi superposer votre propre fichier Sass/SCSS à une base Bootswatch pour remplacer les polices, les couleurs et l’espacement — passez une liste avec le thème de base en premier et votre .scss en second :

format:
  html:
    theme:
      light: [cosmo, custom.scss]
      dark: [darkly, custom.scss]

C’est exactement ce dernier modèle qu’utilise cette page — cosmo/darkly comme base Bootswatch, plus le .scss maison de Datanovia. Actionnez votre interrupteur clair/sombre et regardez toute la page se re-thématiser ; c’est la paire clair/sombre à l’œuvre.

Afficher les outils de code : copie, repli et menu Code

Trois options rendent vos blocs de code plus accueillants pour les lecteurs, toutes présentées dans la documentation du code HTML.

code-copy place un bouton de copie vers le presse-papiers sur chaque bloc de code. Il est activé par défaut dans les versions récentes de Quarto ; définissez-le explicitement pour en être sûr :

format:
  html:
    code-copy: true

Survolez n’importe quel bloc de code de cette page et une icône de copie apparaît dans son coin supérieur droit — c’est code-copy en action.

code-fold replie le code derrière une bascule Code de sorte que la sortie passe en premier et que le code source soit à un clic — pratique pour un rapport axé sur les résultats. Le bloc ci-dessous définit code-fold: true, et grâce à echo: fenced il affiche sa propre clôture de bloc et ses options, de sorte que vous puissiez lire le code source exact une fois qu’il est déplié :

Code

```{r}
#| label: codefold-demo
#| code-fold: true
#| fig-width: 6
#| fig-height: 3.2
#| fig-alt: "Histogram of highway fuel economy for 32 cars, drawn in brand azure."
library(ggplot2)
ggplot(mtcars, aes(mpg)) +
  geom_histogram(bins = 10, fill = "#3a86d4", colour = "white") +
  labs(x = "Miles per gallon", y = "Number of cars") +
  theme_minimal(base_size = 13)
```

Histogram of highway fuel economy for 32 cars, drawn in brand azure.

Le graphique s’est affiché immédiatement ; le code se trouve replié au-dessus de lui derrière la bascule Code. Cliquez dessus pour révéler le code source — y compris la ligne #| code-fold: true qui a produit le repli.

code-tools ajoute un menu Code au niveau du document (un bouton </>, généralement près du coin supérieur droit de la page) qui permet aux lecteurs d’afficher ou de masquer tout le code d’un coup et de consulter le code source complet du .qmd :

format:
  html:
    code-fold: true
    code-tools: true

Pour masquer entièrement le code et n’afficher que la sortie, ne le repliez pas — supprimez l’echo. Définissez echo: false pour l’ensemble du document, ou par bloc avec #| echo: false :

format:
  html:
    echo: false

Regrouper tout dans un seul fichier

Par défaut, un document HTML rendu est accompagné d’un dossier de fichiers de support — images, CSS et JavaScript. C’est parfait pour un site web, mais peu commode à envoyer par e-mail ou à archiver. Définissez embed-resources: true et Quarto intègre chaque dépendance dans un unique fichier .html autonome, sans dossier externe :

format:
  html:
    embed-resources: true

Le résultat est un unique fichier portable que vous pouvez joindre à un e-mail ou déposer sur un lecteur partagé, et qui s’affiche à l’identique partout. C’est l’option moderne : elle remplace l’ancienne self-contained: true, désormais dépréciée au profit d’embed-resources (le comportement est documenté sous self-contained output). Si votre document contient des formules LaTeX rendues et que vous voulez les intégrer aussi, ajoutez self-contained-math: true.

Note

Un fichier autonome est plus volumineux, car chaque image et bibliothèque y est intégrée. Utilisez embed-resources: true pour un document qui doit circuler sous forme d’un seul fichier ; laissez-le désactivé (la valeur par défaut) lorsque vous publiez un site web, où les ressources externes partagées sont mises en cache d’une page à l’autre.

Regrouper le contenu en onglets

Une fonctionnalité HTML connexe qui mérite d’être connue : les jeux d’onglets permettent aux lecteurs de basculer entre des panneaux — une version R et une version Python, par exemple — sans faire défiler la page. Enveloppez le contenu dans ::: {.panel-tabset} et chaque titre à l’intérieur devient un onglet.

Source :

::: {.panel-tabset}
## R

```r
get_sum <- function(a, b) {
  a + b
}
```

## Python

```python
def get_sum(a, b):
  return a + b
```
:::

Rendu :

get_sum <- function(a, b) {
  a + b
}

def get_sum(a, b):
  return a + b

Cliquez entre les onglets ci-dessus — c’est un jeu d’onglets en direct. Ajoutez group="language" à plusieurs jeux d’onglets et Quarto synchronise leur sélection, de sorte que choisir « Python » dans l’un les bascule tous.

Problèmes fréquents

La table des matières est vide ou il manque des titres. Quarto construit la table des matières à partir des titres Markdown de niveau ## (et plus profonds). Un « titre » créé avec du texte en gras (**Introduction**) ou une balise HTML brute <h2> n’est pas pris en compte. Utilisez de vrais titres Markdown ## et définissez toc: true, et chacun apparaît.

Un changement de thème n’apparaît pas après un nouveau rendu. Le navigateur sert une copie en cache de l’ancienne feuille de style. Faites une actualisation forcée (Cmd/Ctrl + Maj + R), et si vous êtes en aperçu, redémarrez l’aperçu pour que Quarto régénère le CSS du thème.

self-contained: true avertit qu’il est déprécié. Renommez-le en embed-resources: true — même résultat en un seul fichier, nom d’option à jour. Si vous voyez encore des fichiers épars après l’avoir défini, vérifiez qu’il est imbriqué sous html: (et non au niveau supérieur) puis relancez le rendu.

Questions fréquentes

Comment ajouter une table des matières à un document HTML Quarto ?

Ajoutez toc: true sous format: html: dans l’en-tête YAML. Quarto construit automatiquement la table des matières à partir des titres de vos sections. Ajustez-la avec toc-depth (le nombre de niveaux de titre), toc-location (left, right ou body) et toc-title (l’intitulé au-dessus de la liste).

Comment changer le thème d’un document HTML Quarto ?

Définissez theme: sous format: html: sur l’un des 25 thèmes Bootswatch intégrés — par exemple theme: flatly. Pour le mode clair et sombre, passez une paire : theme: {light: cosmo, dark: darkly}. Pour personnaliser davantage, ajoutez votre propre fichier .scss après le thème de base dans une liste.

Quelle est la différence entre self-contained et embed-resources dans Quarto ?

Elles font la même chose — regrouper toutes les images, le CSS et le JavaScript dans un unique fichier .html autonome — mais self-contained: true est l’ancienne option, désormais dépréciée, et embed-resources: true est son remplacement actuel. Utilisez embed-resources: true dans les nouveaux documents.

Comment permettre aux lecteurs de télécharger ou de masquer le code de mon rapport ?

Définissez code-tools: true sous format: html:. Cela ajoute un menu Code au niveau du document (un bouton </>) qui permet aux lecteurs d’afficher ou de masquer tout le code d’un coup et de consulter le code source complet du .qmd. Combinez-le avec code-fold: true pour replier le code derrière une bascule Code par bloc.

Comment masquer le code tout en conservant la sortie dans Quarto ?

Définissez echo: false — pour l’ensemble du document sous format: html:, ou pour un seul bloc avec l’option de cellule #| echo: false. Le code s’exécute et sa sortie (figure, tableau, résultat affiché) apparaît toujours ; seul le code source est masqué. Pour conserver le code tout en le glissant derrière une bascule, utilisez plutôt code-fold: true.

Testez vos connaissances

Tâche. Rédigez l’en-tête YAML d’un rapport HTML qui (1) affiche une table des matières à gauche, sur deux niveaux de profondeur ; (2) utilise le thème flatly ; et (3) offre aux lecteurs un menu Code pour afficher ou masquer tout le code.

Indice

Les trois sont des sous-options de html:. La table des matières nécessite toc: plus deux clés complémentaires (une pour le côté, une pour la profondeur). Le menu Code est une seule option booléenne dont le nom se termine par -tools.

Solution

---
title: "My report"
format:
  html:
    toc: true
    toc-location: left
    toc-depth: 2
    theme: flatly
    code-tools: true
---

toc: true active la table des matières, toc-location: left la déplace dans la marge de gauche, et toc-depth: 2 la limite aux deux premiers niveaux de titre. theme: flatly définit l’apparence Bootswatch, et code-tools: true ajoute le menu Code au niveau du document.

Vérification rapide

Vous voulez envoyer par e-mail un unique fichier .html qui s’affiche correctement sans dossier d’images et de feuilles de style associé. Quelle option le produit ?

A. toc: true B. embed-resources: true C. code-tools: true

Afficher la réponse

B. embed-resources: true intègre chaque image, style et script dans un unique fichier autonome — le résultat portable, envoyable par e-mail. toc: true ne fait qu’ajouter une table des matières, et code-tools: true ne fait qu’ajouter le menu Code ; ni l’un ni l’autre ne change la façon dont les ressources du fichier sont empaquetées.

Conclusion

Toutes les options HTML dont vous avez besoin pour un rapport soigné se trouvent au même endroit — le bloc format: html: de votre en-tête YAML. Ajoutez toc: true pour la navigation, choisissez un theme: (une paire clair/sombre si vous voulez une bascule), activez code-copy/code-fold/code-tools pour rendre le code accueillant, et définissez embed-resources: true lorsque le document doit circuler sous forme d’un seul fichier. Définissez-les une fois en haut et Quarto les applique à toute la page — exactement comme il l’a fait pour celle que vous venez de lire.

Leçons connexes

Tableaux dans Quarto — construisez des tableaux markdown, kable et gt dans le document HTML que vous venez de configurer. · Figures dans Quarto — ajoutez, légendez, dimensionnez et référencez de façon croisée des graphiques et des images. · Rédiger avec Quarto — où les options de table des matières, de thème et de code s’intègrent dans le flux de travail complet d’un document.
Pour aller plus loin : Rédiger avec Quarto — la série complète. · Science computationnelle et IA — le pilier.

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

Note

Cette leçon est reproductible : chaque option de cette page a été démontrée par le code source montré directement au-dessus d’elle — 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 = {Options de sortie HTML dans Quarto : table des matières,
    thème, outils de code et fichiers autonomes},
  date = {2026-07-08},
  url = {https://www.datanovia.com/learn/programming/quarto/output-html},
  langid = {fr}
}

Veuillez citer ce travail comme suit :

“Options de sortie HTML dans Quarto : table des matières, thème, outils de code et fichiers autonomes.” 2026. July 8. https://www.datanovia.com/learn/programming/quarto/output-html.