Quarto & PDF avec Typst

PDF sans frictions : Typst dans vos projets Quarto

Christophe Dervieux & Maëlle Salmon

Posit / rOpenSci

16 juin 2026

Le rythme du tutoriel

My turn

Quelques slides pour poser les concepts clés.

Our turn

Démo live — vous suivez dans votre éditeur.

Your turn

Exercice en autonomie avec chronomètre.

Expliquer le rythme dès le début. Chaque bloc suit ce cycle. L’idée c’est de passer un maximum de temps les mains dans le code, pas à regarder des slides.

Un atelier pour tous les niveaux

• Exercices volontairement riches — pas grave si vous ne finissez pas en séance : tout reste à reprendre après (ressources + paquet R compagnon)
• Pas besoin d’écrire du R — le cœur des exos, c’est Quarto / YAML / Typst ; le R des tableaux et graphes est déjà prêt dans les fichiers
• Déjà à l’aise avec Quarto ? — partez en hors-piste : explorez le bonus brand.yml côté R (déjà dans les starters / corrections), doc à l’appui

Annoncer dès le départ : tuto pensé pour tous les niveaux, le rythme My/Our/Your turn cale tout le monde. Trois messages : (1) les exos sont riches exprès — personne n’est censé tout boucler dans le chrono, le matériel reste à eux (site + paquet) pour rejouer après ; (2) débutant·es : on rassure, pas de R à écrire dans les étapes principales ; (3) avancé·es : on les invite explicitement à aller plus loin, hors-piste, vers le branding R (gt/ggplot) déjà présent dans les corrections, en s’aidant des docs — plutôt que d’attendre. ~45 s, ne pas s’attarder.

Le pad partagé de l’atelier

Un bloc-notes collaboratif ouvert à toutes et tous — on y écrit ensemble, en direct.

• 🔗 Les liens de l’atelier (site, ressources, paquet R)
• ❓ Vos questions — posez-les ici, on y répond
• 📝 Vos notes et trouvailles à reprendre après

Gardez-le ouvert pendant les 2 h.

annuel.framapad.org/p/quartorr-aluv

À ouvrir tout de suite avec la salle — projeter l’URL/QR et laisser 30 s pour que chacun·e l’ouvre. C’est notre canal écrit partagé pour toute la durée : on y dépose les liens au fil de l’eau, les participant·es y posent leurs questions (Maëlle et CD y répondent, surtout les questions communes), et tout le monde repart avec les notes. Complémentaire des post-it (signal physique dans l’instant) : le pad, c’est l’écrit qui reste. Pensez à vérifier que le pad existe et est accessible avant la session.

Bloqué·e ? Fini ? Un post-it suffit

Pendant les exercices, posez un post-it sur le dos votre écran — on vous repère d’un coup d’œil, pas besoin de lever la main.

• 🟧 Rose / orange — « je suis bloqué·e » → on passe vous voir
• 🟩 Vert / jaune — « c’est bon, j’ai fini ! »

👉 En clôture, on les recycle en feedback : un point qui vous a plu sur un vert/jaune, un point à améliorer sur un rose/orange.

30 secondes, à montrer juste avant le premier exercice. Le but : un canal de signalement silencieux et lisible depuis le fond de la salle. Rose/orange = appel à l’aide (Maëlle passe dans les rangs, CD rebondit au tableau si la question est commune) ; vert/jaune = terminé (permet de jauger le rythme et d’aiguiller les rapides vers le hors-piste / bonus). Rappeler le double usage : en clôture, on rouvre les deux tas pour récolter un feedback express — positif sur vert/jaune, à améliorer sur rose/orange — à coller sur un mur ou à nous remettre. Cohérence des couleurs : vert/jaune = « ça va », rose/orange = « ça coince », dans les deux temps.

Code de conduite

Cet atelier s’inscrit dans le code de conduite des Rencontres R 2026 — on s’engage à le faire respecter ici comme ailleurs.

L’esprit, en deux mots :

• Un environnement bienveillant et sûr, sans harcèlement, pour toutes et tous
• Respect et bienveillance dans le langage comme dans les échanges
• Un souci, une gêne ? Parlez-nous ou à un membre de l’orga (badge)

Code de conduite complet des Rencontres R 2026

30 secondes, ton sérieux mais sans plomber l’ambiance. Le message clé : on ne fait pas un code à part, on s’inclut dans celui de la conf et on s’engage à le faire vivre dans la salle. Rappeler qu’on est deux (Maëlle passe dans les rangs) et joignables si quoi que ce soit. Pas besoin de lire la liste : donner l’esprit et le lien.

C’est quoi Typst ?

Typst joue le même rôle que LaTeX : produire un PDF. Avec Quarto, vous restez côté Markdown — il traduit vers Typst tout seul.

Ce que vous écrivez (Markdown) :

# Mon rapport

Un mot **en gras**
et un [lien](https://example.org).

Ce que Quarto génère (Typst) :

= Mon rapport

Un mot #strong[en gras]
et un #link("https://example.org")[lien].

Slide visuelle : le but n’est pas d’enseigner Typst, c’est de rassurer. “Tu écris du Markdown, t’as pas besoin d’apprendre Typst pour démarrer.” Le snippet Typst montre la traduction concrète — = pour le titre, #strong[...] pour le gras, #link(...)[...] pour les liens.

Contrat oral : la slide suivante montre le pipeline (.qmd → .typ → PDF), et on ouvrira ensemble le vrai .typ un peu plus loin (keep-typ: true) — pas une option facultative. Le participant est prévenu, pas de surprise à l’Exo 1 étape 3.

On y jettera un œil ensemble avec keep-typ: true — juste pour démystifier.

Du .qmd au PDF

Vue d’ensemble, posée juste après la traduction Markdown→Typst : où se place chaque pièce. Quarto (via Pandoc) traduit votre .qmd en .typ, puis Typst compile ce .typ en PDF. Ce .typ intermédiaire, on l’ouvrira concrètement un peu plus loin avec keep-typ: true.

format: typst — un PDF sans LaTeX

Vous avez un document Quarto et vous voulez un PDF ?

rapport.qmd

---
title: "Mon rapport"
format: typst
---

• Rien à installer — Typst est intégré à Quarto depuis la version 1.5
• Rapide — compilation en quelques secondes, pas plusieurs minutes
• Erreurs lisibles — fini les messages LaTeX cryptiques
• Léger — pas de distribution TeX de 1 Go à gérer

Le point d’entrée : une seule ligne de YAML. Pas besoin de convaincre les gens que LaTeX est mauvais — montrer directement que Typst est simple.

Les options de formats

rapport.qmd

---
format:
  typst:
    toc: true
    papersize: a4
    margin:
      x: 2.5cm
      y: 2.5cm
---

D’autres options existent (mainfont, number-sections, linestretch…) — on les verra en démo.

Ne pas tout montrer ici. Juste papersize et margin pour que les gens voient la structure YAML. Le reste sera manipulé en live.

keep-typ: true — comprendre les coulisses

Souvenez-vous du pipeline : le .typ intermédiaire, entre votre .qmd et le PDF. keep-typ: true le conserve sur le disque pour que vous puissiez l’ouvrir.

rapport.qmd

---
format:
  typst:
    keep-typ: true
---

Le fichier .typ intermédiaire vous permet de :

• Comprendre ce que Quarto génère pour Typst
• Déboguer un rendu inattendu
• Apprendre la syntaxe Typst progressivement

Moment pédagogique clé. Le pipeline démystifie la magie : Quarto n’est pas une boîte noire, on peut voir ce qui se passe entre le .qmd et le .pdf.

_brand.yml — un doc stylé en un fichier

Un seul fichier YAML pour définir l’identité visuelle de vos documents :

_brand.yml

color:
  primary: "#1a5276"
  secondary: "#f39c12"
typography:
  fonts:
    - family: "Noto Sans"
      source: google
  base: "Noto Sans"

• Placez _brand.yml à côté de votre .qmd
• Quarto l’applique automatiquement
• Couleurs, polices, logo…
• Fonctionne avec HTML, Typst, RevealJS…

_brand.yml — un doc stylé en un fichier

Mention orale ~30 sec pendant la démo Our turn : le _brand.yml ne pilote pas que le PDF. Le paquet R brand.yml fournit des helpers theme_brand_ggplot2() et theme_brand_gt() qui appliquent la même charte aux figures et tableaux. Visible dans correction/rapport-starwars.qmd. On en parle pas plus, c’est dans les Ressources.

Parler des helpers R theme_brand_*().

(La Q&A sur le placement du logo — question d’étape 3 du Your turn — est dans _speaker/demo-bloc1-our-turn.qmd, section Pièges.)

Voici la charte

• Une vraie charte à traduire
• Palette nommée + rôles (primary, foreground, background)
• Polices: Inter (Google) + Star Jedi (locale)
• Ce PDF est lui-même rendu par Quarto + Typst + _brand.yml — vous allez faire pareil

Slide-pont entre le concept générique (_brand.yml) et la démo concrète. Le PDF est dans le starter de l’exercice — chaque apprenant·e l’ouvre côté lecteur PDF. Côté Our turn et Your turn : projeter _charte/charte-starwars.pdf à l’écran (ou via 1-quarto-typst/charte-starwars.png si plus rapide) pour que l’apprenant·e voie cible et transcription en parallèle.

Méta-cohérence pédagogique à expliciter à l’oral : « ce PDF que vous tenez n’est pas qu’une spec, c’est un exemple rendu — son logo, ses titres en Star Jedi rouge, sa palette viennent d’un _brand.yml identique à celui que vous allez écrire ».

Le terme « rôles » dans nos supports correspond aux « assignments » de la charte (terme anglais conservé dans la spec _brand.yml) = mapping primary / foreground / background → noms de palette. Le préciser oralement (la charte n’a pas la place de l’expliquer).

Faisons ensemble !

Faisons ensemble !

On passe le doc en PDF Typst, puis on lui applique une couleur via _brand.yml.

1. Ouvrez rapport-starwars.qmd (dossier 01-document-typst/starter/), passez format: html → format: typst, rendez → PDF brut
2. Créez _brand.yml dans le même dossier (à côté du .qmd) avec une seule couleur + rôle primary, re-rendez → le lien de l’intro passe en rouge (primary colore les liens)

_brand.yml

color:
  palette:
    imperial-red: "#BC1E22"
  primary: imperial-red

→ À vous ensuite pour la charte complète (palette + rôles + polices).

Démo live, format ultra-court : 5-6 min max. Le pas-à-pas détaillé (snippet à coller, projection de la charte, ressources, pièges, transition Your turn) est dans le doc animateur dédié _speaker/demo-bloc1-our-turn.qmd — pas de duplication ici (le snippet est déjà sur la slide).

Pourquoi minimal : Our turn montre l’effet d’une édition YAML sur le PDF (une couleur → le lien passe en rouge), Your turn traduit la charte SW complète. Si Our turn fait tout, Your turn = répétition.

Exercice 1

À vous !

🎯 Transformer un .qmd HTML en PDF Typst stylé via _brand.yml.

📄 Charte fournie : charte-starwars.pdf dans le starter (palette + polices + logo + rôles).

⏱ 12 minutes — chrono + étapes projetés à l’écran.

🧭 Boussole — objectif, étapes & chrono, à garder sous les yeux

📖 Page de l’exercice — consigne détaillée, doc utile par étape, correction

12 minutes. Ouvrir la page boussole — 1-quarto-typst/boussole.html — dans un onglet à projeter à côté (countdown autonome, démarre au chargement). Maëlle passe dans les rangs pour aider les bloqué·e·s ; CD reste disponible au tableau pour rebondir sur les questions communes.

Les problèmes fréquents : oubli des guillemets sur les couleurs hex dans brand.yml, nom de police Google mal orthographié, indentation YAML, et espacement parasite des chiffres dans le tableau gt (bug gt → Typst côté Windows/macOS, workaround gt::opt_table_font("Inter") visible dans la correction).

Étape 4 (Star Jedi) : pour les participants bloqués sur la syntaxe source: file + files:, montrer rapidement le bloc dans correction/_brand.yml au tableau. Ne pas paniquer si certains zappent l’étape — le rendu reste correct sans (titres en police Google par défaut). C’est l’étape la plus « visuelle » de l’exo : tous les titres de section passent en lettres décoratives Star Jedi rouge, effet immédiat.

Indication pour les participants qui finissent vite : leur dire « ouvrez correction/rapport-starwars.qmd et regardez les 3 derniers blocs tab_style() du tableau gt — les couleurs viennent de votre _brand.yml via brand_color_pluck() ». Ancre le message de la pépite “Une charte, partout” sur du code concret.

Saviez-vous que…

Saviez-vous que…

• Une charte, deux niveaux — _brand.yml habille automatiquement la mise en page (titres, liens, fond, polices). Vos tableaux gt et graphes ggplot sont du R : ils ne suivent que si vous les branchez avec le paquet brand.yml — un petit geste en plus, détaillé au Bonus B4 du Bloc 2
• Blocs raw Typst — Besoin de Typst natif ? Utilisez ```{=typst} pour injecter du code Typst directement dans votre .qmd
• Vos tableaux passent en Typst — la structure des tableaux gt (R) et Great Tables (Python) est traduite automatiquement en Typst par Quarto (les couleurs de la charte, elles, viennent du point ci-dessus)
• PDF accessible en une ligne — Ajoutez pdf-standard: ua-1 dans le YAML pour un PDF conforme au standard d’accessibilité PDF/UA-1

Plus de détails sur la page Ressources

Slide rapide, 2-3 minutes max. L’objectif est juste de planter des graines. Les gens curieux iront voir la page Ressources. Cette slide est le premier fusible à couper si on manque de temps.

☕ Pause

On se retrouve dans 10 minutes pour le Bloc 2 — passer du document au livre.

Gardez votre dossier de l’Exercice 1 sous la main : on réutilise votre _brand.yml juste après la pause.

Annoncer clairement la durée (~10 min) et l’heure de reprise. Inviter à se dégourdir les jambes. Rappeler que le Bloc 2 repart de leur _brand.yml du Bloc 1 (ou du _brand-starter.yml de secours pour les arrivants / ceux qui n’ont pas fini) — l’arc .qmd → livre continue, on ne repart pas de zéro.