docs: stage the docs on Cloudflare at impulso-next.quantclimate.com

.github/workflows/main.yml

@@ -324,3 +324,40 @@ jobs:
       - name: Deploy documentation
         id: deployment
         uses: actions/deploy-pages@v5
+
+  deploy-docs-cloudflare:
+    # Serves the same build from Cloudflare (docs/wrangler.jsonc). Runs next to
+    # the GitHub Pages deploy while the docs are staged on a second hostname.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [quality, tests-and-type-check, build-docs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    concurrency:
+      group: cloudflare-docs
+      cancel-in-progress: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v7
+
+      - name: Download the docs build
+        uses: actions/download-artifact@v8
+        with:
+          name: github-pages
+
+      - name: Unpack the docs build
+        run: |
+          mkdir -p docs/_build/html
+          tar -xf artifact.tar -C docs/_build/html
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+
+      - name: Deploy to Cloudflare
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+        run: npx --yes wrangler@4.145.0 deploy --config docs/wrangler.jsonc

docs/_redirects

@@ -0,0 +1,5 @@
+# Cloudflare static-asset rules, copied to the site root by html_extra_path.
+# html_handling is "none" in docs/wrangler.jsonc, so a directory URL only
+# serves its index.html through these rules.
+/ /index.html 200
+/*/ /:splat/index.html 200

docs/conf.py

@@ -153,6 +153,8 @@
 ogp_social_cards = {"enable": False}
 html_static_path = ["stylesheets"]
 html_css_files = ["extra.css"]
+# Cloudflare serves the site; _redirects maps directory URLs to index.html.
+html_extra_path = ["_redirects"]
 html_theme_options = {
     "accent_color": "crimson",  # names the token family; stylesheets/extra.css re-tones the crimson scale to ledger oxblood
     "color_mode": "auto",  # follow the reader's light/dark preference

docs/wrangler.jsonc

@@ -0,0 +1,19 @@
+// Cloudflare Workers configuration for the docs: the Sphinx HTML build is
+// served as static assets, with no Worker code. The `deploy-docs-cloudflare`
+// job in .github/workflows/main.yml deploys it on every push to main.
+{
+  "name": "impulso-docs",
+  "compatibility_date": "2026-09-30",
+  // Serve the docs only on the custom domain, not on workers.dev.
+  "workers_dev": false,
+  "preview_urls": false,
+  // Cloudflare creates the DNS record and certificate for this hostname.
+  // Staging hostname: GitHub Pages still serves impulso.quantclimate.com.
+  "routes": [{ "pattern": "impulso-next.quantclimate.com", "custom_domain": true }],
+  "assets": {
+    "directory": "./_build/html",
+    // Serve every file at exactly the URL Sphinx gives it (/page.html stays
+    // /page.html). docs/_redirects maps / and /dir/ to their index.html.
+    "html_handling": "none"
+  }
+}