Docs site deploy failure

Runbook for when this docs site won't build or deploy on Cloudflare Pages — usually a dependency bump that broke the pinned, known-good build. Reproduce locally, revert, redeploy.

Symptom: A commit to main didn’t go live — the Cloudflare Pages build failed, and docs.leif.super-ht.com is stale or showing an error.

Likely cause

The build runs in Cloudflare’s CI, so a bad edit doesn’t break anything until it’s pushed — but once pushed, a broken build means no deploy. The usual culprit is a dependency bump: package.json versions are pinned deliberately to dodge the Astro 5.18 / Zod v4 / Starlight 0.30 incompatibility, and a “minor” upgrade can break the build in CI where it’s harder to debug than locally. Other causes: bad frontmatter, a malformed MDX/directive, or a missing file referenced by the build.

Diagnose

Reproduce the CI build locally — it’s the same npm install + npm run build:

npm install
npm run build

The error you get locally is the error CI got. Common shapes:

  • Dependency/version error (Zod, Astro, Starlight version mismatch) → a bump broke the pinned set.
  • Content collection / frontmatter error naming a file → fix that page’s frontmatter.
  • MDX / remark error → a malformed :::callout or other directive.

Check whether package.json or the lockfile changed in the offending commit — that points straight at a dependency cause.

Fix

  • Dependency bump: revert package.json (and the lockfile) to the pinned, known-good versions and rebuild. Don’t re-bump without a local build passing first. The pins are intentional — see Cloudflare Pages Deploys.

  • Content/frontmatter: fix the page the local build named, confirm npm run build passes, then commit.

Commit the fix to main (via github_create_or_update_file or a normal push) — Cloudflare Pages rebuilds on the push.

Verify

  • Local npm run build completes cleanly ([build] Complete!).
  • The Cloudflare Pages deploy for the new commit succeeds.
  • docs.leif.super-ht.com reflects the change.
fetch_url(url="https://docs.leif.super-ht.com/", max_bytes=2000)