Quarto

Markdown
Contenu
Rendu
Introduction à Quarto
Author

Ludovic Deneuville

Note

Ce site est réalisé avec Quarto.

  • le contenu de chacune des pages de ce site est dans des fichiers qmd (voir dépôt GitHub)
  • le rendu html est généré avec Quarto
  • les pages html sont ensuite hébergées sur un site internet statique (via GitHub pages)

1 Quarto, c’est quoi ?

Quarto est un outil permettant de produire des documents à partir d’un fichier source.

Dans un même fichier, nous pouvons mélanger :

  • des métadonnées permettant de définir le rendu souhaité
  • du texte en Markdown
  • du code, par exemple en R ou en Python
  • les résultats produits par ce code

Le fichier source est généralement un fichier .qmd (Quarto Markdown).

1.1 Un même fichier, plusieurs rendus

À partir d’un même fichier .qmd, Quarto peut produire différents types de documents, par exemple :

                  fichier source
                      .qmd
                       │
                       ▼
                 ┌───────────┐
                 │   Quarto  │
                 └─────┬─────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
        HTML          PDF       diaporama

L’intérêt est donc de séparer le contenu de sa mise en forme finale.

Nous écrivons une seule fois le contenu, puis nous choisissons les formats dans lequels on souhaite le publier.

1.2 Exemple

À gauche, vous avez le contenu rédigé, à droite la mise ne forme gérée par Quarto.

- Vous êtes en train de lire le rendu html
- Le code pour générer cette page est visible via le bouton `</> Code` en haut à droite
  • Vous êtes en train de lire le rendu html
  • Le code pour générer cette page est visible via le bouton </> Code en haut à droite

2 D’où vient cette idée ?

D’un script R à un document R + Markdown

Prenons un exemple simple. Nous souhaitons analyser les notes d’une classe.

2.1 Étape 1 — Un fichier R

Nous pouvons commencer par créer un fichier analyse.R :

analyse.R
notes <- c(12, 15, 9, 14, 18, 11, 12, 12, 14)

# Calcul de la moyenne
moyenne <- mean(notes)

# Diagramme en barre
hist(notes, breaks = seq(8, 18))

Le fichier contient principalement du code.

Les commentaires permettent d’expliquer le code. Mais ils ne sont pas réellement destinés à constituer un document à destination du lecteur.

2.2 Ajouter du texte : le R Markdown

Nous souhaitons maintenant produire un petit rapport. Utilisons un fichier .Rmd :

analyse.Rmd
**Résultats :**

Nous avons relevé les notes suivantes :

```{r}
notes <- c(12, 15, 9, 14, 18, 11, 12, 12, 14)
moyenne <- mean(notes)
hist(notes, breaks = seq(8, 18))
```

La moyenne de la classe (`{r} moyenne`) est donc calculée à partir des données ci-dessus.

Résultats :

Nous avons relevé les notes suivantes :

notes <- c(12, 15, 9, 14, 18, 11, 12, 12, 14)
moyenne <- mean(notes)
hist(notes, breaks = seq(8, 18))

La moyenne de la classe (13) est donc calculée à partir des données ci-dessus.

Le fichier contient maintenant :

  • du texte destiné au lecteur
  • du code R regroupé dans des blocs de code appelés chunk
  • les résultats produits par ce code

Nous pouvons ainsi produire automatiquement un rapport à partir de l’analyse. 🎉

Tip

Ainsi il est possible d’avoir directement ses figures dans son rapport. Plus besoin de :

  • générer sa figure
  • exporter l’image
  • la réimporter dans son rapport
  • et devoir tout recommencer au moindre changement 😡

2.3 Puis Quarto

Quarto reprend cette idée, mais la généralise.

La grande différence est que Quarto n’est pas limité à R, mais il est possible d’utiliser Python, Julia et d’autres langages.

Les fichiers .Rmd deviennent des .qmd. Mais le principe reste le même, c’est un mélange de texte, code et résultats.

3 La « moulinette » Quarto

Le fichier .qmd constitue le fichier source.

Quarto va le transformer en document final.

On peut voir Quarto comme une moulinette :

  1. Quarto lit le fichier .qmd
  2. il exécute les morceaux de code
  3. il récupère les résultats
  4. il applique la mise en forme
  5. il produit le document final

3.1 Les métadonnées du document

Les premières lignes d’un fichier .qmd permettent de définir des métadonnées.

Elles permettent d’indiquer par exemple :

  • le titre
  • l’autrice
  • le ou les formats de rendu avec des options spécifiques à chaque format

Elles sont placées dans l’en-tête du fichier, entre ---.

Exemple
---
title: "Analyse des résultats"
author: "Alyssa"
format:
  html:
    number-sections: true
    toc: true
  typst:
    papersize: a4
    fontsize: 11pt
  revealjs: default
---

Le document ci-dessus va générer à la fois :

  • un fichier html pour un site web
  • un fichier typst (pdf)

3.2 Principe général

Nous pouvons résumer le fonctionnement de Quarto ainsi :

┌─────────────────────────────────┐
│          fichier .qmd           │
│  • métadonnées                  │
│  • texte                        │
│  • code                         │
└────────────────┬────────────────┘
                 │
                 │ Quarto
                 ▼
       ┌─────────────────────┐
       │  Exécution du code  │
       │         +           │
       │  mise en forme      │
       └──────────┬──────────┘
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
      HTML       PDF      slides

4 Ressources