Passer de rmarkdown à quarto

De R Markdown à Quarto pour aller plus loin avec ses publications

Christophe Dervieux

Posit

21 juin 2023

Démarrer avec Quarto !

Faisons ensemble !

Créer un projet Quarto depuis RStudio et produire un HTML.

File > New Project…

Menu création de projet Quarto depuis RStudio IDE

$ quarto create project
 ? Type » default
 ? Directory » quarto-101
Creating project at C:\Users\chris\AppData\Local\Temp\quarto-101:
  - Created _quarto.yml
  - Created quarto-101.qmd

Explorons…

quarto-101
+¦¦ quarto-101.qmd
L¦¦ _quarto.yml


_quarto.yml
project:
  title: "quarto-101"
quarto-101.qmd
---
title: "quarto-101"
---

## Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

Produire un HTML

Menu de RStudio IDE dans un document .qmd

Nouveau bouton pour transformer son document dans RStudio IDE

terminal
quarto render quarto-101.qmd # defaults to html
quarto render quarto-101.qmd --to html

Produire un HTML

Capture d'écran de la fenêtre viewer de RStudio IDE après avoir générer un HTML.

Et mes documents existants alors ?

Convertir de .Rmd à .qmd ?

Pas nécessaire car Quarto est compatible!

terminal
quarto render my-favorite.Rmd --to html

À vous !

02:00

Ajoutons au projet

  1. Créer un sous-dossier dans le projet e.g rapports.
  2. Y déposer le fichier .Rmd d’exercices nommé manchots.Rmd tel quel.
  3. Produire un HTML avec quarto preview rapport/manchots.Rmd dans le Terminal.
  4. Produire un HTML avec le bouton Render de l’IDE.

Afficher le bouton Render au lieu de Knit pour un Rmd dans un projet Quarto

Retirer output: html_document de l’en-tête YAML and sauvegarder le fichier : Le bouton Render devrait maintenant apparaître.

De .Rmd à .qmd

Voyons ce qui change!

YAML: l’en-tête

Le “Yet Another Markup Language” ou “YAML Ain’t Markup Language” est toujours utilisé pour fournir des métadonnées au niveau du document.

---
title: "Une histoire de manchots"
author: "C. Dervieux"
date: "21/06/2023"
format: 
  html: 
    toc: true
---

YAML: Chunk options

```{r species, warning=FALSE, fig.width=5, fig.cap="A propos de penguins"}
ggplot(
  penguins,
  aes(
    x = bill_length_mm, y = bill_depth_mm,
    color = species, shape = species
  )
) +
  geom_point() +
  labs(x = "Bill length (mm)", y = "Bill depth (mm)")
```

YAML: Chunk options

```{r}
#| label: bill-dims-species
#| fig-width: 5
#| fig-cap: À propos de penguins
ggplot(
  penguins,
  aes(
    x = bill_length_mm, y = bill_depth_mm,
    color = species, shape = species
  )
) +
  geom_point() +
  labs(x = "Bill length (mm)", y = "Bill depth (mm)")
```

YAML: Chunk options

#| label: bill-dims-species
#| fig-width: 5
#| fig-cap: À propos de penguins

Quarto introduit le “hash pipe” dans #| - c’est la syntaxe préférée, bien que Quarto soit rétrocompatible avec l’ancienne syntaxe R Markdown.

  1. Cohérence entre les computation engine (Jupyter/knitr)
  2. Cohérence entre les options YAML / Chunk / Divs (:::)
  3. Une option par ligne, offrant l’autocomplétion et la validation

YAML: Chunk options

#| fig-width: 5
#| fig-cap: À propos de penguins

Notez que le YAML pour Quarto suivra une syntaxe de type “mot-mot”, avec un tiret - et non un ..

La différence de syntaxe est due au fait que Quarto est plus étroitement aligné sur les noms de format et les options de Pandoc (d’où l’utilisation de - comme séparateur de mots au lieu de _ ou .).

À vous !

05:00

Transformons en .qmd

  1. Copier manchots.Rmd à nouveau-manchots.qmd
  2. Utiliser knitr::convert_chunk_header() sur le fichier .qmd (Regarder l’aide de la fonction)
  3. Vérifier les configurations des chunks de code (. à transformer en - par example1)
  4. Vérifier l’en-tête YAML du fichier .qmd
  5. Produire un HTML du document au format .qmd

Nouvelle fonctionnalité Quarto

Tester l’autocomplétion et validation YAML dans RStudio IDE 🔗

Quarto unifie R Mardown

Retrouvons des fonctionnalités !

Callout Blocks

Logo bookdown

R Markdown Quarto
Custom Blocks de rmarkdown et bookdown à créer et styliser soit même. Callout Blocks disponible dans tous les formats et déjà stylisé. 
::: {.callout-note}

## À propos des 'callouts'

Notez qu'il existe cinq types de 'callout', dont : `note`, `warning`, `important`, `tip`, et `caution`.
:::

À propos des ‘callouts’

Notez qu’il existe cinq types de ‘callout’, dont : note, warning, important, tip, et caution.

Références (Figures, Tables, …)

Logo bookdown

R Markdown Quarto
Disponible avec bookdown dans les formats “book” (ex. gitbook()) ou les variantes comme html_document2() Cross References disponible dans tous les formats, pour plus de contenus et configurables.

Changement de syntaxe !

  • Préfixe nécessaire sur le label sous la forme fig- et non fig:
  • Même syntax que citation avec @label et non pas \@ref(label)
Voir @fig-quarto-schematic pour une illustration du fonctionnement de Quarto par Alison Horst.

![Un schéma illustré de Quarto](images/quarto-schematics.png){#fig-quarto-schematic}

Références (Figures, Tables, …)

Logo bookdown

Voir @fig-quarto-schematic pour une illustration du fonctionnement de Quarto par Alison Horst.

![Un schéma illustré de Quarto](images/quarto-schematics.png){#fig-quarto-schematic}

Voir Figure 1 pour une illustration du fonctionnement de Quarto par Alison Horst.

A schematic representing rendering of Quarto documents from .qmd, to knitr or jupyter, to plain text markdown, then converted by pandoc into any number of output types including html, PDF, or Word document.

Figure 1: A schematic representing rendering of Quarto documents from .qmd

Illustration extrait de la Keynote “Hello, Quarto” de Julia Lowndes et Mine Çetinkaya-Rundel (RStudio::conf(2022)).

Mise en page avancée

Logo distill

R Markdown Quarto
Disponible pour HTML avec distill (Figure avancée) ou tufte (Contenu dans la marge) Article Layout disponible pour format multiple et plus flexibilité.

À Vous !

10:00

Ajoutez ces fonctionnalités !

Les formats Quarto

Comme R Markdown, on peut produire différents formats de documents.

De multiples formats…

  • format: html
  • format: pdf
  • format: docx
  • format: revealjs
format: 
  html:
    code-fold: true
  pdf:
1    lof: true
2toc: true
1
lof = List Of Figures
2
Exemple d’option commune aux formats HTML et PDF


…basée sur Pandoc

Options Spécifiques - Ex: Themes HTML

Le HTML de Quarto est stylisé avec Bootstrap 5 et des valeurs par défaut choisies pour Quarto.

---
format:
  html:
    theme: litera
---

Options Spécifiques - Ex: Themes HTML

Le HTML de Quarto est stylisé avec Bootstrap 5 et des valeurs par défaut choisies pour Quarto.

---
format:
  html:
    theme: 
      - litera
      - custom.scss
---

Vous pouvez également utiliser un thème et personnaliser les composants avec SCSS/SASS.

Pour en savoir plus sur le sujet: Venez à mon talk ! 😉

Options Spécifiques - Ex: Code tools

format:
  html:
    code-fold: true
    code-tools: true
Capture d'écran du menu ajouté dans un HTML quarto quand code-tools est activé

Découvrir les options !

A moi !

Demo time ! 🕙

Produire un PDF

  • Pas ou peu de changement dans la .qmd utilisé pour produire un HTML.

Si vous voulez essayer…

Il faut être configuré pour LaTeX mais pas très adapté au cadre tuto

  • PDF = LaTeX => Installation de TinyTeX
  • LaTeX = Paquets CTAN => Installation longue
  • Produire un PDF avec LaTeX => Pas si rapide

Ou avoir la dernière pre-release 1.4 pour les nouveautés ! 😉

Questions ?

Voyons maintenant comment produire des contenus plus élaborés avec Quarto

Next

🔗 cderv.quarto.pub/tuto-quarto-rr2023