Cut-over docs hosting from ReadTheDocs to Cloudflare Pages

[lucasrodes]

Written by Claude Code — @lucasrodes at the wheel.

The CF Pages parallel mirror is live at https://docs-cf.owid.io/ via three Pages projects (owid-docs, owid-etl-docs, owid-grapher-py-docs) with the umbrella _worker.js proxying subproject paths. RtD remains the authoritative docs.owid.io/ deploy until we cut over. See owid/owid-docs/INFRASTRUCTURE.md for how the pieces fit.

This issue tracks the cut-over plan once we're happy with the CF mirror.

1. Evaluation period (now)

Spot-check these pages on docs-cf.owid.io and confirm parity with RtD. The dynamically generated content is the highest-risk surface — those pages depend on pre-build scripts (docs/ignore/pre-build/*.py) and post-build notebook conversion, which CF runs through the same Make targets as RtD but in a fresh CI env.

• Umbrella — / (owid-docs landing, nav into subprojects)
• ETL — dynamically generated (most likely to drift):
  • /projects/etl/architecture/metadata/reference/ (from bake_metadata_reference.py)
  • /projects/etl/api/catalog-api/ (from bake_catalog_api.py + lib/catalog README)
  • /projects/etl/api/search-api/, chart-api/, semantic-search-api/
  • /projects/etl/guides/analytics-events/ (TypeScript-sourced, fetched from owid-grapher at build time)
  • /projects/etl/guides/etl-cli/ (CLI help)
  • any page under /projects/etl/analyses/ (Jupyter notebooks → HTML)
• ETL — static: /projects/etl/, /projects/etl/getting-started/, /projects/etl/contributing/
• owid-grapher-py: /projects/owid-grapher-py/, /projects/owid-grapher-py/api-reference/grapher/
• Cross-links between subprojects (the umbrella nav and any inline links)
• Search — top-bar search on each subproject (built by Zensical, index regenerated each build)
• Legacy URL redirects — /en/latest/, /projects/etl/en/latest/..., /projects/owid-grapher-py/en/latest/... should 301 to the canonical paths (see _worker.js in owid-docs)
• Sitemap + robots.txt at each project root
• 404 behavior — visit a nonexistent path under each subproject

Useful comparison: open the same URL on RtD and CF side-by-side. Differences in TOC, headings, or generated content are the signal that something needs fixing before cut-over.

2. Cut-over steps

When sign-off is ready:

• DNS (site team owns this) — repoint docs.owid.io from RtD's CNAME to the CF Pages domain. CF auto-issues a cert.
• CF Pages custom domain — attach docs.owid.io to the owid-docs project (CF dashboard → owid-docs → Custom domains).
• Detach docs.owid.io from the RtD owid-docs project (RtD admin → Domains) — new finding: the legacy COVID docs (RtD subproject owidcovid-19-data, never migrated to CF) have their native URL owidcovid-19-data.readthedocs.io 302-ing back to docs.owid.io/projects/covid/. If the domain stays configured on RtD after the swap, the COVID docs become unreachable from every URL (native → docs.owid.io → CF 404/redirect loop). 🔨 Cut-over prose + COVID docs redirect for docs.owid.io owid-docs#6 adds a _worker.js 301 for /projects/covid/* → the native RtD URL, which only works once the domain is detached.
• site_url override in each subproject workflow — change the sed line from https://docs-cf.owid.io/... to https://docs.owid.io/.... Affects: owid/etl .github/workflows/deploy-docs-cf.yml, owid/owid-grapher-py same file. → PRs ready: 📜 Point docs site_url at docs.owid.io for the CF cut-over #6217, 🔨 Point docs site_url at docs.owid.io for the CF cut-over owid-grapher-py#28 (safe to merge pre-swap).
• owid-docs zensical.toml already has site_url = \"https://docs.owid.io/\" — no change needed.
• _worker.js uses relative paths only — no change needed.
• docs-cf.owid.io custom domain — keep as a staging alias (decided 2026-06-07).
• Cross-references in code/docs — grep for docs-cf.owid.io and docs.owid.io across all three repos, update anything that hardcodes the staging URL. → Done in 📜 Point docs site_url at docs.owid.io for the CF cut-over #6217 (also fixes several already-404 doc links) and 🔨 Cut-over prose + COVID docs redirect for docs.owid.io owid-docs#6 (post-cut-over prose). (The Slack quick-links column we added to owidbot points at *.owid-etl-docs.pages.dev/projects/etl/ — that's a branch-alias URL, not a docs.owid.io URL, so no change.)

3. Cleanup (after cut-over is stable for ~1 week)

• Remove .readthedocs.yaml (this repo) and .readthedocs.yml (owid-docs, owid-grapher-py).
• Archive or delete the RtD projects (owid-etl, owid-docs, owid-grapher-py).
• Remove the legacy GH Pages workflow owid-docs/.github/workflows/docs.yml.
• Drop the legacy /en/latest/ 301 rule from _worker.js once external links have had time to update (or keep indefinitely — it's tiny and harmless).

Coordination

The DNS swap is the only step that requires the site team (Bastian / Mojmir). Everything else is self-contained in these three docs repos.

[lucasrodes]

Written by Claude Code — @lucasrodes at the wheel.

Status update (2026-06-07): the code side of the cut-over is ready. Three draft PRs, all safe to merge before the DNS swap (every touched URL resolves on both hosts today):

• 📜 Point docs site_url at docs.owid.io for the CF cut-over #6217 — workflow site_url → docs.owid.io + fixes for several doc links that were already 404 (lib/catalog/README.md's /en/latest/api/catalog/... trio, root README's libraries/catalog/, datautils' dead RtD badge) and legacy /en/latest/ segments.
• 🔨 Point docs site_url at docs.owid.io for the CF cut-over owid-grapher-py#28 — workflow site_url → docs.owid.io.
• 🔨 Cut-over prose + COVID docs redirect for docs.owid.io owid-docs#6 — post-cut-over README/INFRASTRUCTURE prose + a new _worker.js 301 for /projects/covid/*.

New finding (now in the checklist): the legacy COVID docs are an RtD subproject (owidcovid-19-data) that was never migrated to CF, and its native RtD URL currently 302s back to docs.owid.io. At swap time the docs.owid.io custom domain must be detached from the RtD owid-docs project, or the COVID docs become unreachable from every URL.

Remaining manual steps (in order):

1. Merge the three PRs.
2. CF dashboard → owid-docs Pages project → Custom domains → attach docs.owid.io.
3. RtD admin → owid-docs project → Domains → remove docs.owid.io.
4. Site team repoints docs.owid.io DNS: CNAME readthedocs.io → owid-docs.pages.dev.
5. Smoke-test the spot-check list from the issue description on docs.owid.io.

docs-cf.owid.io stays attached as a staging alias.