Personnaliser ses documents Quarto

À la découverte de `_brand.yml`

Christophe Dervieux

Posit PBC

20 mai 2025

Un système de publication scientifique et technique open-source, intégrant l’exécution de code.

Quarto est l’évolution de R Markdown

• il unifie et améliore l’écosystème R Markdown, pour les utilisateurs R.
• il l’étend pour les personnes qui ne connaissent pas R Markdown (Python, Julia, Observable, …)

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

Produire des HTML

---
format: html
---

Produire des PDF

---
format: typst
---

Déjà bien, mais…

Les organisations ont besoin de personnaliser leurs documents selon leur charte graphique.

Source: https://slides.garrickadenbuie.com/brand-yml-shiny/

Prenons un exemple

Prenons un exemple

Source: https://slides.garrickadenbuie.com/brand-yml-shiny/

Produire des HTML avec _brand.yml

---
format: html
---

Produire des PDF avec _brand.yml

---
format: typst
---

_brand.yml

1. Créez un fichier _brand.yml dans votre projet
2. Définissez les couleurs, les polices, les logos, etc.
3. Il pourra être utilisé par tous les outils supportant _brand.yml

_brand.yml

meta:

meta 🔗 Spec

Information de l’organisation, nom de l’entreprise, URLs, etc.

_brand.yml

meta:

color:

meta 🔗 Spec

Information de l’organisation, nom de l’entreprise, URLs, etc.

color 🔗 Spec

Palette de couleurs de l’image de marque de l’organisation.

_brand.yml

meta:

color:

typography:

meta 🔗 Spec

Information de l’organisation, nom de l’entreprise, URLs, etc.

color 🔗 Spec

Palette de couleurs de l’image de marque de l’organisation.

typography 🔗 Spec

Polices pour les différents éléments.

_brand.yml

meta:

color:

typography:

logo:

meta 🔗 Spec

Information de l’organisation, nom de l’entreprise, URLs, etc.

color 🔗 Spec

Palette de couleurs de l’image de marque de l’organisation.

typography 🔗 Spec

Polices pour les différents éléments.

logo 🔗 Spec

Logos pour l’image de marque de l’organisation.

_brand.yml

meta:

color:

typography:

logo:

defaults:

meta 🔗 Spec

Information de l’organisation, nom de l’entreprise, URLs, etc.

color 🔗 Spec

Palette de couleurs de l’image de marque de l’organisation.

typography 🔗 Spec

Polices pour les différents éléments.

logo 🔗 Spec

Logos pour l’image de marque de l’organisation.

defaults 🔗 Spec

Options pour le support spécifique par des outils utilisant _brand.yml

Pulse Mobile Brand

_brand.yml

meta:
  name: Pulse Mobile
  link: https://pulse.mobile

color:
  palette:
    purple: "#8a2be2"
    blue: "#00c2ff"
    green: "#4dc964"
    yellow: "#ffd600"
    red: "#ff5a5f"
    black: "#121212"
    white: "#f8f8f8"  
  primary: purple
  info: blue
  
typography:
  fonts:
    - family: Montserrat Alternates
      source: google
    - family: Montserrat
      source: google
    - family: Space Mono
      source: google
  base: Montserrat
  headings: 
    family: Montserrat Alternates
    weight: 500
  monospace: Space Mono
  monospace-inline:
    color: purple

logo: 
  images:
    full-color: logos/logomark-full-color.png
    med-color: logos/logomark-med-color.png
    icon-color: logos/icon-color.png
  small: icon-color
  medium: med-color
  large: full-color

_brand.yml avec Quarto

_brand.yml avec Quarto

Pris en compte par défaut

À mettre à la racine du projet Quarto

.
├── report.qmd
├── _brand.yml
└── _quarto.yml

Si le fichier existe, il est automatiquement utilisé par Quarto.

_brand.yml avec Quarto

Configurations possibles

Dans le document ou le _quarto.yml

# fichier à une place différente
brand: brand/_brand.yml

# fichier avec un nom différent
brand: brand/_brand-pulse.yml

# désactiver
brand: false

_brand.yml avec Quarto

Configurations possibles

Dans le document directement

brand:
  color:
    palette:
      purple: "#8a2be2"
    primary: purple
  typography:
    fonts:
      - family: Montserrat Alternates
        source: google
    headings: 
      family: Montserrat Alternates
      weight: 500

Support spécifique à Quarto

Intégration avec les thèmes Quarto

Quarto Themes pour format: html.

équivalent avec un _brand.yml à

mais l’ordre peut être important: Quarto Themes Layering

theme:
  - cosmo       # Un thème bootswatch 
  - tweaks.scss # Une personnalisation par l'utilisateur

Intégration avec les thèmes Quarto

Quarto Themes pour format: html.

équivalent avec un _brand.yml

mais l’ordre peut être important: Quarto Themes Layering

theme:
  - brand       # theme dérivé du `_brand.yml`
  - cosmo       # Un thème bootswatch 
  - tweaks.scss # Une personnalisation par l'utilisateur

Intégration avec les thèmes Quarto

Quarto Themes pour format: html.

équivalent avec un _brand.yml

mais l’ordre peut être important ➡️ Quarto Themes Layering

theme:
  - cosmo       # Un thème bootswatch 
  - brand       # theme dérivé du `_brand.yml`
  - tweaks.scss # Une personnalisation par l'utilisateur

Thèmes Clair et Sombre pour HTML

theme:
  light: flatly
  dark: darkly

brand:
  light: light-brand.yml
  dark: dark-brand.yml

brand:
  light:
    color:
      background: "#ffffff"
      foreground: "#333333"
  dark:
    color:
      background: "#333333"
      foreground: "#ffffff"

Support pour PDF avec Typst

Typst CSS

Une fonctionnalité Quarto 1.5 qui permet de convertir des propriétés CSS en propriétés Typst.

Avantage ➡️ Style similaire entre format HTML et format Typst.

Exemple (Typst à gauche / HTML à droite)

Typst CSS

Adaptation pour _brand.yml

• Variable pour template: brand-color et brand-background-color
  Exemple: Rectangle avec la couleur primaire

  ```{=typst}
  #rect(fill: brand-color.primary)
  ```

• choix du mode sombre ou clair à utiliser

  brand:
    light: light-brand.yml
    dark: dark-brand.yml

  format:
    typst:
      brand-mode: dark

Pour résumer

Un seul fichier à réutiliser

Quarto: document, websites, slides

Shiny for R & Shiny for Python

bslib

Rapports R Markdown

Sites web de documentation de package avec pkgdown

Un seul fichier à réutiliser

Avec des options communes

• Respect de la spécification _brand.yml

• Supports spécifiques

  • brand.defaults.bootstrap pour Quarto et Shiny
  • brand.defaults.shiny.theme pour Shiny

Un seul fichier à réutiliser

lire _brand.yml avec bslib

brand <- attr(bslib::bs_theme(), "brand") 

Un seul fichier à réutiliser

lire _brand.yml avec bslib

brand <- attr(bslib::bs_theme(), "brand") 

avec gt

  gt_tab |>
    gt::tab_style(
      style = cell_fill(color = brand$color$palette$blue),
      locations = cells_title()
    ) |>
    tab_style(
      style = cell_text(color = brand$color$palette$purple),
      locations = cells_stub()
    )

Un seul fichier à réutiliser

lire _brand.yml avec bslib

brand <- attr(bslib::bs_theme(), "brand") 

avec ggplot2

  ggplot_object +
    scale_color_manual(
      values = c("Participants" = brand$color$palette$blue),
      name = NULL
    ) +
    scale_fill_manual(
      values = c("Events" = brand$color$palette$purple),
      name = NULL
    )

Un seul fichier à éditer

• Positron, VS Code, RStudio

• brand_yml Python 📦

• brand.yml R 📦 (en projet)

En savoir plus sur brand.yml

• posit-dev.github.io/brand-yml
• posit-dev/brand-yml
• posit.co/blog/unified-branding…

Questions?

Merci!

And thanks to Garrick Aden-Buie letting me reuse part of ‘Theming Made Easy: Introducing Brand YAML for Shiny’ examples.