feat: gate root docs deploys on releases, serve main under /preview/

.github/workflows/docs.yml

@@ -18,6 +18,12 @@ on:
       - "docs/**"
       - ".github/workflows/docs.yml"
       - ".github/actions/install-hugo/action.yml"
+  # Fires for releases published by hand; releases created by the release
+  # workflow's GITHUB_TOKEN cannot trigger this event, so that workflow
+  # dispatches this one explicitly instead.
+  release:
+    types:
+      - published
   workflow_dispatch:
 
 # Publishing jobs raise this to write on themselves; keep the default read-only.
@@ -33,19 +39,30 @@ concurrency:
 
 jobs:
   # Production: build the site and publish it to the gh-pages branch root.
+  # Runs for a release (the release workflow dispatches it at the tag), a
+  # manual dispatch, or the merge of the release workflow's pin-update PR -
+  # the release tag predates that PR, so without this last deploy the root
+  # site would keep the previous release's wasm url/sha in its examples.
   deploy:
     name: "Deploy docs"
-    if: github.event_name != 'pull_request'
+    if: |
+      github.event_name == 'release' || github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.merged == true &&
+       startsWith(github.event.pull_request.head.ref, 'release/update-readme-'))
     runs-on: ubuntu-latest
     # contents: write lets the deploy action push the built site to gh-pages.
     permissions:
       contents: write
     steps:
+      # For the pin-update merge, build main (the released tag plus the pin
+      # commit) instead of the event's own ref; an empty ref is the default.
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
+          ref: ${{ github.event_name == 'pull_request' && 'main' || '' }}
 
       - name: Install Hugo (extended)
         uses: ./.github/actions/install-hugo
@@ -62,15 +79,60 @@ jobs:
           HUGO_ENVIRONMENT: production
         run: hugo --minify --gc
 
-      # clean-exclude keeps the pr-preview umbrella so a production deploy
-      # never deletes previews of still-open PRs; force: false rebases
-      # instead of force-pushing, tolerating concurrent preview pushes.
+      # clean-exclude keeps the preview trees so a production deploy never
+      # deletes main's preview or previews of still-open PRs; force: false
+      # rebases instead of force-pushing, tolerating concurrent preview pushes.
+      - name: Deploy to gh-pages
+        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        with:
+          branch: gh-pages
+          folder: docs/public
+          clean-exclude: |
+            pr-preview/
+            preview/
+          force: false
+
+  # Main preview: every docs push to main deploys the current state under
+  # /preview/, leaving the root (latest release) untouched.
+  main-preview:
+    name: "Deploy main preview"
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    # contents: write lets the deploy action push the built site to gh-pages.
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install Hugo (extended)
+        uses: ./.github/actions/install-hugo
+
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: docs/go.mod
+
+      # previewNoindex adds a robots noindex meta so the duplicate content
+      # under /preview/ never competes with the root site in search results.
+      - name: Build with Hugo
+        working-directory: docs
+        env:
+          HUGO_ENVIRONMENT: production
+          HUGO_PARAMS_PREVIEWNOINDEX: "true"
+        run: hugo --minify --gc --baseURL "https://sqlc-gen-better-python.rayakame.dev/preview/"
+
+      # target-folder scopes both the deploy and its cleaning to preview/,
+      # so the root site and the pr-preview umbrella are never touched.
       - name: Deploy to gh-pages
         uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
         with:
           branch: gh-pages
           folder: docs/public
-          clean-exclude: pr-preview/
+          target-folder: preview
           force: false
 
   # PR previews: build with a per-PR baseURL and publish under
@@ -110,6 +172,7 @@ jobs:
         working-directory: docs
         env:
           HUGO_ENVIRONMENT: production
+          HUGO_PARAMS_PREVIEWNOINDEX: "true"
           PR_NUMBER: ${{ github.event.number }}
         run: hugo --minify --gc --baseURL "https://sqlc-gen-better-python.rayakame.dev/pr-preview/pr-${PR_NUMBER}/"
 
@@ -119,3 +182,5 @@ jobs:
           source-dir: docs/public
           preview-branch: gh-pages
           umbrella-dir: pr-preview
+          # The PR comment's link defaults to <owner>.github.io/<repo>.
+          pages-base-url: sqlc-gen-better-python.rayakame.dev

.github/workflows/release.yml

@@ -104,3 +104,12 @@ jobs:
           tag_name: "refs/tags/${{ steps.latest.outputs.output }}"
           body_path: release_body.md
           files: ./sqlc-gen-better-python.wasm
+
+      # Releases created with GITHUB_TOKEN never fire the docs workflow's
+      # release trigger (workflow_dispatch is the documented exception), so
+      # dispatch the root docs deploy explicitly, pinned to the release tag.
+      - name: Deploy docs for the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ steps.latest.outputs.output }}
+        run: gh workflow run docs.yml --ref "$RELEASE_TAG"

docs/layouts/_partials/custom/head-end.html

@@ -0,0 +1,6 @@
+{{/* Preview deploys (main's /preview/ and the PR previews) set the
+previewNoindex param so search engines never index duplicate content;
+crawlers honor the most restrictive robots meta on the page. */}}
+{{- if site.Params.previewNoindex -}}
+<meta name="robots" content="noindex, nofollow">
+{{- end -}}