A Folder for the Workshop

Terminal, once: from the workshop clone, prepare a practice folder and copy the reported IRCA data used in the computation exercise.

mkdir -p ~/code/quarto-play
mkdir -p ~/code/quarto-play/context
cp examples/irca-colombia/irca_boyaca_cundinamarca_santander.csv \
  ~/code/quarto-play/context/
cd ~/code/quarto-play
# Start one coding agent:
claude
# Or: codex
# Or: agy

Ask your coding agent:

I am learning Quarto. Use this folder for the exercises. Check the tools available, initialize Git if needed, and work on a workshop branch. Tell me which folder you are using and what is missing.

Check: the session names quarto-play as its working folder.

Connect Your GitHub Account

Ask your coding agent in quarto-play:

Check whether GitHub CLI (gh) is available here. If it is missing, help me install it for this terminal. Guide me through signing in to my GitHub account in the browser, then verify the active account. Do not create a repository yet.

Commands to recognize:

gh auth login
gh auth status

Check: gh auth status names the GitHub account you intend to use.

GitHub CLI login and status, checked 2026-10-28.

A Document from One Request

Ask your coding agent:

Create hello.qmd, a short HTML page for a student new to Quarto. Set format: html in its YAML frontmatter. Include a title, a brief explanation, and two things I can publish. Show Markdown for a heading, bold phrase, and list beside its rendered result. Add a self-contained Mermaid diagram of a .qmd file becoming HTML. Render, fix errors, and tell me which file to open.

Command behind the render:

quarto render hello.qmd --to html

Check: compare hello.qmd with hello.html. The Markdown example matches its rendered result, and the diagram is visible.

What the Coding Agent Did

The coding agent can carry out this sequence from a plain-English request. The generated source remains yours to read, edit, and version.

The Next Message Is a Revision

Continue in the same coding agent conversation:

Change the title to “What Do Municipal IRCA Values Show?”. Add a question about reported water-quality risk in Boyacá and nearby departments. Add sections for code, interpretation, and sources. Render again.

Check: both titles change. This HTML practice page can later support the optional notebook project.

Exercise

Request one different revision in your own words. Point to the changed source and show its effect in the browser.

A Useful Request

In hello.qmd, explain Quarto to first-year data science students. Use a municipal water-quality notebook example in under 100 words. Preserve my title. Render the page and check that the example appears.

Understanding the Source

Quarto’s Job

Quarto combines prose, code, and results into a publication. The coding agent can write the source and run Quarto for you.

Exercise

Browse the Quarto gallery. Describe one feature you would ask your coding agent to add to your project.

The Quarto Rendering Pipeline

hello.qmd
   │  executable chunks, if present
   ▼
Jupyter (often Python) or Knitr (often R)
   │  code and results become Markdown
   ▼
intermediate .md
   │  document conversion
   ▼
Pandoc
   ├── HTML page or Reveal.js slides
   └── PDF (with a PDF engine)

When a render fails: locate the source/YAML, code-execution, or output conversion stage before asking the agent for a fix.

One Plain-Text Source, Many Outputs

flowchart LR
    A["Plain-text Markdown<br/>hello.qmd"] --> B["Quarto"]
    B --> C["HTML page"]
    B --> D["PDF document"]
    B --> E["Word document"]
    B --> F["Reveal.js slides"]

The .qmd file stays editable. Quarto renders the requested format; some formats need additional tools or document settings.

Markdown You Can Recognize

Ask your coding agent:

Add a “Reading list” to hello.qmd with a link to the official Colombian water-quality dataset and one bold phrase stating the unit of analysis. Verify the link, render, and explain the Markdown.

Source pattern:

## Reading list

Each row is a **municipality-year summary**, not an individual water sample.

[INS/SIVICAP water-quality dataset](https://www.datos.gov.co/Salud-y-Protecci-n-Social/Calidad-del-Agua-para-Consumo-Humano-en-Colombia/nxt2-39c3)

Check: a heading, bold text, and a working link appear on the page.

YAML Selects the Output

Ask your coding agent:

Add a table of contents to hello.qmd. Keep the existing title and sections. Render it and explain the YAML change.

Source pattern at the top of the file:

---
title: "What Do Municipal IRCA Values Show?"
format:
  html:
    toc: true
---

Check: the contents links lead to your section headings.

Prompt Engineering for Quarto

Name the part to change, the action, and the visible check.

Try: “Change the YAML format to html; add a caption to the plot chunk; render and check that the caption appears.”

Formatting a Comparison

Ask your coding agent:

Add two tabs to hello.qmd: “Question” and “Evidence”. Put a short municipal IRCA note in each. Use Quarto’s tabset syntax and render.

Source pattern:

::: {.panel-tabset}
## Question
How do reported IRCA values vary across municipalities?
## Evidence
The official table reports annual municipal IRCA values, with gaps in rural data.
:::

Check: clicking each tab reveals the corresponding text.

Displayed Code and Executed Code

Ask your coding agent:

Add one displayed Python example and one executable Python cell to hello.qmd. Have each say hello. Explain how their fences differ. Render the page with execution enabled.

```python
print("This code is displayed")
```

```{python}
print("This code runs")
```

Check: only the executable cell produces a separate output line.

The Coding Agent Handles the Runtime

If the executable example needs dependencies, ask your coding agent:

Inspect the available Python environments. Reuse a suitable local environment or prepare one for this project. Render hello.qmd with execution enabled. Fix failures and record the interpreter, dependencies, and working command in README.md.

Commands you should recognize:

quarto check jupyter
quarto render hello.qmd

Check: the output exists and the recorded build command works.

A Computation in These Slides

This cell counts 2024 municipality records in the three selected departments from the bundled official-data extract when the deck renders:

import csv
from collections import Counter

with open("examples/irca-colombia/irca_boyaca_cundinamarca_santander.csv", newline="") as source:
    group_counts = Counter(
        row["departamento"] for row in csv.DictReader(source)
        if row["a_o"] == "2024" and row["municipiocodigo"] != "#TODOS"
    )
total = sum(group_counts.values())
largest_share = 100 * max(group_counts.values()) / total
print(f"Municipality records in 2024: {total}")
print(f"Largest group share: {largest_share:.1f}%")

Municipality records in 2024: 318
Largest group share: 37.4%

Check: the total is 318. Boyacá has the most records (119).

Revise a Calculation

The max function selects the largest department group. What happens if we ask for the smallest group instead?

Exercise

Add this computation to hello.qmd, adjusting the CSV path to context/irca_boyaca_cundinamarca_santander.csv. Change max to min, render, and explain what changes.

Check: the total stays 318 while the reported department share changes.

Cell Options Control What Readers See

Ask your coding agent:

Hide the group-count calculation’s code in the page, but keep its output visible and recompute it on render. Explain the option used.

Source pattern inside the executable cell:

#| echo: false
import csv
from collections import Counter
with open("context/irca_boyaca_cundinamarca_santander.csv", newline="") as source:
    group_counts = Counter(
        row["departamento"] for row in csv.DictReader(source)
        if row["a_o"] == "2024" and row["municipiocodigo"] != "#TODOS"
    )
print(f"Municipality records: {sum(group_counts.values())}")

echo: false hides source. eval: false would stop the calculation.

Check: the result remains visible and agrees with the practice inputs.

Controlled Failure

Exercise

Copy this deliberately broken chunk into your practice hello.qmd. Ask the agent to render without fixing the chunk first:

```{python}
# Deliberate error: this name has not been defined.
print(workshop_total_typo)
```

Then ask: “Quote the first useful error in the Quarto CLI output. Point to the failing chunk, explain the cause, and propose the smallest fix. Do not change unrelated text.” Apply the fix, render again, and inspect the output.

Check the Diagnosis

Require the agent to quote the relevant error and show the smallest source change. A successful rerender tests the explanation.

Change HTML to Reveal.js

Ask the agent to copy the repaired hello.qmd to talk.qmd and change its YAML format from html to revealjs:

---
title: "My short talk"
format: revealjs
---

Use ## headings for individual slides. Ask the agent to split long sections and keep each result with its meaning. Then render:

quarto render talk.qmd

Check: open talk.html and advance through every slide.

Review the Slides Before Sharing

Ask your coding agent:

Render talk.qmd, inspect every slide at desktop and laptop presentation sizes, and report text overflow or missing results. Fix the source and rerender. Tell me which slides changed.

Check yourself: Can someone read every slide? Do links work? Is a computed result still explained? Is any private note or local path visible by mistake?

Publish the Reviewed Deck to Quarto Pub

In your practice folder, after checking the destination and output:

quarto publish quarto-pub talk.qmd

Follow Quarto’s interactive account and destination prompts. Open the returned URL and confirm the public deck matches your reviewed local talk.html.

Agent request: “Prepare the publish command and tell me what it will make public. Wait for my approval before running it.”

Three-Hour Completion Check

Exercise

Show a partner hello.qmd, the rendered HTML, the repaired error, and talk.html. If you published, show the Quarto Pub URL too. Explain:

1. Where YAML frontmatter, Markdown, and code each live.
2. Which CLI line identified the deliberate failure.
3. What changed when html became revealjs.
4. What you reviewed before sharing.

Done: your partner can reproduce the render and follow your diagnosis.

Four Optional Deliverables

The same agent workflow can produce a six-slide introduction, a three-page essay, a runnable notebook, and a separate blog from the reported INS/SIVICAP municipal IRCA table. Inspect each output before sharing it.

These projects extend the workshop; they are not required in three hours.

Shared Inputs for Tasks 1–3

From the workshop clone, copy the teaching bundle into your practice folder:

mkdir -p ~/code/quarto-play/context
cp examples/irca-colombia/* ~/code/quarto-play/context/

Check: return to your quarto-play agent session. Preserve the CSV.

Task 1: A Generated Introduction

Ask your coding agent in quarto-play:

Create intro.qmd for first-year data science students. Generate exactly six Reveal.js slides: title, the municipal IRCA question, what one row represents, the three departments in 2024, variation and limits, and sources. Use context/notes.md and context/sources.bib. Keep the dark theme, add speaker notes, and render intro.html.

quarto render intro.qmd --to revealjs

Outputs: intro.qmd and intro.html, six slides including title and sources.

Check: distinguish municipal annual summaries from water samples. Inspect every slide at desktop and laptop sizes, including links and captions.

Task 2: What Do Reported IRCA Values Show?

Ask your coding agent in quarto-play:

Write essay.qmd for data science students about reported 2024 municipal IRCA in Boyacá, Cundinamarca, and Santander. Use context/irca_boyaca_cundinamarca_santander.csv for every number and context/sources.bib for provenance. Exclude #TODOS department aggregates from municipality comparisons. Explain counts, medians, variation, and missing rural IRCA. Follow the next slide’s page plan. Render exactly three pages to essay.pdf and inspect them.

quarto render essay.qmd --to pdf

Outputs: editable essay.qmd and a three-page essay.pdf.

Essay Page Plan and Review

Use A4 paper, 11-point text, and 1-inch margins. Three pages total, including references, with no separate cover. Revise prose to fit.

Exercise

Trace each numerical claim to the CSV. Find one sentence that treats the municipal average as an individual water sample and ask your agent to revise it.

Task 3: Notebook Content

Ask your coding agent in quarto-play:

Adapt context/notebook.qmd into notebook.qmd here. Fix data and bibliography paths to context/. Include the question, 2024 municipal counts, medians, ranges, missing rural values, and a captioned IRCA distribution chart by department. State what a row represents. Include limitations and readable source links in Markdown. Convert to notebook.ipynb and execute it with saved results.

Outputs: editable notebook.qmd and runnable notebook.ipynb.

Check: all 318 municipality rows contribute; summaries and chart agree with the CSV. ND values are missing, not zero.

Task 3: A Runnable Jupyter Notebook

Run in quarto-play with the selected Python/Jupyter environment:

quarto convert notebook.qmd --output notebook.ipynb
jupyter nbconvert --to notebook --execute --inplace notebook.ipynb

Exercise

Open notebook.ipynb, restart its kernel, and run all cells from the task folder.

Done: code cells execute, the saved table and chart agree with the CSV, and source links work. An HTML page alone does not complete this task.

A Separate Blog Folder

Terminal, once: start a separate blog project and coding agent session.

mkdir -p ~/code/quarto-blog
cd ~/code/quarto-blog
# Start one coding agent:
claude
# Or: codex

Ask your coding agent:

Create a Quarto blog titled “Municipal Water Quality Notebook”. Initialize Git if needed and work on a blog-setup branch. Render the starter site and tell me how to preview it locally.

Output: an HTML website with a home page and a water-quality post. Check: the home page lists the starter posts before you add your own.

The Scaffold Command

The coding agent can run the scaffold command as part of that request:

quarto create project blog . --no-open --no-prompt

Check: the coding agent edits the generated configuration without losing its structure.

Choose What the Blog Publishes

Ask your coding agent:

In the blog’s _quarto.yml, restrict project.render to the home page, about page, and posts. Keep context/ as source material for the analysis. Preserve the existing site configuration.

project:
  type: website
  render:
    - index.qmd
    - about.qmd
    - posts/**/*.qmd

Check: after rendering, _site/context/notes.html and _site/context/notebook.html are absent. Add any new public pages to the list.

Municipal IRCA Context for the Post

Copy the shared teaching inputs into the separate blog:

mkdir -p ~/code/quarto-blog/context
cp ~/code/quarto-play/context/* ~/code/quarto-blog/context/

Check: #TODOS rows are department aggregates, not municipalities.

Your First Executable Post

Ask your coding agent:

Read context/notes.md and context/notebook.qmd. Create posts/municipal-irca/index.qmd with a question, executable Python reading the CSV, a 2024 municipal IRCA distribution chart, interpretation, and cited sources. Exclude #TODOS rows, fix paths for the post folder, and include a title, date, caption, and alt text. Render the blog and check its listing.

quarto render

Outputs: posts/municipal-irca/index.qmd, _site/posts/municipal-irca/index.html, and a listing in _site/index.html.

Check: the chart uses municipality rows and the home page links to the post.

A Cell the Coding Agent Might Write

One possible source pattern inside posts/municipal-irca/index.qmd:

```{python}
#| label: fig-irca-municipal
#| fig-cap: "Reported 2024 municipal IRCA (%) in three Colombian departments."
#| fig-alt: "Dot plot of 2024 municipal IRCA values grouped by department."
import pandas as pd
import matplotlib.pyplot as plt
water = pd.read_csv("../../context/irca_boyaca_cundinamarca_santander.csv")
municipal = water[(water.a_o == 2024) & (water.municipiocodigo != "#TODOS")]
for department, group in municipal.groupby("departamento"):
    plt.scatter([department] * len(group), group.irca, alpha=0.4)
plt.ylabel("Reported municipal IRCA (%)")
plt.ylim(0, 100)
plt.show()
```

Check: each point is an annual municipality summary, not a sample.

Provenance and Limits

Ask your coding agent:

Cite INS/SIVICAP for the reported IRCA values and explain the municipality-year unit of analysis. State that the chart describes reported 2024 values; it does not identify causes, measure individual exposure, or predict future water quality. Render the references.

• INS/SIVICAP open-data table
• DANE inventory of the IRCA statistical operation

Check: the post has working source links and a specific limitation.

Preview and Render

Ask your coding agent:

Start a local preview of this blog and give me its URL. I want to inspect the post, the listing, and the navigation in a browser.

Commands for your own terminal:

quarto preview
# When you need a fresh output build:
quarto render

Preview serves the site while you edit. Render creates the output files. Neither command publishes the blog to the public web.

Feedback That Changes the Page

Continue the same conversation after inspecting the post:

The plot does not explain that points represent annual municipality summaries. Add that to its caption and alt text. Re-render the whole blog.

Exercise

Find one real defect in your own preview and describe it to your coding agent.

Check: show the before-and-after source and the corrected page.

A Blog Checkpoint

Ask your coding agent:

Review this blog for broken local links, missing figure captions, and unsupported claims. Fix the issues you can verify. Render the whole site and report what you checked and what still needs my review.

Exercise

Open the home page, follow the post link, and return using navigation. Inspect the chart at a laptop viewport size.

Done: the listing works, the figure is readable, and the prose explains the dataset provenance and limits.

Four Task Completion Checks

• Introduction slides: intro.html has exactly six readable slides, including the title and references.
• Essay: essay.pdf has exactly three pages including references and explains what the reported municipal summaries can support.
• Data Jupyter notebook: notebook.ipynb runs from a fresh kernel and saves the 2024 municipal summaries and chart.
• Separate blog: the HTML home page links to the rendered municipal IRCA post.

For every task, keep editable sources, unchanged inputs, and a README.md with build commands. Check source links, provenance, and the unit of analysis.

What This Example Can Teach

Audience: students who have completed the execution exercise and can read a chart. Input: INS/SIVICAP annual municipal IRCA summaries for Boyacá, Cundinamarca, and Santander. One row is one municipality-year or department-year.

Source: Colombian open-data portal. The deck renders from the unchanged extract in examples/irca-colombia/.

Question: how did reported IRCA (%) vary among the three departments’ municipalities in 2024? The table has no individual samples or sensor readings.

Compare 2024 Municipality Records

import pandas as pd
import matplotlib.pyplot as plt

water = pd.read_csv(
    "examples/irca-colombia/irca_boyaca_cundinamarca_santander.csv",
    dtype={"departamentocodigo": str, "municipiocodigo": str},
)
current = water[(water["a_o"] == 2024) & (water["municipiocodigo"] != "#TODOS")]
summary = current.groupby("departamento")["irca"].agg(
    municipalities="count", median="median", minimum="min", maximum="max"
)
print(summary.round(1).to_string())

              municipalities  median  minimum  maximum
departamento                                          
Boyacá                   119     7.1      0.0     50.6
Cundinamarca             113     5.0      0.0     43.2
Santander                 86     9.6      0.0     93.9

Check: the three department counts sum to 318 municipality records.

Read the Reported Values

The median reported municipal IRCA is 7.1% in Boyacá, 5.0% in Cundinamarca, and 9.6% in Santander in 2024. These medians give each municipality equal weight; they are not population-weighted exposure estimates.

Question: what does a municipality with a higher reported value tell us, and what can this summary not establish about individual households?

See Variation Within Departments

The source also reports urban and rural IRCA, but ND means unavailable. Only 152 of 318 2024 municipality rows have numeric rural IRCA. Missing values cannot be treated as zero.

Audit the Claim

Exercise

Using examples/irca-colombia/, verify the three municipality counts and the number of available rural values. Then rewrite this claim:

“The chart shows that individual water samples in Santander will have a higher risk next year.”

Done: your statement names the 2024 municipality-level summaries and avoids predicting future samples or inferring individual exposure.

Reviewing the Files

Ask your coding agent:

Summarize the changes and explain which files are source, generated output, or local dependencies. Check the diff and suggest the files that belong in a commit. Keep this review local.

Commands for inspection:

git status --short
git diff --stat
git diff --check

Check: inspect new files too. A normal git diff omits untracked files.

Publishing Preparation

Ask your coding agent:

Prepare this personal blog for GitHub Pages. Inspect its configuration, render it, and explain the files and repository settings needed. Show the destination and intended visibility. Stop before creating a remote repository, pushing, or publishing.

Check: you recognize the account, repository name, visibility, and content.

The next slide uses Quarto’s gh-pages method for your new blog. This workshop itself serves committed docs/ from main.

Publishing Your Blog

After reviewing the destination, ask your coding agent:

Commit the reviewed blog files, create a public GitHub repository named my-blog under my account, push the source, and publish using Quarto’s gh-pages method. Check deployment and give me the live URL.

Commands involved, after the reviewed local commit:

gh auth status
# If needed, complete gh auth login yourself.
gh repo create my-blog --public --source=. --push
quarto publish gh-pages

Check: open the live URL and test a post link after deployment completes.

When a Build Fails

Ask your coding agent: include the failed command, exact error, and file path.

Running quarto render fails in posts/municipal-irca/index.qmd with the error below. Reproduce it, identify the cause, fix it, and rerun the full build. Keep execution enabled and preserve the figure. Explain what changed.

Check: the same command succeeds and the expected result still appears.

Exercise

In a disposable copy, misspell a Python variable. Ask your coding agent to repair the failure, then explain the diff before accepting it.

Collaborative Blog Exercise

Exercise — 30 minutes

Work in groups of 3–4. Each person owns a different post on their own branch.

Create a branch for my contribution. Write a post about my chosen topic using the notes I provide. Follow this blog’s existing conventions, render it, and show me the changes for review.

A partner reviews the evidence and preview. Ask your coding agent to address the feedback. One integrator combines the reviewed contributions and publishes.

Done: each post has a working link, an identifiable author, and a reviewed claim.

Other Inputs, Same Conversation

A notebook:

Adapt my municipal-IRCA analysis.ipynb into a blog post. Preserve the computations, add the missing explanation, and verify that the rendered results agree.

An R analysis:

Create a post from my R script. Prepare the required packages, add captions and units, and record a working render command.

Use the same checks: source, computation, evidence, and rendered result.

What You Should Be Able to Explain

• Which request caused a file or computation to change?
• Which Quarto command produced the page you inspected?
• What evidence made you accept the result?
• What revision did you request after seeing the output?

Continue with AI workflows: promotion experiments and sales outcomes.

References and Questions

• Quarto guide and Python computations
• Creating a blog, GitHub Pages, and Quarto Pub
• Codex CLI and prompting guidance
• Claude Code installation

New Quarto Pub and Reveal.js guidance checked 2026-10-28; other listed CLI and publishing guidance checked 2026-10-06.

Which part of your next publication would you ask your coding agent to build first?