9  Publishing and Proving the Rebuild

Keywords

Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering

The guide is finished, and nobody but you can see it: every output sits in a folder on your computer. This chapter puts it on the web, where anyone can open it on a phone, with GitHub to keep a copy of the history you have been committing and GitHub Pages to serve the result. Then it asks the question the whole workflow is built to answer: if one input changes, which outputs change with it, and how do you know? That question comes with no prompt. It tests whether you can predict what a rebuild will do, and then check.

In this chapter
  • Explain what pushing, branches and pull requests add to the commits you already make.
  • Make the folder a website and publish it to GitHub Pages.
  • Choose between hosts that take your files and hosts that build.
  • Predict, rebuild and explain what one changed input reaches.

Start fromthe end of Chapter 8, with gh signed in

You builda website, its GitHub repository and the live site

Checkpointnone; the catch-up copies examples/london/

9.1 Git: every change, safely

Section 1.4 likened Git to Word’s Track Changes for a whole folder, with a lasting history, and since the first report (Section 5.4) you have kept one yourself: git status and git diff before each commit, a message that says why, and git restore for a change you did not want. That is what Git does inside one folder, and it already keeps every earlier version of the guide, each with a note saying why it changed. Publishing needs what Git does beyond the folder: a copy of the history that others can reach, and a way for someone else to read a change and approve it before it counts.

The vocabulary for that is short (Figure 9.1; Pro Git and GitHub’s documentation, checked 2026-10-31). Your folder is already a repository, a project folder with its history, and each of your commits is a snapshot of every tracked file with its message. The new words are about sharing them.

Six steps. Branch: work on a branch, so main stays untouched. Commit: save a snapshot of the files with a message saying why. Push: copy the commits to GitHub. Pull request: propose the change and show the difference. Review: someone reads the difference and comments, approves or asks for changes. Merge: the commits join main. Working alone, you commit to main and push; in a team, every change goes round the whole loop.
Figure 9.1: Every change, safely. A team takes each change round the whole loop; working alone, as in this book, you commit to the main line and push.

To push is to copy commits to the shared repository on GitHub, the website that keeps a copy of a repository online. A branch is a movable label on a line of commits, so work can go on there while the main line, main (the name git init -b main gave it), keeps working. A pull request proposes merging a branch and shows its difference, or diff, line by line, as git diff does in your terminal, but on a page that others can read; a review comments on it, approves it or asks for changes; merging adds its commits to main.

Working alone, as in this book, you commit straight to main and push; in a team, every change goes round the loop. Either way the check is the one you already make: read the diff before a change counts. From here the agent can run the Git commands too. Ask it to “commit with a message that says why”, and read its diff before you approve: a diff is the clearest check you have of what the agent actually did.

Pause and think

The agent reports “Committed the dashboard changes” and asks to push. What do you check before you approve?

Answer

The diff behind the commit: which files and lines changed, that they are the ones you asked for, that nothing in data/ or images/ changed, and that the message says why.

9.2 Where a site lives

A rendered Quarto website is static: a folder of HTML, CSS, JavaScript, images and documents, with no program running on a server. Any web server can serve it, so publishing means copying that folder to a host. GitHub Pages is the host this book uses, because the repository is already on GitHub and quarto publish gh-pages is built in (Figure 9.2).

Your project folder holds the source, which git pushes to the main branch of a GitHub repository. quarto publish gh-pages renders the site on your computer and pushes only the rendered HTML to a separate branch, gh-pages. GitHub Pages serves that branch at https://user.github.io/repo/. Anyone with the address can read the site.
Figure 9.2: Publishing to GitHub Pages. The source goes to the main branch with Git; quarto publish gh-pages renders the site on your computer and pushes only the rendered HTML to a separate branch, which GitHub serves.

There are two ways to get a site onto a host. Either you render on your own computer and upload the result, as quarto publish does for GitHub Pages and Netlify, or the host builds the site from your repository on every push. The second works only if the build installs Quarto, Python and every package the project needs, or if the rendered output is committed. The London repository leaves its rendered _site/ folder out, so a host that builds would produce nothing until the build is set up.

Pause and think

You connect london-guide to a host that builds from Git, and it publishes an empty site. Why?

Answer

The repository holds no rendered site, because .gitignore leaves _site/ out, and the host’s build has no Quarto, Python or packages unless you install them in it. Either render on your computer and upload the result, or set up the build.

Six hosts with free plans for static sites show the two routes (Table 9.1, Table 9.2). Their free plans change, so Table K.2 in Appendix K lists each one’s current limits, with the date they were checked: read them before choosing.

Table 9.1: Hosts you render for and upload to.
Host Upload with
GitHub Pages quarto publish gh-pages, this book’s route
Netlify quarto publish netlify
Cloudflare wrangler deploy
Table 9.2: Hosts that build the site from your repository.
Host How it builds
Vercel from the repository, on every push
GitLab Pages publishes a public folder from a CI job
Render rebuilds on every push

Two details matter for this project. Quarto’s Netlify build plugin runs no Python, so render on your computer and upload. GitLab builds in a CI job, a build it runs on each push: set output-dir: public and install Quarto and Python in the job. Quarto Pub, Quarto’s own free host, is being replaced by Posit Connect Cloud.

9.3 One folder, one website

Ask your coding agent
Make this folder a Quarto website: _quarto.yml (render only the .qmd files; navbar: Guide, Dashboard, a Downloads menu for the docx, pdf, pptx, epub and london-slides.html files that exist) and index.qmd, and add /_site/ to .gitignore. Render and check the links.
Expect it to run

writes 2 files · adds a line to .gitignore · uv run quarto render → _site/

You do

then, in the preview tab: Ctrl+C, and uv run quarto preview

A _quarto.yml file at the top of the folder turns it into a project. quarto render with no file name then builds every listed page into _site/, with shared navigation, and quarto preview with no file name previews the whole site. The dashboard becomes one page of it:

project:
  type: website
1  render:
    - index.qmd
    - london.qmd
    - london-dashboard.qmd
website:
  title: "Visit London"
  navbar:
    left:
      - {text: Guide, href: london.qmd}
      - {text: Dashboard, href: london-dashboard.qmd}
2      - {text: Downloads, menu: [...]}
1
An explicit render list keeps the README, the data notes and the photo credits from becoming pages of the site.
2
The menu links the files the other formats wrote: the Word guide, the PDF, the flyer, and whichever optional files you made.

.gitignore gains one line, for the rendered site, _site/, which is rebuilt from the source and published separately (Section 9.4). The rest of the list has been there since you started the folder (Section 6.2): the environment .venv/ (rebuilt from uv.lock), Quarto’s working files and the outputs rendered beside the sources. index.qmd becomes the site’s home page, index.html, the page a visitor sees at the site’s address.

ImportantTry it

Make the folder a website and restart the preview.

You’re done when the site opens with Guide, Dashboard and Downloads in its navigation bar, and each Downloads link opens its file.

9.4 Publish

Before you paste the next prompt, replace <your-github-username> with your GitHub username (the agent can look it up with gh api user if you ask it to).

Ask your coding agent
If this folder is not yet a Git repository, run `git init -b main`; check that .gitignore covers _site/, .quarto/, .venv/, *_files/, *.quarto_ipynb, london*.html, *.docx, *.pdf, *.pptx and *.epub. Replace README.md in this folder with a short one linking to https://<your-github-username>.github.io/london-guide/ and listing the files in the site's Downloads menu. Commit it with any work not yet committed (nothing that .gitignore leaves out), then create a public GitHub repository named `london-guide` with gh and push `main` to it. Set the repository's website to the same URL with `gh repo edit --homepage`. Show me the README and the website URL you set.
Expect it to run

git status · git commit · gh repo create london-guide … · gh repo edit --homepage …

You do

approve gh · in the preview tab: Ctrl+C, then uv run quarto publish gh-pages and Enter · open the address on your phone

The agent creates the repository on GitHub from your folder with gh repo create london-guide --public --source=. --push, which also pushes the commits, using the sign-in from the setup check. Every commit you have made since you started the folder goes with them, so the repository on GitHub opens with the guide’s whole history, one checked step at a time. Its README is the first thing visitors to the repository see, and its link takes them on to the live site.

The first publish is yours, typed in the terminal. Stop the preview first: the publish renders the whole site, and two renders in one folder collide. It asks one question, “Publish site … (Y/n)”, which Enter answers yes; then it renders the site, creates the gh-pages branch, pushes the rendered site and opens it. Quarto’s GitHub Pages guide says to run quarto publish gh-pages locally, once, before setting up a GitHub Action to publish (checked 2026-11-12). Make that first run interactive, too: in a dry run with Quarto 1.6.40, --no-prompt stopped the first publish with “the remote origin does not have a branch named gh-pages”. That was observed with 1.6.40 and not re-tested with 1.10.20. Once the branch exists, the agent can update the site with uv run quarto publish gh-pages --no-prompt.

In that dry run, the first publish of each site took one and a half to two minutes, and GitHub Pages then built it in 20 to 35 seconds, so a 404 page in the first minute usually means the site is still being deployed.

WarningCommon pitfall

A push that fails with HTTP 400 (“RPC failed”, “the remote end hung up unexpectedly”) was seen with larger sites, such as dashboards with embedded maps. Raise Git’s buffer for this repository with git config http.postBuffer 524288000, and push again.

TipIn practice

Publishing from your own computer is simple and keeps the build where your environment is. The alternative, a GitHub Action that renders on every push (Quarto’s quarto-dev/quarto-actions), needs Python and the project’s packages installed in the job, or freeze set so that committed results are reused, and Quarto’s guide still asks for one local quarto publish gh-pages first.

ImportantTry it

Publish the guide.

You’re done when https://<your-github-username>.github.io/london-guide/london-dashboard.html opens on your phone.

Stuck for two minutes? Paste this into your agent. It backs up your work and brings the project to this point; then carry on from here.

Catch me up: follow ../quarto-workshop/examples/london/README.md

9.5 Change one input, explain the rebuild

Chapter 1 began with a correction (Section 1.1): ALVA revises one figure, and in a copy-and-paste workflow someone has to carry it by hand into every file that quotes it. Here is that scenario for real, in a project where no visitor count was ever copied. You made the same move on a smaller scale with the first report (Section 5.5) and predicted one for the guide’s first three formats (Section 7.5); now it covers every page. No prompt is supplied: write your own, or do it by hand. Make the edit to the data yourself, for example with nano data/attractions.csv (Ctrl+O, Enter, Ctrl+X): the project’s rules keep the agent out of data/, which is the point of them.

ImportantTry it
  1. Predict. Set the Tower of London’s visits_2025 in data/attractions.csv to 8000000. Which outputs will change? Write it down before you read on.
  2. Rebuild: stop the preview, then run uv run quarto render.
  3. Explain which outputs changed, which did not, and why.
  4. Undo with git restore data/attractions.csv, then rebuild.

You’re done when you can name the outputs that changed, the ones that did not, and the line of code that links each changed output to the input.

The value is fictitious: chosen to change the top attraction, so that the effect is visible, and reversible, because the real file has been committed since you copied it in (Section 6.8). git restore puts a file back as it was at the last commit, and the second rebuild leaves no trial number in your files.

Check your prediction

To check, you need to know which page reads which input. Table 9.3 is computed from the finished project’s sources, optional pages included: a page counts as reading a file only if its code loads it.

Table 9.3: Which page of the finished London project (each a .qmd file) reads which file in data/, and the formats it writes. Computed from the sources: a mark means the page’s code loads the file.
Page Writes attrac­tions visits churches sights
london html, docx, pdf, pptx, epub, slides ●
london-dashboard html ● ● ●
london-email docx ●
london-flyer pdf
london-social pdf ●
london-whitepaper pdf ● ●

In all, five pages load attractions.csv, and between them they write ten files, so the change reaches all of them at the next render.

What it does there depends on each page’s code. Of those pages, three (the guide, the dashboard and the partner brief) find the top attraction with attractions["visits_2025"].idxmax() and the total with .sum(), so in each of them the Tower of London becomes the most visited attraction and the total rises. The square advert uses only the first call, so it names the Tower too.

The white paper names no top attraction: its sums by admission change, but its table keeps ALVA’s rank_uk column from the file, which would still rank the Tower ninth in the UK beside the most visits of the ten. A copied column goes stale too. Still, that answers the question Chapter 1 began with: the correction reaches ten files with one command, and nobody has to go looking for them.

Copies deserve a second look. The flyer loads no data at all, and the sights tables in the guide and the partner brief are typed, although the guide’s credits name sights.csv: all three copy their facts (price bands, nearest stations) from the cited file into the Markdown. That was a reasonable choice, because those facts rarely change, but it means a correction to sights.csv updates none of them. A cited copy is still a copy.

NoteWhy this works

Why does every page recompute, even ones whose sources did not change? Because the project keeps Quarto’s default, freeze: false: every render re-runs every page’s code, which keeps this exercise’s answer simple. With caching turned on, a page whose own source did not change would keep its old numbers, and the answer would depend on the cache; Chapter 23 returns to that trade-off.

Two more things do not change: the live site, until you publish again (uv run quarto publish gh-pages --no-prompt), and any output you did not rebuild. Model answers, with the follow-up questions worth asking, are in Appendix E.

9.6 A white paper (optional)

The same data can also become an academic paper: an abstract, numbered sections, computed results and a reference list, set in the typeface LaTeX documents use, without installing LaTeX.

Ask your coding agent
Create london-whitepaper.qmd, an A4 Typst white paper in "New Computer Modern": an abstract (no inline code), numbered Introduction, Methods, Results and Conclusions, then References via `#set bibliography(title: [References])` (references.bib from `url`). Analyse data/visits.csv vs 2019 and data/attractions.csv by `admission`. Add it to `render` and the "Downloads" menu; render; check citations. Figures must be vector: set `fig-format: svg` and check that the files in `figure-typst/` end in .svg.
bibliography: references.bib
format:
  typst:
1    mainfont: "New Computer Modern"
2    section-numbering: "1.1"
3    bibliographystyle: ieee
4    fig-format: svg
1
Typst 0.15, bundled with Quarto 1.10.20, includes New Computer Modern, the OpenType version of LaTeX’s Computer Modern, so the paper looks like a LaTeX article without a TeX installation.
2
Numbers the headings: 1, 1.1, 2.
3
Typst’s numbered reference style; [@key] in the text cites an entry in references.bib.
4
Vector figures stay sharp at any zoom; the prompt’s check makes sure they really are vectors.
The first page of an A4 paper set in a LaTeX-style typeface: the title Visits to London's leading ALVA member attractions, 2015 to 2025, the subtitle Pandemic loss and recovery: a descriptive analysis, the author London Tourism Office, an abstract, and sections 1, Introduction, and 2, Methods, with numbered citations in square brackets.
Figure 9.3: The first page of the finished London white paper: title, abstract, and numbered sections with citations. Rendered from examples/london/london-whitepaper.qmd.
WarningCommon pitfall

Three traps, all met while building the example. The paper’s settings need Quarto 1.10 or newer: Quarto 1.6.40’s Typst rejects them with “unexpected argument: spacing”. An inline expression in a YAML abstract runs before the setup cell and fails, so the finished example writes its abstract in the body, in a raw Typst block. And Typst prints its own heading above the reference list, “Bibliography” by default, which the prompt changes with #set bibliography(title: [References]) so the paper needs no References heading of its own.

A genuine LaTeX PDF is also available, as format: pdf, but it needs a TeX distribution, for example quarto install tinytex. For most reports Typst is faster and simpler.

Summary

  • Pushing copies your commits to GitHub; a pull request shows a diff for someone else to review before it counts.
  • A built site is static files: upload them, or let a host build them.
  • A _quarto.yml with a render list makes a folder a website.
  • The first quarto publish gh-pages is yours; later updates can be the agent’s.
  • A changed input reaches every page whose code loads it; copies and the live site do not.

That completes one guide for many audiences. In the water analysis the hard part is the analysis itself: grouping Colombia’s municipal zones into kinds by water safety, services and context. That one analysis is then published as a report, slides, a blog post and a website, all reading the results of one script, and its rebuild test changes a setting of the analysis instead of a number in a table.

Further reading