ci: deploy to Cloudflare Workers

.github/workflows/deploy-cloudflare.yml

@@ -0,0 +1,44 @@
+name: Deploy to Cloudflare Workers
+
+on:
+  push:
+    branches: [main]
+    # The README doesn't change the site, so it doesn't redeploy.
+    paths-ignore:
+      - "README.md"
+  workflow_dispatch:
+
+# Never run two deploys at once; queue rather than cancel so an in-flight
+# deploy is not interrupted.
+concurrency:
+  group: deploy-cloudflare
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Deploy to Cloudflare Workers
+        # `pnpm deploy` is a pnpm built-in; `pnpm run deploy` runs the script.
+        run: pnpm run deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

.github/workflows/preview-cloudflare.yml

@@ -0,0 +1,95 @@
+name: Preview on Cloudflare Workers
+
+# Uploads each pull request as a new version of the walnut-docs Worker, under
+# the preview alias `pr-<number>`, and comments its URL on the PR:
+# https://pr-<number>-walnut-docs.walnuthq.workers.dev
+#
+# Uploading a version does not deploy it: docs.walnut.dev keeps serving the
+# version deploy-cloudflare.yml deployed from `main`. Each push moves the alias
+# to the new version, so the URL stays the same for the life of the PR.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    # Same as the deploy: the README doesn't change the site.
+    paths-ignore:
+      - "README.md"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+# A new push replaces a preview still being built for the same PR.
+concurrency:
+  group: preview-cloudflare-${{ github.event.number }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    # Pull requests from forks get no secrets.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    env:
+      ALIAS: pr-${{ github.event.number }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Upload a preview version
+        # pnpm forwards flags after the script name; a `--` would reach
+        # wrangler as-is and end its option parsing, dropping the alias.
+        run: pnpm run upload --preview-alias "$ALIAS"
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      - name: Check the preview responds
+        run: |
+          set -euo pipefail
+          url="https://$ALIAS-walnut-docs.walnuthq.workers.dev"
+          # The alias can take a few seconds to point at the new version.
+          for _ in 1 2 3 4 5 6; do
+            if curl -fsS -o /dev/null "$url"; then
+              echo "PREVIEW_URL=$url" >> "$GITHUB_ENV"
+              exit 0
+            fi
+            sleep 5
+          done
+          echo "$url did not respond" >&2
+          exit 1
+
+      - name: Comment the preview URL
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.number }}
+          SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          marker="<!-- preview-cloudflare -->"
+          body="$marker
+          **Preview:** $PREVIEW_URL
+
+          Built from $SHA."
+          # Edit the comment from an earlier run rather than adding another.
+          id=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR/comments" --paginate \
+            --jq ".[] | select(.body | startswith(\"$marker\")) | .id" | head -n1)
+          if [ -n "$id" ]; then
+            gh api -X PATCH "repos/$GITHUB_REPOSITORY/issues/comments/$id" -f body="$body"
+          else
+            gh api "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -f body="$body"
+          fi

.gitignore

@@ -53,3 +53,7 @@ website/i18n/**/*
 
 .netlify
 .tool-versions
+
+# cloudflare
+.wrangler
+.dev.vars*

.node-version

@@ -0,0 +1 @@
+24

README.md

@@ -11,23 +11,31 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 ## Installation
 
 ```
-npm i
+pnpm install
 ```
 
 ## Local Development
 
 ```
-npm run start
+pnpm start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ## Deployment
 
+The site is a static [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) deployment of the `build/` directory, configured in `wrangler.jsonc`. It is served at [docs.walnut.dev](https://docs.walnut.dev/) and at `walnut-docs.walnuthq.workers.dev`.
+
+- Pushing to `main` deploys to production (`.github/workflows/deploy-cloudflare.yml`).
+- Each pull request is uploaded as a preview version, served at `https://pr-<number>-walnut-docs.walnuthq.workers.dev`, without touching production. The URL is commented on the PR (`.github/workflows/preview-cloudflare.yml`).
+
+Both workflows need the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` repository secrets.
+
+To serve the production build locally with the Workers runtime, run `pnpm preview`. To deploy by hand, run `pnpm wrangler login` once, then `pnpm run deploy`.
 
 
 ## Updating search index
 
 The search bar utilizes a local search index with [a plugin ](https://github.com/praveenn77/docusaurus-lunr-search).
 
-Whenever needed, the index can be manually updated by: `npm run build`. To see the changes in local development, use `npm run serve`.
+Whenever needed, the index can be manually updated by: `pnpm build`. To see the changes in local development, use `pnpm serve`.

docusaurus.config.ts

@@ -51,7 +51,6 @@ const config: Config = {
   // projectName: 'walnut-docs', // Usually your repo name.
 
   onBrokenLinks: 'warn',
-  onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -63,6 +62,9 @@ const config: Config = {
 
   markdown: {
     mermaid: true,
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
+    },
   },
   themes: ['@docusaurus/theme-mermaid', 'docusaurus-theme-openapi-docs'],
   plugins: [