Se démarquer avec les thèmes HTML Quarto

Rencontres R 2023

Christophe Dervieux

Posit PBC

21 juin 2023

Qu’est-ce que Quarto ?

C’est comme R Markdown non ?

Quarto

C’est un nouveau système de publication scientifique et technique Open-Source, basé sur Pandoc, pensé et construit sur les +10 ans d’expérience avec R Markdown

C’est un outil ligne de commande (CLI), non lié à un language en particulier et qui contient tout le nécessaire.

Terminal

quarto render document.qmd --to html

Illustration de la présentation “Hello, Quarto” par Julia Lowndes et Mine Çetinkaya-Rundel, présentée à la conférence RStudio 2022. Illustré par Allison Horst.

Quarto unifie + étend R Markdown

• Implémentation cohérente de fonctionnalités pour les différents formats de sorties : tabsets, code-folding, syntax highlighting, etc.
• Des valeurs par défaut plus accessibles et une meilleure prise en charge de l’accessibilité.

• Support de R, Python, Julia, Observable, et plus encore via le moteur Jupyter pour les chunks de code exécutables.
• De nouvelles fonctionnalités pour une meilleure expérience: auto-complétion YAML, informations sur les erreurs de syntaxe YAML, etc.

Personnaliser sa sortie HTML avec Quarto

A propos des fonctionnalités de thèmes

Le format HTML

---
title: "Démo HTML"
format: html
---

basique-style.qmd

---
title: "Démo HTML personalisée"
format: 
  html:
    css: monstyle.css
---

• Le thème par défaut est basé sur Bootstrap 5 (variante bslib)
• Des choix par défaut améliorés par rapport à R Markdown
• Modifiable avec un simple CSS

Un choix de thèmes disponibles…

---
title: "Thème Bootswatch"
format: 
  html:
    theme: lux
---

---
title: "Pas de thème"
format: 
  html:
    theme: none
---

• Inclusions de ~25 thèmes Bootswatch
• Similaire à R Markdown avec bslib

…facilement personnalisable !

---
title: "Thème modifié"
format: 
  html:
    theme: lux
    fontsize: 1.1em
    linestretch: 1.7
---

---
title: "Mode Clair / Sombre"
format: 
  html:
    theme:
      dark: darkly
      light: flatly
---

Des configurations simplifiées par YAML:

• Valeur pour des variables CSS
• Thèmes Clair et Sombre
  

Aller plus loin dans la personnalisation !

Quarto themes, powered by SASS

theme:
  - lux
  - perso.scss

theme: theme-perso.scss

Sass https://sass-lang.com est un langage d’extension CSS qui vous permet de créer des règles CSS de manière beaucoup plus souple.

Utilisé par Bootstrap et Reveal JS

Fichier de Thème Quarto

perso.scss

/*-- scss:defaults --*/ 
$h2-font-size:          1.6rem !default;
$headings-font-weight:  500 !default;
$custom-color: blue;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -1px -1px 0 rgba(0, 0, 0, .3);
  color: $custom-color;
}

Il est ainsi possible d’accéder à toutes les variables Bootstrap, et aux variables spécifiques Quarto

Comprendre le mécanisme

Une simplication par rapport à une utilise basique de SASS

• Un unique fichier pour appliquer son thème (SASS de base en demanderait plusieurs)

• Décorateurs de région pour définir les sections (functions, defaults, mixins, and rules)

• Superposition des sections en fonction de leur type pour leur intégration avec les autres configurations (Bootstrap)

• Résolution des fonctionnalités SASS @use ou @import en relatif au thème Quarto

Voir l’article spéciale de la documentation pour comprendre le mécanime de superpositon des sections.

A retenir

• Format HTML basé sur Bootstrap 5

• Différents niveaux de personnalisations sont possibles

• Intégration avec SASS via un fichier de thème unique

• Permet une réutilisation simple des thèmes pour tous les formats HTML (documents, site web, blog, …)

• Permet un partage simplifié des thèmes entre utilisateurs
  (via le mécanisme d’Extension Custom Format)

Pour s’inspirer: Gallerie Quarto
Exemple de thème communautaire: Bookup by Julien Barnier (@juba)
Thèmes clair et sombre basés sur la famille de police Roboto

Des questions ?

Merci!

https://cderv.github.io/rr-2023-quarto-html-theming/

https://github.com/cderv/rr-2023-quarto-html-theming