Skip to content

About

workshop introducing quarto

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

561 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Quarto Workshop

The cover of Prompt, Check, Publish, by Ravi Kalia

📖 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.

For attendees

Quick links: 📖 Book (free e-book · HTML) · Cheatsheet · Troubleshooting & Gotchas

Pre-work (before the workshop)

  1. 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 run xcode-select --install first, so the Command Line Tools pop-up does not interrupt the agent later; Ubuntu and Debian users run sudo 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.

  2. 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
  3. 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 check is fine: uv handles Python per project. With another agent, run codex --version or agy --version instead. Skip the git config lines if they are already set.

  4. 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 / agy instead of claude. 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.html and hello.pdf both output 42, tell the organizer it succeeded!

  5. 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.

No install rights? Use GitHub Codespaces

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.

How the slides work

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.

Agenda

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.

For instructors and contributors

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.

Build and preview

quarto render
quarto preview
# Or preview a single deck:
quarto preview ai-workflows.qmd

The 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 render

Preview 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).

The e-book landing page

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-media remakes ebook/media/ and ebook/_head.html with scripts/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 with STEPS="head inside": head after changing the book's title, description or date in book/_quarto.yml, inside after republishing the book, cover after changing its cover. It needs Google Chrome and ffmpeg.
  • make ebook-check serves docs/ 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. After make book-publish of a new edition, and once it is committed, the author attaches the published EPUB to a new release with make book-release TAG=book-YYYY-MM-DD (it runs gh release create). A new release per edition keeps each edition's download count; replacing the file in an old release resets it. latest is the newest release in the repository, so any other release must carry the EPUB too.
  • On iPhones, iPads and Android phones, ebook.js points the buttons at the EPUB's copy on GitHub Pages (docs/book/), which is served as application/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.

Editing and verification

  • 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.

Checks in CI

.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.

About

workshop introducing quarto

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages