[mikkel]

What

patchling.app now gets a build step. bash scripts/build-site.sh writes dist/:

Path	Content
/	landing/ unchanged (demo page)
/py/	patchling-py docs. A shallow public clone of 255BITS/patchling-py main (no token) is built with mkdocs build --strict, from the same mkdocs.yml and nav as gptdiff.255labs.xyz. Only site_url is overridden, to https://patchling.app/py/.
/js/	JS docs. This repo's README.md, CHANGELOG.md and docs/deploy.md, rendered with the same mkdocs-material (scripts/site/mkdocs.js.yml, --strict).
/docs, /docs/*	301 to /py/, /py/:splat (dist/_redirects, Cloudflare Pages syntax)

The landing page's Python "Docs" link was stale (255bits.github.io/patchling-py); it now goes to /py/. The JavaScript card gains a "Docs" link to /js/, and the top nav gains "JS docs" and "Py docs".

Zero-dependency library:

• The build tooling is one bash script plus mkdocs-material==9.6.22 (the same pin as patchling-py's Deploy Documentation workflow), installed into a throwaway venv under .site-build/.
• package.json is untouched, files is still ["src"], and dist/ and .site-build/ are gitignored.
• npm pack --dry-run is identical to main: 19 entries, 202,017 bytes.

The expected Pages settings in scripts/check-pages-settings.mjs (EXPECTED), docs/deploy.md and the fixture now say bash scripts/build-site.sh / dist. Until the dashboard is changed, a live node scripts/check-pages-settings.mjs will report that drift on purpose.

One-time setup (Mikkel). Nothing has been changed in Cloudflare.

Cloudflare dashboard → Workers & Pages → patchling → Settings:

1. Builds → Build configuration → Edit
   • Build command: bash scripts/build-site.sh
   • Build output directory: dist
   • Root directory: (leave empty)
2. Variables and Secrets (Production and Preview), plain text: PYTHON_VERSION = 3.12. No secrets are needed: the clone is public.
3. Timing. Do steps 1–2 right before merging this PR, then merge.
   • Changing settings doesn't trigger a build. The next push to main (this merge) is the first build with them.
   • In the other order, main lacks the script and the build would fail, though the current deployment stays live.
   • Do the reverse when reverting.
4. Deploy hook for patchling-py #28 (Builds → Deploy hooks → Add): name patchling-py, branch main. Store the URL as the patchling-py repo secret CF_PAGES_DEPLOY_HOOK_PATCHLING_APP.

How #28's hook fits

Every Pages build of this repo clones patchling-py main fresh. patchling-py #28 calls the deploy hook whenever docs or package files change on its main. That makes Pages rebuild main here, so /py/ picks up the new docs within one build, with no push to this repo. #28 needs no code change.

Tests (local)

• Build: bash scripts/build-site.sh built patchling-py@9555eb88 in about 15 s, 120 files in dist/, with --strict clean for both /py/ and /js/.
• Served dist/ with a small static server that applies dist/_redirects, checked with Playwright:
  • 200 and no failed same-origin requests or assets on /, /py/, /py/cli/, /py/api/, /py/examples/basic/, /js/, /js/CHANGELOG/ and /js/deploy/.
  • All four new links (nav and cards) open the right docs.
  • /docs/quickstart/#install → /py/quickstart/#install.
• npm test: 251 tests, 247 pass, 4 skipped (live), 0 failed. This includes new checks:
  • the landing links point at /py/ and /js/;
  • landing/ has no py/js/docs that would collide with the build output;
  • the _redirects rules;
  • files is ["src"] with no dependencies;
  • updated Pages-settings negatives.
• node scripts/check-release-version.mjs --main passes.
• npm pack --dry-run is identical to origin/main.

Note: previews of this PR use the current settings (no build), so the /py/ and /js/ links 404 there until step 1 is done.

Deployment sequencing

• Ship the Pages settings change together with this merge. Switch the Cloudflare Pages build command to bash scripts/build-site.sh / output dist at the same moment site: serve patchling-py docs at /py/ and JS docs at /js/ on patchling.app #13 merges to main, so there is no Pages build from the old main with the new settings (or the new main with the old settings) in between. Don't trigger a retry/redeploy in the gap.
• Merging either patchling-py PR deploys immediately. patchling-py#28 starts calling the Pages deploy hook on every qualifying push to patchling-py main (once the secret exists); patchling-py#29 changes the gptdiff.255labs.xyz docs workflow. Merge them only after site: serve patchling-py docs at /py/ and JS docs at /js/ on patchling.app #13 is live.
• Check the real /py/ docs before turning on the redirect. After site: serve patchling-py docs at /py/ and JS docs at /js/ on patchling.app #13 deploys, open https://patchling.app/py/ (plus a deep link like /py/cli/, /docs/ → /py/ 301, and /build-info.json to confirm the patchling and patchling-py SHAs) before setting GPTDIFF_REDIRECT_TO_PATCHLING_APP on patchling-py.
• Rollback: unset/false GPTDIFF_REDIRECT_TO_PATCHLING_APP and rerun Deploy Documentation to restore gptdiff.255labs.xyz; in Cloudflare Pages, roll back to the previous production deployment (Deployments → ⋯ → Rollback) and restore the old build command/output; revert site: serve patchling-py docs at /py/ and JS docs at /js/ on patchling.app #13 (and #28 if needed) on main with a normal revert commit.

[cloudflare-workers-and-pages]

Deploying patchling with    Cloudflare Pages

Latest commit:	806c0fa
Status:	✅  Deploy successful!
Preview URL:	https://9259b6ca.patchling.pages.dev
Branch Preview URL:	https://build-docs-from-patchling-py.patchling.pages.dev

View logs