Add the workflow

.github/workflows/docs-deploy.yml

@@ -3,7 +3,8 @@ name: "Deploy (docs)"
 on:
     # Run on every push to main that changes docs/
     push:
-        branches: [main]
+        # TODO (MR): Added testing branch here. Remove.
+        branches: [main, deploy-docs]
         paths:
             - "docs/**"
             - ".github/workflows/web-lint.yml"
@@ -13,9 +14,16 @@ on:
 jobs:
     deploy:
         runs-on: ubuntu-latest
+
         defaults:
             run:
                 working-directory: docs
+
+        # cloudflare/pages-action needs these to create deployments
+        permissions:
+            contents: read
+            deployments: write
+
         steps:
             - name: Checkout code
               uses: actions/checkout@v4
@@ -33,3 +41,13 @@ jobs:
             - name: Build production site
               # Will create docs/.vitepress/dist
               run: yarn build
+
+            - name: Publish
+              uses: cloudflare/pages-action@1
+              with:
+                  accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+                  apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+                  projectName: docs-3d7
+                  directory: docs/docs/.vitepress/dist
+                  gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+                  wranglerVersion: "3"

web/docs/deploy-new.md

@@ -29,9 +29,47 @@ Upload](https://developers.cloudflare.com/pages/get-started/direct-upload/).
 > it worked when I tried, and it seems to have worked for [other people
 > too](https://community.cloudflare.com/t/linking-git-repo-to-existing-cf-pages-project/530888).
 
+
 There are two ways to create a new project, using Wrangler
 [[1](https://github.com/cloudflare/pages-action/issues/51)] or using the
 Cloudflare dashboard
 [[2](https://github.com/cloudflare/pages-action/issues/115)]. Since this is one
 time thing, the second option might be easier.
 
+The remaining steps are documented in [Cloudflare's guide for using Direct
+Upload with
+CI](https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/).
+As a checklist,
+
+- Generate `CLOUDFLARE_API_TOKEN`
+- Add `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` to the GitHub secrets
+- Add your workflow. e.g. see `docs-deploy.yml`.
+
+This is the basic setup, and should already work.
+
+## Deploying multiple sites
+
+However, we wish to deploy multiple sites from this same repository, so the
+standard Cloudflare conception of a single "production" branch doesn't work for
+us.
+
+Instead, we use tie each deployment to a branch names. Note that we don't have
+to actually create the branch or push to it, this branch name is just used as
+the the `branch` parameter that gets passed to `cloudflare/pages-action`.
+
+Since our root pages project is `ente.pages.dev`, so a branch named `foo` would
+be available at `foo.ente.pages.dev`.
+
+Finally, we create CNAME aliases using a [Custom Domain in
+Cloudflare](https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/)
+to point to these deployments from our user facing DNS names.
+
+As a concrete example, the GitHub workflow that deploys `docs/` passes "help" as
+the branch name. The resulting deployment is available at "help.ente.pages.dev".
+Finally, we add a custom domain to point to it from
+[help.ente.io](https://help.ente.io).
+
+## GitHub deployments
+
+In our workflow we use the `deployments: write` permission and pass the
+resulting `GITHUB_TOKEN` to the Cloudflare Pages Action ([docs](https://github.com/cloudflare/pages-action)).