
1 Introduction
Quarto est un système de publication scientifique et technique open-source de nouvelle génération. Il vous permet de combiner du texte narratif avec du code (en Python, R, Julia, et Observable) pour créer des documents soignés et entièrement reproductibles.
1.1 ✨ Pourquoi choisir Quarto ?
- Multi-langage : Écrivez du code en Python, R, et Julia dans le même document.
- Multi-format : Exportez le même fichier source en HTML, PDF, MS Word, présentations (Power Point, Beamer, ReavelJs), dashboards, et plus encore.
- Reproductibilité : Votre document final contient à la fois le code et ses résultats. N’importe qui peut ré-exécuter votre analyse.
- Simplicité : La syntaxe Markdown est facile à apprendre, et les options avancées sont claires et puissantes.
1.2 Public Cible
Toute personne (analyste, chercheur, étudiant) qui manipule des données et souhaite communiquer ses résultats de manière claire, professionnelle et reproductible.
1.3 Objectifs de ce guide
- Installer Quarto et comprendre la structure d’un document (
.qmd). - Mélanger texte (Markdown) et code (Python, R…) dans un même fichier.
- Contrôler l’affichage et l’exécution du code.
- Mettre en forme vos documents avec des composants avancés.
- Exporter votre travail dans plusieurs formats.
- ✨ Découvrir des fonctionnalités clés comme les références croisées et la bibliographie.
1.4 ✨ Avant de Commencer : Installation
Avant toute chose, vous devez installer Quarto. C’est très simple :
Téléchargez le Quarto CLI depuis le site officiel.
Utilisez un éditeur de code qui a une bonne intégration avec Quarto, comme
Une fois installé, vous pouvez créer un nouveau fichier avec l’extension .qmd et commencer à écrire !
2 Partie 1 : L’Anatomie d’un Document Quarto
Un document Quarto est un simple fichier texte .qmd composé de trois éléments.
2.1 L’en-tête YAML
C’est le “panneau de contrôle” de votre document, situé tout en haut et délimité par ---. Il définit les métadonnées (titre, auteurn date, …) et les options de formatage.
---
title: "Mon Rapport"
subtitle: "Un sous-titre"
author:
- name: Nom Prénom
email: prenom.nom@mail.net
institute: Mon Institut
date: today
1execute:
echo: true
eval: true
code-fold: true
2format:
html:
3 toc: true
4 toc-depth: 2
5 theme: cosmo
pdf:
6 documentclass: scrreprt
toc: true
toc-depth: 2
7 number-sections: true
8 number-depth: 2
---- 1
- Paramètres pour l’exécution du code (R, Python, Julia, …)
- 2
- Possibilité de définir plusieurs formats de sortie.
- 3
- Activer ou non la table des matières.
- 4
- La profondeur de la table des matières.
- 5
- Plusieurs thèmes sont disponibles.
- 6
- Classe \(\LaTeX\) pour la sortie PDF.
- 7
- Activer ou non la numérotation des sections et sous-sections.
- 8
- La profondeur de numérotation des sections et sous-sections.
Pour plus de détails, consultez le site de la documentation de Quarto.
2.2 Le Texte en Markdown
Tout le contenu narratif est écrit en Markdown, une syntaxe simple pour formater du texte.
# Titre de niveau 1
Ceci est une section de texte. On peut mettre du texte en **gras** ou en *italique*.
Voici une liste à puces:
- Item 1
- Item 2
Voici une liste numérotée, avec sous-listes:
1. Item 1
a. Sous-item a
b. Sous-item b
2. Item 2
## Sous-section 1
Voici une sous-section.Vous trouverez les bases du Markdown ici.
2.3 Les Blocs de Code (Code Chunks)
C’est ici que la magie opère. Vous insérez votre code dans des blocs délimités par ```{python} (ou {r}, {julia}). Lorsque vous “rendrez” le document, Quarto exécutera ce code et inclura les résultats (texte, tableaux, graphiques) dans le document final.
```{python}
import pandas as pd
import seaborn as sns
df = sns.load_dataset('iris')
df.head()
```3 Partie 2 : Le Cœur de Quarto : Le Code
3.1 Maîtriser les options des blocs de code
Vous pouvez contrôler précisément comment chaque bloc de code se comporte grâce aux options #|.
#| echo: false: Le code ne sera pas affiché (mais il sera exécuté).#| eval: false: Le code sera affiché, mais pas exécuté.#| include: false: Le code est exécuté, mais ni le code ni sa sortie ne sont affichés.#| fig-cap: "...": Ajoute une légende à un graphique.#| label: fig-iris: ✨ Ajoute une étiquette pour pouvoir référencer le graphique plus tard.
```{python}
#| label: fig-iris-scatter
#| fig-cap: "Relation entre la longueur et la largeur des sépales."
sns.scatterplot(data=df, x='sepal_length', y='sepal_width', hue='species')
```3.2 ✨ Le Code en Ligne (Inline Code)
Une fonctionnalité extrêmement puissante est la capacité d’insérer des résultats de code directement dans votre texte. Cela garantit que vos chiffres sont toujours à jour avec vos données.
La syntaxe est `!expr python_code` pour Python ou `r r_code` pour R.
Le jeu de données Iris contient `!expr len(df)` observations.
La longueur moyenne des sépales est de `!expr df['sepal_length'].mean().round(2)` cm.4 Partie 3 : Mettre en Forme comme un Pro
Quarto offre des outils puissants pour organiser votre contenu.
4.1 Les Avertissements (Callouts)
Parfait pour attirer l’attention sur une information importante.
:::{.callout-note}
Ceci est une note. L'espèce Setosa est clairement séparée des autres.
::::::{.callout-important}
Ceci est une note importante. L'espèce Setosa est clairement séparée des autres.
:::4.2 La Mise en Page en Colonnes et les Onglets
Idéal pour présenter différentes facettes d’une analyse sans surcharger la page.
:::{.panel-tabset}
### Graphique
Le graphique est visible dans la Figure @fig-iris-scatter.
### Données
```{python}
#| echo: false
df.describe()
```
:::4.3 ✨ Les Références Croisées
Grâce aux étiquettes (#| label: ...), vous pouvez facilement faire référence à vos figures, tableaux ou sections.
Exemple :
Comme nous pouvons le voir dans la **Figure @fig-iris-scatter**,
il existe une corrélation claire...5 Partie 4 : Exporter, Partager et Aller Plus Loin
5.1 Le Rendu
Pour transformer votre fichier .qmd en un document final, vous avez plusieurs options selon votre environnement de travail.
Terminal (Ligne de commande)
C’est la méthode universelle. Ouvrez un terminal dans le dossier de votre projet et exécutez :
quarto render mon_document.qmd✨ RStudio IDE
L’intégration de Quarto dans RStudio rend le processus très simple.
- Cliquez sur le bouton Render situé au-dessus de votre éditeur de texte.
- Ou utilisez le raccourci clavier
Ctrl+Shift+K(Windows/Linux) ouCmd+Shift+K(macOS).
✨ VS Code / Positron
Si vous utilisez VS Code ou Positron avec l’extension Quarto officielle :
- Cliquez sur le lien Render ou Preview en haut à droite de la fenêtre de l’éditeur.
- Ou, ouvrez la palette de commandes avec
Ctrl+Shift+P(Windows/Linux) ouCmd+Shift+P(macOS) et tapezQuarto: Render Document.
5.2 Personnaliser la sortie avec YAML
Pour générer un PDF, par exemple, changez format: html en format: pdf (cela nécessite une installation LaTeX). Vous pouvez aussi spécifier plusieurs formats et leurs options.
---
title: "Rapport Avancé"
format:
html:
toc: true
toc-depth: 2
code-fold: true
theme: cosmo
pdf:
documentclass: scrreprt
---5.3 ✨ Ajouter une Bibliographie
Pour un document académique ou technique, une bibliographie est essentielle.
- Créez un fichier
references.bibavec vos citations au format BibTeX. - Ajoutez la clé
bibliography: references.bibà votre en-tête YAML. - Citez vos sources dans le texte avec la syntaxe
[@auteur_annee].
Exemple : Quarto a été développé par Posit, anciennement RStudio [@allaire_quarto_2022].
6 Conclusion
Vous avez maintenant toutes les clés en main pour commencer à créer des documents riches et reproductibles avec Quarto. De la simple analyse aux rapports complexes, Quarto s’adapte à vos besoins et vous permet de vous concentrer sur l’essentiel : vos données et votre message.
- Créez un nouveau fichier
.qmdet son en-tête YAML (titre, auteur, formathtml). - Écrivez une introduction expliquant que vous allez analyser le jeu de données
penguins. - Ajoutez un bloc de code qui charge le jeu de données
penguinsde Seaborn et affiche les 5 premières lignes. Cachez le code de ce bloc (echo: false). - ✨ Dans une phrase, utilisez du code en ligne pour indiquer le nombre total de manchots dans le jeu de données.
- Créez un nuage de points de la longueur des nageoires (
flipper_length_mm) en fonction de la masse corporelle (body_mass_g). Ajoutez une légende et une étiquette (label) au graphique. - Utilisez un callout pour résumer ce que la Figure @votre-etiquette montre.
- Rendez le document en utilisant la méthode de votre choix et admirez votre rapport dynamique!