Introduction
Context and objectives
Doctoral students at the Conservatoire national des arts et métiers (cnam) must submit their thesis as a PDF compliant with the institutional template, while also wanting a navigable HTML version for sharing and accessibility. This dual objective — archivable PDF/A and readable HTML — is precisely what the Quarto publishing system (Allaire et al. 2022) offers, provided a template configured for the specific constraints of the Cnam is available.
The present document is both the user guide for the quarto-cnam-thesis template and its live demonstration: every feature described here is simultaneously explained, shown in raw syntax, and rendered before your eyes in this very document.
Structure of this guide
This guide is organised into five thematic chapters:
- Structure and formatting — heading hierarchy, numbering, section cross-references, inline formatting, lists.
- Figures and layout — static images, Python-generated figures, multi-column layout, PDF-only figures.
- Equations and tables — mathematical syntax, simple Markdown tables, advanced tables with the
quartableextension. - Callouts and code blocks — the five callout types, displayed code without execution, executed code with Python.
- References, glossary, and annotations — bibliographic citations, acronym and term system, collaborative comments.
The guiding principle is constant: for each feature, a code block displays the exact Markdown syntax (not executed), immediately followed by the actual rendered output.
Prerequisites
The thesis source files are ordinary text files with the .qmd extension (Quarto Markdown). They can be opened and edited with any text editor — VS Code, RStudio, Neovim, Notepad++ or even the system notepad.
Quarto and LaTeX
This template requires Quarto 1.4 or later. The compilation engine is pdflatex — XeLaTeX and LuaLaTeX are not supported due to constraints of the pdfx package used for PDF/A-1b compliance.
https://quarto.org/docs/get-started/ — .pkg, .msi or .deb installer depending on the platform; step-by-step editor guide for VS Code, RStudio and more.
Step 2 — Install LaTeX. If you do not already have LaTeX, use TinyTeX, Quarto’s built-in minimal distribution. It installs in seconds and automatically downloads any missing package on first render:
On the first render, TinyTeX downloads the packages required by the template (pdfx, minitoc, tcolorbox, glossaries…). This may take a few minutes. All subsequent renders run entirely offline.
Already have LaTeX? Any up-to-date TeX Live 2023+ or MiKTeX installation works with no additional configuration. If your distribution is older, either update it or run quarto install tinytex to switch to TinyTeX.
| System | Quarto | LaTeX |
|---|---|---|
| macOS | .pkg or brew install quarto |
quarto install tinytex (recommended) or TeX Live / MacTeX |
| Windows | .msi (64-bit) |
quarto install tinytex (recommended) or MiKTeX / TeX Live |
| Linux (Debian/Ubuntu) | sudo dpkg -i quarto-*.deb |
quarto install tinytex (recommended) or sudo apt install texlive-full |
Executable code (Python, R…)
A scripting language is only needed if the thesis contains executable code cells — computed figures or tables generated directly in the document. A thesis written in pure text with static images requires no scripting language at all: the post-render script (postrender.ts) runs on Quarto’s bundled Deno runtime.
Quarto supports several computation engines:
- Python (via Jupyter) — used in the examples of this guide. → Quarto documentation: Python computations
- R (via knitr) — well suited for statistics, econometrics, ecology and other disciplines where R is the dominant language. → Quarto documentation: R computations
The rest of this section covers Python setup, which powers the examples in this document. For R, refer to the Quarto documentation linked above.
The packages required by the examples in this document are listed in requirements.txt at the project root: numpy, matplotlib, pandas, tabulate.
Virtual environment — why it matters. A virtual environment isolates this project’s packages from the rest of the system Python installation, avoids version conflicts, and facilitates reproducibility. Installing packages directly into the system Python is strongly discouraged.
uv — recommended
uv installs Python, creates the virtual environment, and manages packages in a single command, without requiring Python on the system beforehand. Quarto automatically detects the .venv/ folder created — no manual activation is needed before quarto render.
# Step 1 — install uv (once, on the system)
# 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"
# Step 2 — in the thesis directory:
uv python install 3.12 # downloads and installs Python 3.12
uv venv # creates .venv/ in the current directory
uv pip install -r requirements.txt # installs all packages + Jupytervenv + pip — alternative
If Python 3.10+ is already installed on the system:
Conda users can create a dedicated environment: conda create -n mythesis python=3.12 && conda activate mythesis && pip install jupyter -r requirements.txt. pyenv users install the target version with pyenv, then use venv as above.
Installing the template
This command copies all source files into the current directory, including the .qmd files of this documentation, which serve as a starting point. The content files to modify are located in content_fr/ (French profile) and content_en/ (English profile), together with the yaml configuration files (see Annexe A — YAML configuration).
Adapting the template to your thesis
Two files need to be edited before the first render.
_quarto.yml — thesis metadata: title, author, jury, defence date, discipline… This file is shared by both the PDF and HTML outputs. A complete reference is given in Annexe A — YAML configuration.
_quarto-en.yml (or _quarto-fr.yml) — the list of chapters that make up the book. This is the first place to edit: replace the example chapters with your own .qmd files:
book:
chapters:
- index.qmd # do not remove
- content_en/frontmatter/acknowledgements.qmd
- content_en/frontmatter/resume.qmd
- content_en/frontmatter/abstract.qmd
- content_en/frontmatter/tables.qmd # do not remove
- content_en/chapters/00-introduction.qmd
- content_en/chapters/01-my-chapter.qmd # <- your chapters here
- content_en/chapters/02-my-chapter.qmd
- content_en/backmatter/conclusion.qmd
- content_en/backmatter/bibliography.qmd
appendices:
- content_en/backmatter/appendices.qmd
- content_en/backmatter/appendices-pdfa.qmdTo create a chapter: add a .qmd file in content_en/chapters/ and insert it into this list.
Rendering the document
In Quarto, this is called rendering: it triggers the generation of the .tex file, the compilation, and the creation of html files, since this template provides dual PDF and HTML output. To do this, run one of the following commands depending on the language in which you are writing the thesis (French or English, according to the rules of the doctoral schools and the composition of your jury):
Live preview
During writing, there is no need to rerun quarto render after every change. The quarto preview command watches the source files and automatically rebuilds the document whenever a .qmd file is saved:
Quarto then opens the HTML version in the browser and refreshes it within seconds on each save. Only the modified chapter is recompiled (incremental rebuild), which makes the edit–preview cycle very fast — even with Python code blocks, thanks to the freeze: auto cache.
Use quarto preview daily to check formatting, cross-references, and figures. Run quarto render periodically (before a supervision meeting, before submission) to obtain the final PDF. Both outputs — HTML and PDF — are consistent: what renders correctly in HTML compiles correctly in PDF.
For VS Code or RStudio users, the Quarto extension integrates a Render button and a preview panel directly in the editor — without using the terminal.