Lesson 1 of 3  ·  WECA Regional Indicators Workflow

The Freeze Cache

Why it exists, how it works, and the four files you always commit

⏱ ~10 minutes

The problem this solves

Five analysts. Five laptops. Five sets of raw data — none of which can go into git (too large, potentially sensitive). One published book on GitHub Pages.

How does GitHub build the full report when it has none of the raw data?

The answer is the freeze cache.

How the freeze cache works

When you render your chapter locally:

quarto render chapters/05-environment/index.qmd

Quarto runs your R code, produces your charts and tables, then saves a photograph of all the outputs to the _freeze/ directory:

_freeze/ chapters/ 05-environment/ index/ execute-results/ html.json ← the "photograph" of your outputs figure-html/ my-plot-1.png ← any generated figures

The html.json file contains everything needed to rebuild your chapter page: every table, every number, every chart reference.

The fingerprint check

Each time GitHub builds the book, Quarto checks whether your source file has changed by comparing fingerprints (hashes):

Source file fingerprint == Stored fingerprint in html.json? ✅ MATCH → Use the photograph. Raw data never needed. ❌ MISMATCH → Try to re-run your R code → FAIL (no raw data on GitHub)

Critical rule

Every time you change your chapter source, you must re-render locally and commit the updated html.json. Even a one-word edit to a heading will break the fingerprint match.

The four files you always commit together

A contribution to this book is never a single file. It is always exactly these four things:

chapters/0X-topic/index.qmd

The narrative and code for your chapter.

scripts/R/0X-topic/RI_XY_name.R

The indicator script that processes raw data into a fact CSV.

data/fact/RI_XY_name.csv

The processed indicator data. Small enough to commit; no sensitive raw data.

_freeze/…/html.json

The freeze snapshot. Without this, GitHub can't render your chapter.

The workflow in sequence

  1. Start from a fresh main — always branch from an up-to-date main before doing any work.
    git checkout main && git pull && git checkout -b yourname/chapter-name

  2. Render your chapter locally — your raw data must be in data/raw/.
    quarto render chapters/0X-topic/index.qmd

  3. Check what git sees — verify the four files appear as modified or untracked, and that nothing unexpected has changed.
    git status

  4. Stage exactly the right files — name them individually, never git add .

  5. Commit and push to your branch.

Missing any of the four files means a publishing failure. The freeze snapshot is the most commonly forgotten.

Check your understanding

Click an answer. Explanations reveal after each selection.

You make a small edit to your chapter — fixing a typo in a heading. What happens when GitHub Actions tries to build the book?

Any edit — even a single character — changes the source file's hash. Quarto detects a fingerprint mismatch and tries to re-execute your code. Since GitHub has no raw data, it fails with a "path does not exist" error. The fix: re-render locally, commit the updated html.json.

Which four files must always be committed together for a successful contribution?

The four are: (1) chapter source .qmd, (2) indicator R script in scripts/R/, (3) fact CSV in data/fact/, and (4) the freeze snapshot html.json. Never commit renv.lock, .Rproj, raw data, or .Renviron — these belong to the project lead or stay local.

What does the html.json file inside _freeze/ actually contain?

Think of html.json as a photograph of everything your code produced: every table cell, every chart reference, every computed number. It also stores the source file's fingerprint so Quarto knows whether the source has changed since the snapshot was taken. This is the entire mechanism that lets GitHub build the book without your raw data.

The one thing to remember

Change your chapter → re-render → commit the updated html.json. Every time, without exception.

Primary source: WORKFLOW_LEARNING_GUIDE.md — the authoritative guide for this project's publish workflow.

Have a question? Ask your teacher in this conversation — just type it and continue the session.