Introduction
Contexte et objectifs
Les doctorants du Conservatoire national des arts et métiers (cnam) doivent déposer leur thèse sous forme d’un PDF conforme à la maquette institutionnelle tout en souhaitant disposer d’une version HTML navigable pour le partage et l’accessibilité. Ce double objectif — PDF/A archivable et HTML lisible — est exactement ce que propose le système de publication Quarto (Allaire et al. 2022), à condition de disposer d’un template configuré pour les contraintes spécifiques du Cnam.
Le présent document est à la fois le guide d’utilisation du template quarto-cnam-thesis et sa démonstration vivante : chaque fonctionnalité décrite ici est simultanément expliquée, montrée en syntaxe brute, et rendue sous vos yeux dans ce même document.
Structure de ce guide
Ce guide est organisé en cinq chapitres thématiques :
- Structure et mise en forme — hiérarchie des titres, numérotation, cross-références, mise en forme inline, listes.
- Figures et mise en page — images statiques, figures générées par Python, mise en page multi-colonnes, figures PDF-only.
- Équations et tableaux — syntaxe mathématique, tableaux Markdown simples, tableaux avancés avec l’extension
quartable. - Callouts et blocs de code — les cinq types d’encadrés, code affiché sans exécution, code exécuté avec Python.
- Références, glossaire et annotations — citations bibliographiques, système d’acronymes et de termes, commentaires collaboratifs.
Le principe directeur est constant : pour chaque fonctionnalité, un bloc de code affiche la syntaxe Markdown exacte (non exécutée), suivi immédiatement du rendu réel.
Prérequis
Les fichiers sources de la thèse sont des fichiers texte ordinaires avec l’extension .qmd (Quarto Markdown). Ils s’ouvrent et s’éditent avec n’importe quel éditeur de texte — VS Code, RStudio, Neovim, Notepad++ ou même le bloc-notes du système.
Quarto et LaTeX
Ce template requiert Quarto 1.4 ou supérieur. Le moteur de compilation est pdflatex — XeLaTeX et LuaLaTeX ne sont pas supportés en raison des contraintes du package pdfx utilisé pour la conformité PDF/A-1b.
https://quarto.org/docs/get-started/ — installeur .pkg, .msi ou .deb selon la plateforme ; guide pas à pas pour VS Code, RStudio et autres éditeurs inclus.
Étape 2 — Installer LaTeX. Si vous n’avez pas encore LaTeX, utilisez TinyTeX, la distribution minimale intégrée à Quarto. Elle s’installe en quelques secondes et télécharge automatiquement les packages manquants au premier rendu :
Au premier rendu, TinyTeX télécharge les packages requis par le template (pdfx, minitoc, tcolorbox, glossaries…). Cela peut prendre quelques minutes. Les rendus suivants fonctionnent entièrement hors ligne.
Vous avez déjà LaTeX ? Toute distribution TeX Live 2023+ ou MiKTeX à jour fonctionne sans configuration supplémentaire. Si votre distribution est ancienne, mettez-la à jour ou lancez quarto install tinytex pour passer à TinyTeX.
| Système | Quarto | LaTeX |
|---|---|---|
| macOS | .pkg ou brew install quarto |
quarto install tinytex (recommandé) ou TeX Live / MacTeX |
| Windows | .msi (64 bits) |
quarto install tinytex (recommandé) ou MiKTeX / TeX Live |
| Linux (Debian/Ubuntu) | sudo dpkg -i quarto-*.deb |
quarto install tinytex (recommandé) ou sudo apt install texlive-full |
Code exécutable (Python, R…)
Un langage de script n’est nécessaire que si la thèse contient des cellules de code exécutable — figures calculées ou tableaux générés directement dans le document. Une thèse rédigée en texte pur avec des images statiques n’a besoin d’aucun langage de script : le script post-render (postrender.ts) tourne sur le runtime Deno intégré à Quarto.
Quarto supporte plusieurs moteurs de calcul :
- Python (via Jupyter) — utilisé dans les exemples de ce guide. → Documentation Quarto : Python
- R (via knitr) — bien adapté aux statistiques, à l’économétrie, à l’écologie et aux disciplines où R est le langage dominant. → Documentation Quarto : R
La suite de cette section détaille la configuration de Python, qui alimente les exemples de ce document. Pour R, se référer à la documentation Quarto ci-dessus.
Les packages requis par les exemples de ce document sont listés dans requirements.txt à la racine du projet : numpy, matplotlib, pandas, tabulate.
Environnement virtuel — pourquoi c’est important. Un environnement virtuel isole les packages de ce projet du reste de l’installation Python du système, évite les conflits de versions et facilite la reproductibilité. Il est fortement déconseillé d’installer les packages directement dans Python système.
uv — recommandé
uv installe Python, crée l’environnement virtuel et gère les packages en une seule commande, sans Python préalable sur le système. Quarto détecte automatiquement le dossier .venv/ créé — aucune activation manuelle n’est nécessaire avant quarto render.
# Étape 1 — installer uv (une seule fois, sur le système)
# macOS / Linux :
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell) :
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Étape 2 — dans le répertoire de la thèse :
uv python install 3.12 # télécharge et installe Python 3.12
uv venv # crée .venv/ dans le répertoire courant
uv pip install -r requirements.txt # installe tous les packages + Jupytervenv + pip — alternative
Si Python 3.10+ est déjà installé sur le système :
Les utilisateurs conda peuvent créer un environnement dédié : conda create -n mathese python=3.12 && conda activate mathese && pip install jupyter -r requirements.txt. Les utilisateurs pyenv installent la version cible avec pyenv, puis utilisent venv comme ci-dessus.
Installer le template
Cette commande copie tous les fichiers sources dans le répertoire courant, y compris les fichiers .qmd de cette documentation, qui servent de point de départ. Les fichiers de contenu à modifier se trouvent dans content_fr/ (profil français) et content_en/ (profil anglais), ainsi que les fichiers de configuration yaml (voir Annexe A — Configuration YAML).
Adapter le template à votre thèse
Deux fichiers sont à modifier avant le premier rendu.
_quarto.yml — les métadonnées de la thèse : titre, auteur, jury, date de soutenance, discipline… Ce fichier est commun aux deux sorties PDF et HTML. Une référence complète est donnée en Annexe A — Configuration YAML.
_quarto-fr.yml (ou _quarto-en.yml) — la liste des chapitres qui constituent le livre. C’est le premier endroit à modifier : remplacer les chapitres d’exemple par vos propres fichiers .qmd :
book:
chapters:
- index.qmd # ne pas supprimer
- content_fr/liminaire/remerciements.qmd
- content_fr/liminaire/resume.qmd
- content_fr/liminaire/abstract.qmd
- content_fr/liminaire/tables.qmd # ne pas supprimer
- content_fr/chapitres/00-introduction.qmd
- content_fr/chapitres/01-mon-chapitre.qmd # ← vos chapitres ici
- content_fr/chapitres/02-mon-chapitre.qmd
- content_fr/postliminaire/conclusion.qmd
- content_fr/postliminaire/bibliographie.qmd
appendices:
- content_fr/postliminaire/annexes.qmd
- content_fr/postliminaire/annexes-pdfa.qmdPour créer un chapitre : ajouter un fichier .qmd dans content_fr/chapitres/ et l’insérer dans cette liste.
Générer le document
En Quarto, on appelle ça le rendu : cela lance la génération du fichier .tex, la compilation, et la création des fichiers html, puisque ce template fournit une double sortie PDF et HTML. Pour cela, lancer l’une des commandes qui suivent, en fonction de votre langue de rédaction de la thèse (Français ou Anglais suivant les règles des écoles doctorales et la composition de votre jury) :
Prévisualisation en temps réel
Pendant la rédaction, il n’est pas nécessaire de relancer quarto render à chaque modification. La commande quarto preview surveille les fichiers sources et reconstruit automatiquement le document dès qu’un fichier .qmd est sauvegardé :
Quarto ouvre alors la version HTML dans le navigateur et la rafraîchit en quelques secondes à chaque sauvegarde. Seul le chapitre modifié est recompilé (reconstruction incrémentale), ce qui rend le cycle édition–aperçu très rapide — même avec des blocs de code Python, grâce au cache freeze: auto.
Utiliser quarto preview au quotidien pour vérifier la mise en forme, les cross-références et les figures. Relancer quarto render ponctuellement (avant une réunion de suivi, avant un dépôt) pour obtenir le PDF final. Les deux sorties — HTML et PDF — sont cohérentes : ce qui s’affiche correctement en HTML se compile correctement en PDF.
Pour les utilisateurs de VS Code ou RStudio, l’extension Quarto intègre un bouton Render et un panneau de prévisualisation directement dans l’éditeur — sans passer par le terminal.