• The reproducibility crisis, and the mundane reason most results fail: the code does not run
• The habits that fix it: project structure, raw data left alone, relative paths, seeds, recorded versions
• Quarto and its three parts: YAML header, Markdown, and code chunks
• quarto render builds a document; quarto preview keeps a live one open
• Every render is a restart-and-run-all test of your analysis
• You wrote and rendered your first document. Today we put Quarto to work

Last class you rendered one HTML page. Today that same skill fans out:

• Markdown beyond the basics: tables, footnotes, maths
• PDFs and citations that format themselves from a .bib file
• freeze: rendering documents without re-running the world
• Slides (like these) and websites, published free from GitHub
• Parameterised reports: one file that writes a report for every country in your dataset
• Two exercises along the way, so bring your laptop battery

• Tables: pipes and dashes, with colons setting the alignment

| Left | Centre | Right |
|:-----|:------:|------:|
| a    | b      | c     |

• Maths is LaTeX between dollar signs: $\mu = \frac{1}{n}\sum x_i$ inline, $$ ... $$ for display equations
• The LaTeX Wiki lists the symbols; the Markdown Guide covers the rest
• That is most of the language. Markdown is small on purpose

• Quarto renders existing .ipynb notebooks directly. No rewriting needed
• Add a YAML header in the first cell (as raw text) and run:

Terminal

quarto render notebook.ipynb --to html

• By default Quarto uses the outputs already stored in the notebook. Add --execute to re-run the code first
• If Quarto cannot find your Python, quarto check jupyter diagnoses it, and the QUARTO_PYTHON variable fixes it
• Writing .qmd from the start is still nicer for long documents, but old notebooks convert as they are

• Most journals, agencies, and employers still want PDF
• PDF rendering goes through LaTeX, and you installed TinyTeX last class (quarto install tinytex)
• After that, PDF is one flag:

Terminal

quarto render report.qmd --to pdf

• The same works on a notebook, and --execute re-runs it first:

Terminal

quarto render notebook.ipynb --to pdf --execute

• Fonts, margins, and page geometry are all YAML options: see the PDF basics guide

• Formatting references by hand is slow, and updating them by hand is how errors creep in. BibTeX automates both
• A .bib file is plain text: one entry per source, each with a citation key (here, nash1950equilibrium)
• Point your YAML at the file:

bibliography: references.bib

• Then cite by key in your prose:
  • @nash1950equilibrium → Nash (1950)
  • [@nash1950equilibrium] → (Nash 1950)
  • [@nash1950equilibrium, p. 48] → (Nash 1950, p. 48)
• Quarto formats the citations and appends the reference list. Change the style with one line: csl: apa.csl (thousands of styles here)

• You almost never type an entry by hand
• On Google Scholar, click Cite, then BibTeX, and copy the result into your .bib file
• For anything bigger than a homework, use a reference manager: Zotero is free, open source, and exports .bib files that stay in sync with your library
• Check the entries you import: Scholar sometimes gets capitalisation and journal names wrong, and the error lands in your reference list

A citation points outside your document. A cross-reference points inside it. Label the chunk, then use the label:

```{python}
#| label: fig-rain
#| fig-cap: "Monthly rainfall in Atlanta"
plt.plot(month, rain)
```

Rainfall peaks in March (@fig-rain).

That last line renders as Rainfall peaks in March (Figure 1)

Markdown tables take the label underneath, after a colon:

| City     | Population |
|:---------|-----------:|
| Atlanta  |    498,715 |
| Savannah |    147,780 |

: Two cities {#tbl-cities}

• Quarto’s default PDF looks fine. Journals, universities, and employers often want a specific look
• That is what LaTeX templates are for, and you do not have to write one: you point your YAML at one

format:
  pdf:
    template: your-template.latex

• I keep my own templates (articles, syllabi, letters, CVs) at https://github.com/danilofreire/quarto-templates
• You can save some time by using them, or finding others you like 😅

• You finish a report in October. In November you fix a typo and render it again
• Between the two dates, pandas shipped a new version and one default changed
• Your edit was one character. Three numbers in the results table are now different
• You find out when a colleague asks why their printed copy disagrees with the website

Put this in _quarto.yml for a project:

project:
  type: website

execute:
  freeze: auto

Or in the YAML header of a single document:

---
title: "Rainfall report"
format: html
execute:
  freeze: auto
---

• Quarto runs the code once and stores the results in a folder called _freeze/
• After that, a document re-runs only when its own source changes
• freeze: auto: change the code, get new results. Change nothing, get the same results
• freeze: true: never re-run. For archival work, a submitted paper or a signed-off report
• freeze: false: the default, always re-run

What it does

• Controls when your code runs again
• Keeps October’s results until you touch the source
• Stops accidental re-computation
• Makes a render fast and predictable

What it does not do

• Control what your code runs with
• Survive deleting _freeze/
• Protect a machine with other package versions
• Pin pandas to the version you tested

• Quarto renders slides with reveal.js, an HTML presentation framework
• These very slides are Quarto + reveal.js!
• Why bother, when PowerPoint exists?
  • Plain text: diffs, version control, merge conflicts that make sense
  • Code runs inside the slides: charts update when the data changes
  • One source, many formats: the same .qmd can also become a PDF handout
  • Free hosting: push to GitHub, share a link
• Fair warning: the first deck takes longer than dragging boxes. The payoff is that your 50th deck is no harder than your 2nd

Two options, both free:

You met GitHub Pages in module 02. Githack is the fastest path: push your HTML, paste the file URL at raw.githack.com, share the link it returns

• Quarto websites are static: pre-rendered HTML, CSS, and images, no server-side code
• Fast to load, free to host, and trivial to version-control
• Common uses: course sites, project documentation, portfolios, research blogs
• Free hosting on GitHub Pages, Netlify, or Vercel
• Limitation: no databases, no login pages, no server-side logic. For those you need a web framework (Flask, Django, etc.)
• More at quarto.org/docs/websites

• Example: https://www.mm218.dev/

Every Quarto website is a folder with the same skeleton:

• Each .qmd becomes one page, with the navigation, footer, and theme inherited from _quarto.yml
• A page’s own YAML usually holds just its title

The generated _quarto.yml for a new site:

project:
  type: website

website:
  title: "today"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

The theme list has two dozen options, light and dark

• The course site is a Quarto website like the one you just created, plus a longer _quarto.yml
• The abridged config is on the right: navigation bar, GitHub links, a footer, and paired light and dark themes
• The full file is on GitHub, and its index.qmd is here
• Steal from it freely! That is why it is public

Quarto has a built-in publish command for GitHub Pages:

Terminal

quarto publish gh-pages

• It renders the site, creates or updates a gh-pages branch, pushes it, and GitHub serves the result at https://username.github.io/repo-name/
• The manual alternative: quarto render, commit the output folder, push, and point Pages at it in the repository settings
• After the first publish, updating the site is: edit the .qmd, run the command again

• You need the same report for ten countries. Or every month. Or for each of thirty students
• The tempting move is to copy the file ten times and edit each copy. Do not. One mistake now means ten files to fix
• Write one report with a parameter instead: a value you set from outside the document
• In Python, a parameter is an ordinary variable in a cell tagged parameters

#| tags: [parameters]
country = "Brazil"

• That value is the default. Render the file normally and you get Brazil

• To override it, pass -P in the terminal:

Terminal

quarto render report.qmd -P country:Uruguay

• The tag is how Quarto finds the cell to replace. Forget it and -P does nothing
• Put the tagged cell first, above any code that uses the parameter
• One extra package makes this work, installed once:

Terminal

pip install papermill

Terminal

quarto render report.qmd -P country:"United States"

• The data is real: World Bank indicators for ten countries, 2000 to 2023, in data/country_profiles.csv
• The parameter does its work in three places: it filters the data, titles the report, and appears in the sentence
• `{python} country` is inline code. It drops the value of a Python expression straight into your prose
• So the words change with the data. No heading spells out “Brazil” by hand
• Only the default names a country. Change it, or pass -P, and the whole document follows
• The full file is in the lecture folder, a little longer than this extract because it also builds a table

Rendered with the default, country = "Brazil":

One country at a time, each with its own file name:

Terminal

quarto render report.qmd -P country:Uruguay \
  --output profile-Uruguay.html

Or let the shell do all of them, with the loop you met in module 02:

Terminal

for c in Brazil Mexico Uruguay; do
  quarto render report.qmd \
    -P country:$c \
    --output profile-$c.html
done

Three commands you did not have to type, and three files:

profile-Brazil.html
profile-Mexico.html
profile-Uruguay.html

Three failures you will meet this term, as they appear on screen:

Terminal

  Cell 1/1: ''...ERROR
ModuleNotFoundError: No module named 'geopandas'

Terminal

ERROR: YAMLException: bad indentation of
a mapping entry (2:14)
 2 | title: Quarto: a first look
------------------^

Terminal

compilation failed- error
Undefined control sequence.
l.172 ...bad command: \(\notarealcommand

• Python errors read from the bottom. The last line names the problem. The traceback above it only shows how the code got there
• Quarto tells you which cell broke, so you know where to look first
• A missing module usually means the package is fine, and Quarto is running a different Python
• YAML errors read from the top. Trust the caret: line 2, column 14 is the unquoted colon
• The stack trace printed underneath is noise. Ignore it
• In LaTeX errors, l.172 is a line in the generated .tex, not in your .qmd
• The text beside it is yours, though, so search your file for that
• And render often, so the only new thing is also the broken thing

Which Python is Quarto actually running? Ask it:

Terminal

quarto check jupyter

[✓] Checking Python 3 installation....OK
      Version: 3.13.13 (Conda)
      Path: /Users/danilo/miniconda3/bin/python3
      Kernels: ds350, python3

Compare that path with which python3. If they differ, you have found your error. Three fixes:

Terminal

# 1. activate first, render in the same terminal
source .venv/bin/activate
quarto render report.qmd

# 2. point Quarto at one interpreter
QUARTO_PYTHON=~/.venv/bin/python \
  quarto render report.qmd

# 3. name a kernel in the document itself
jupyter: ds350

Take stock for a moment. As of today, you can build:

• An article with formatted citations and numbered figures, in HTML and PDF, from one plain-text file
• A _freeze/ folder that pins your results until you decide to change them
• Slides and a public website, online with quarto publish gh-pages
• One parameterised report that a shell loop turns into ten reports

And you know why each one earns its place:

• freeze: auto separates “I changed the code” from “the world changed”
• Labels and @ references mean nothing is numbered by hand
• A website is just a folder with a _quarto.yml in it
• Everything today was plain text, so everything today lives in Git

• We change gears: local language models
• How large language models actually work, in enough depth to predict their failures
• A trained model turns out to be a file you can download, so we take one apart and read every setting inside it
• Then you build a chatbot with a personality of your own choosing
• Install Ollama before class and run ollama pull llama3.2:1b. The download is 1.3 GB, and the classroom wifi cannot do that twenty-five times at once
• Bring the scepticism you built this week: it transfers

The complete practice.qmd:

---
title: "My Quarto Document"
subtitle: "A simple example"
author: "Danilo Freire"
date: "2026-09-30"
format: html
bibliography: references.bib
---

# Introduction

This is a simple Quarto document.
This is @fig-sine.

```{python}
#| echo: true
#| eval: true
#| fig-cap: "Sine function"
#| label: fig-sine

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.plot(x, y)
plt.xlabel("x")
plt.ylabel("sin(x)")
plt.title("Figure 01")
plt.show()
```

Render with:

Terminal

quarto render practice.qmd
quarto render practice.qmd --to pdf

The rendered output:

Your folder should look like this before you render anything:

country-report/
├── report.qmd
└── data/
    └── country_profiles.csv

Steps 3 to 6, in order:

Terminal

quarto render report.qmd

quarto render report.qmd \
  -P country:Japan \
  --output profile-Japan.html

quarto render report.qmd \
  -P country:"South Africa" \
  --output profile-South-Africa.html

Three things worth noticing:

• The first render writes report.html, and it says Brazil, because that is the default in the tagged cell
• Without --output, every render writes over report.html. The Japan version would have replaced the Brazil one
• South Africa needs quotes. Without them the shell splits the name in two, the filter matches nothing, and the render stops with a ValueError

Back to main text