📖 Free e-book: Prompt, Check, Publish, the workshop as a book. Download the EPUB, or read it online with the live 3-D scenes.
AI-assisted reproducible publishing with Quarto. In a hands-on 6-hour day (including two 15-minute breaks and a 30-minute meal), participants direct a coding agent (Claude Code, Codex or Antigravity) that writes the computations, check its work, and turn plain-text Markdown into docx, pdf, pptx, revealjs slides, a website, a blog and a dashboard (and, optionally, epub and academic white papers). Each part ends with a task that has no supplied prompt: change an input, rebuild, and explain which outputs update. The slides are the course resource: everything needed to follow along alone is on them.
- Quarto workshop: Part 1 builds a London tourist guide from Markdown to a published dashboard. Part 2 clusters Colombian municipalities by drinking-water risk and context, then publishes one analysis many ways.
- The book, Prompt, Check, Publish, is the workshop as a free book: its page has the EPUB e-book, and the website edition runs the live 3-D scenes.
- AI workflows: an optional 90-minute graduate lab built on a real randomized email-marketing experiment, with a report in PDF (Typst), DOCX and IPYNB, eight slides, and verified revisions.
Quick links: 📖 Book (free e-book · HTML) · Cheatsheet · Troubleshooting & Gotchas
-
Install tools: Install Quarto (≥ 1.10 for the white-paper examples; 1.10.20 validated), uv (it brings Python automatically), Git, an editor, the GitHub CLI (run
gh auth login), and one coding agent (Claude Code, Codex or Google's Antigravity CLI,agy). Windows users: follow the Windows setup page first: it installs Ubuntu (WSL) step by step, and everything afterwards happens inside Ubuntu. Mac users runxcode-select --installfirst, so the Command Line Tools pop-up does not interrupt the agent later; Ubuntu and Debian users runsudo apt update && sudo apt install -y curl git. Install one coding agent first, then ask it (the deck has the prompt) to install the other tools. -
Clone the repository: Clone this repository beside your project workspace folders to get the data and checkpoints:
cd ~ && git clone https://github.com/project-delphi/quarto-workshop.git
-
Run the setup check (slide):
quarto check uv --version gh auth status claude --version git config --global user.name "Your Name" git config --global user.email "you@example.com"
Jupyter "not available" from
quarto checkis fine: uv handles Python per project. With another agent, runcodex --versionoragy --versioninstead. Skip thegit configlines if they are already set. -
Do the 🧪 test run (slide): In a terminal, create a test directory and launch your coding agent:
mkdir -p ~/quarto-test && cd ~/quarto-test claude
Or
codex/agyinstead ofclaude. Paste this prompt into your agent:Run `uv init --bare` and `uv add ipykernel nbclient nbformat pyyaml`. Create hello.qmd (html and typst formats): a Python cell computing `6 * 7` and an inline-code sentence showing it. Render it with `uv run quarto render hello.qmd`; check hello.html and hello.pdf both say 42.Once
hello.htmlandhello.pdfboth output 42, tell the organizer it succeeded! -
Read the 📖 Read Before the Day slides (slide): how the agent works, what models cost, using AI in research, and Markdown in Y minutes (5 min).
PDFs use Quarto's bundled Typst engine, so no LaTeX install is needed. Each project creates its own
Python environment with uv during the workshop (one prompt, a few seconds), and all Quarto
and Python commands run through uv run. To follow the slides in another language such as Spanish, use the
Google Translate extension;
code blocks stay in English.
If you cannot install software (a locked-down work laptop, or Windows without WSL), run the
workshop in your browser instead. On this repository's GitHub page choose Code → Codespaces →
Create codespace on main. The dev container brings Quarto
1.10.20, uv, Git and the GitHub CLI, and puts this repository at ~/quarto-workshop, so it does the work of
pre-work steps 1 and 4: you install only your coding agent (step 3). In the codespace's terminal, run cd ~ before making a
project, install your coding agent with its Linux command, and preview with
quarto preview --port 4848 --host 0.0.0.0 --no-browser; Codespaces offers to open the page.
If gh auth login reports that GITHUB_TOKEN is in use, run unset GITHUB_TOKEN first: the
codespace's own token only reaches this repository. Personal accounts get 120 core hours (60 hours
on the default 2-core machine) and 15 GB of storage a month free
(billing,
checked 2026-11-18); stop the codespace when you finish.
Hands-on slides use three coloured boxes:
| Box | Meaning |
|---|---|
| 🤖 Ask your coding agent (violet) | The exact prompt to paste |
| 👀 Expect it to run (amber) | Commands the agent will probably run for you |
| ⌨️ You type (green) | The few things only you can do: start the agent, sign in, approve its commands, run quarto preview, open results |
Every exercise shows a ⏱️ time box and a ✅ "you're done when…" check. 🏠 slides are pre-work and ⭐ slides are optional and self-paced. Stuck for two minutes? Copy the exercise's 😰 Catch me up prompt into your agent, for example:
Catch me up: follow ../quarto-workshop/checkpoints/02-london-qmd/README.md
Each checkpoint README lists the steps, which also work by hand from inside your project
folder: back up the folder, all but its .venv/ (uv run rebuilds it), to a new
time-stamped ../<folder>-backup-NN-<time> (earlier backups are kept), copy the
checkpoint in, copy the water data/ if it is missing (Part 2 checkpoints hold sources
only), render, check a named output, and rejoin at the slide the
README names. A checkpoint is the state at the end of its block, so it can be ahead of the
step you are on: skip the block's remaining prompts and follow the slides until the next ⏱️
block, where everyone is hands-on together again. The finished projects, examples/london/
and examples/water/, have the same catch-up section in their READMEs.
From Part 2's Cluster block on, the analysis has two routes. The normal 📤 route copies each
block's finished scripts/analysis.py from its checkpoint and spends the time on the pages;
the ⭐ challenge route writes the analysis with the ⭐ prompts. Both write the same
outputs/, so everyone builds the same report, slides and blog (and, optionally, dashboard).
Prompts are examples, not transcripts: agents vary, so check the rendered result and read the diff.
| Time | Block | Slide |
|---|---|---|
| 0:00 | 👋 Welcome · 🎯 objective · 🏁 outcome | Slide |
| 0:10 | 🧭 What Is Quarto? | Slide |
| 0:15 | 🧰 Ready to Prompt · ✋ fix failed checks · boxes · 🗣️ prompting (🛠️ Setup and 📖 Read Before the Day are pre-work) | Slide |
| 0:30 | 🇬🇧 Part 1 · London: Markdown → HTML, rules, environment | Slide |
| 1:05 | ☕ Break · 🛟 catch up (15 min) | Slide |
| 1:20 | 🧪 Part 1 · .md → .qmd: YAML, code, docx + PDF |
Slide |
| 1:40 | 🗂️ Part 1 · Three audiences, 🤖 sub-agents in parallel | Slide |
| 1:55 | 🌍 Part 1 · Publish to GitHub Pages | Slide |
| 2:15 | 🔁 Part 1 · Change an Input, Rebuild, Explain | Slide |
| 2:25 | 🍽️ Meal Break · 🛟 catch up (30 min) | Slide |
| 2:55 | 💧 Part 2 · Colombian water quality: why, data, explore, prepare, cluster (85 min) | Slide |
| 4:20 | ☕ Break · 🛟 catch up (15 min) | Slide |
| 4:35 | 💧 Part 2 · Interpret, correlation ≠ causation, publish many (75 min) | Slide |
| 5:50 | 🏁 Done · 🔗 show your sites | Slide |
| 6:00 | 👋 Home |
Times count from the start of the day: add your start time.
Guides: Instructor Runbook · Cheatsheet · Troubleshooting
| Path | Purpose |
|---|---|
index.qmd |
Workshop deck: Part 0 intro and setup; includes the two parts below |
slides/_london.qmd, slides/_water.qmd |
Part 1 and Part 2 slides, included from index.qmd |
ai-workflows.qmd |
Optional marketing-experiment lab on agent-assisted Quarto authoring |
windows-setup.qmd |
Step 1 of setup for Windows, as a long-form page linked from the deck (styled by assets/page.scss) |
INSTRUCTOR.md |
Facilitator guide: pacing, the 2-minute rule, room logistics, troubleshooting |
CHEATSHEET.md |
Quick reference: Quarto YAML formats, cell options, dashboards, uv commands |
TROUBLESHOOTING.md |
Common gotchas: first publish, buffer size, preview locks, Typst sizing |
examples/london/ |
Finished Part 1 project: cited London data, guide, dashboard, audience versions, ⭐ white paper, website |
examples/water/ |
Finished Part 2 project: municipal water dataset, build pipeline, analysis, outputs and ⭐ white paper |
starters/first-report/ |
The starter of the book's "A First Report, by Hand": five cited ALVA rows and a report with one deliberately wrong typed number, which readers copy to ~/first-report, render, check, change and undo by hand |
starters/eval-repo/ |
The book's fast-path starter: an existing-style Python repository (Acme Signals, a fictional start-up) that evaluates three releases of a model on the real UCI Bank Marketing data (CC BY 4.0), with tests and a notebook and no Quarto yet, which readers copy to ~/acme-eval |
examples/eval/ |
The finished evaluation project: scripts/evaluate.py writes every result to outputs/ once; the report and model card read them, with guards (acme_eval.claims) |
checkpoints/ |
The state at the end of each hands-on block, with catch-up steps in each README (no rendered output; water ones need examples/water/data/) |
assets/ |
Hub and publishing diagrams (SVG); pelicans/ holds the 🐦 slide's images, with sources and costs in its README; threejs-visits.png is the ✨ slide's dry run; deck-3d/ builds the three.js bundle for the 3-D slides (Part 1's London map, Part 2's cluster cloud and relief, and five optional meta-feature slides); deck-qr.svg and ebook-qr.svg are the title slide's QR code to the published deck and the 📖 Get the Book slide's to the e-book's page, written by uv run --with segno python scripts/deck_qr.py; ebook-cover.webp is that slide's cover, written by make ebook-media |
book/ |
The book edition (EPUB and HTML) of the workshop, built with make book; see book/README.md |
ebook/ |
The book's landing page, /quarto-workshop/ebook/, built by the root project from the book's source; see "The e-book landing page" below |
Makefile, scripts/keep-book.ts, scripts/deck_qr.py |
make deck, make book, make site and the other book targets; the deck's post-render step that restores docs/book/; the deck's QR codes |
scripts/ebook_media.py, scripts/ebook_check.py |
The landing page's media and <head> (make ebook-media), and its checks (make ebook-check) |
theme.scss |
Dark theme additions: agent boxes, clocks, cards, previews, progress bar |
section-progress.html |
Coloured section progress bar and navigation |
_quarto.yml |
Explicit render list, execution defaults, shared Reveal.js settings |
examples/marketing-context/, examples/ai-context/ |
Inputs for the AI workflows lab |
AGENTS.md / CLAUDE.md |
Repository instructions, slide conventions, data contracts, delegation roles |
environment.yml, environment-r.yml |
Python (and optional R) environment recipes |
docs/ |
Committed rendered output (the decks, and the book in docs/book/); GitHub Pages serves main:/docs |
examples/, checkpoints/, starters/ and slides/ stay outside project.render; the examples and
checkpoints are rendered separately when they change.
quarto render
quarto preview
# Or preview a single deck:
quarto preview ai-workflows.qmdThe deck executes Python. If you use this checkout's .conda/ environment (built from
environment.yml), select it explicitly:
QUARTO_PYTHON="$PWD/.conda/bin/python" \
JUPYTER_PATH="$PWD/.conda/share/jupyter" quarto renderPreview does not open a browser automatically: open the URL printed in the terminal.
A full render empties docs/, including the book edition in docs/book/. make deck renders
the decks and keeps docs/book/ exactly as it was; after a plain quarto render, the
post-render step (scripts/keep-book.ts) restores its committed or staged version. To rebuild
the book too, run make site (the decks, then the book; tools and steps in
book/README.md).
Quarto 1.10.20 (with bundled Typst 0.15) is the locally validated baseline; dashboards and
Typst need Quarto ≥ 1.4. The white-paper examples use #set par(spacing: …), which Quarto
1.6.40's Typst rejects, so they need a newer Quarto (checked 2026-11-01).
The bottom bar divides the deck into coloured sections that match the agenda. The active
segment has a white marker, and a label shows the current section and its slide count. Click a
segment to jump to its start. Level-one headings start segments; data-progress-label on a
slide heading starts a task segment (used for the eight marketing turns).
ebook/index.qmd is the book's landing page, served at
https://project-delphi.github.io/quarto-workshop/ebook/ and rendered with the decks by
quarto render or make deck. It is a minimal: true HTML page with its own ebook.css and
ebook.js (no Bootstrap), dark in every OS setting, in the cover's colours. It is built with
the book's own method: its cells read every number, title, chapter, quotation and credit from
the book's source and data through ebook/_source.py, and the render stops if wording it
quotes is no longer in the book.
make ebook-mediaremakesebook/media/andebook/_head.htmlwithscripts/ebook_media.py(fonts, cover, the 1200 × 627 share image, icons, clips, pictures of the book's pages, and the page's<head>). Name steps withSTEPS="head inside":headafter changing the book's title, description or date inbook/_quarto.yml,insideafter republishing the book,coverafter changing its cover. It needs Google Chrome and ffmpeg.make ebook-checkservesdocs/at/quarto-workshop/and checks the rendered page: screenshots at 375 × 812 and 1440 × 900, light and dark, and with reduced motion; the download button on a phone's first screen; the hint and EPUB link each kind of phone gets; first-load weight; every link on the page, on the deck's title and 📖 Get the Book slides and in the website edition's sidebar; the contents' numbers; the share card and the JSON-LD. Run Lighthouse (mobile) against the same local server too.- The Download the EPUB buttons link to
https://github.com/project-delphi/quarto-workshop/releases/latest/download/prompt-check-publish.epub, which GitHub counts. It answers 404 until a release carries the file. Aftermake book-publishof a new edition, and once it is committed, the author attaches the published EPUB to a new release withmake book-release TAG=book-YYYY-MM-DD(it runsgh release create). A new release per edition keeps each edition's download count; replacing the file in an old release resets it.latestis the newest release in the repository, so any other release must carry the EPUB too. - On iPhones, iPads and Android phones,
ebook.jspoints the buttons at the EPUB's copy on GitHub Pages (docs/book/), which is served asapplication/epub+zip; the release serves a generic file to save, which phones do not offer to open in a reader. So the release counts desktop downloads only. In-app browsers keep the release link, and each phone sees a hint for getting the file into a reader; the FAQ gives all three without JavaScript. - After publishing, check the share card with LinkedIn's Post Inspector, which also refreshes LinkedIn's cached copy.
- Follow the slide conventions in
AGENTS.md: one concept per slide, ≤ ~30 words of prose, emoji over words, notes for detail, the three agent boxes, ⏱️ and ✅ on every exercise, and a 😰 catch-up prompt naming a checkpoint README. - Exercise times are planning estimates that leave each block a few minutes for showing results and recovering from a failed command. Rehearse with a stopwatch and keep the agenda slides, section clocks, exercise labels and this README consistent.
- Use executable
{python}cells only for code that should run during rendering, and display-only fences for examples. Never run install, network, publish or agent commands while rendering. - Every number on a slide is computed from committed data or carries a citation.
- Render the whole project, inspect every changed slide at 1280 × 720, 1366 × 768 and
1440 × 1000, check links between both decks, and run
git diff --check.
.github/workflows/build.yml runs on every pull request and on pushes to main: from a clean
clone it builds both book editions (make book, make book-es, with EPUBCheck and the link,
scene and translation checks), renders the decks and landing pages, runs make ebook-check,
and checks the change for whitespace errors. It builds and checks only: it never publishes or
pushes. It installs the deck's Python packages with uv rather than conda, so its deck output can
differ in detail from a local make deck; the committed docs/ still comes from a local build.
To run it locally, install act and Docker, then
act workflow_dispatch -W .github/workflows/build.yml -P ubuntu-24.04=catthehacker/ubuntu:act-24.04
(add --container-architecture linux/arm64 on Apple silicon); the landing-page step, which needs
Google Chrome, is skipped there.
Re-render and include docs/ alongside source edits. Do not hand-edit generated HTML or switch
this repository to quarto publish gh-pages (participants use that command for their own
repositories). A failed clean render can remove existing output; fix the failure and complete a
successful full render before delivering changes. The .gitignore exception for
docs/site_libs/** prevents the generic dist/ rule from hiding Reveal.js assets.
