From c5a8641c908ece9c72f69367c894281f7b865d5d Mon Sep 17 00:00:00 2001 From: Christopher Date: Fri, 31 Jul 2026 01:20:23 +0200 Subject: [PATCH 1/4] feat: gate root docs deploys on releases, serve main under /preview/ The root site now deploys only from a release (the release workflow dispatches the docs workflow at the tag, since GITHUB_TOKEN-created releases cannot fire the release trigger) or a manual dispatch. Docs pushes to main deploy to /preview/ instead, and both preview flavors emit a robots noindex meta so they never compete with the root site in search results. --- .github/workflows/docs.yml | 64 +++++++++++++++++++-- .github/workflows/release.yml | 8 +++ docs/layouts/_partials/custom/head-end.html | 6 ++ 3 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 docs/layouts/_partials/custom/head-end.html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 75e7dc4d..12529298 100644 --- a/.github/workflows/docs.yml +++ b/.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,9 +39,11 @@ concurrency: jobs: # Production: build the site and publish it to the gh-pages branch root. + # Runs only for a release (the release workflow dispatches it at the tag) + # or a manual dispatch, so the root site always matches the latest release. deploy: name: "Deploy docs" - if: github.event_name != 'pull_request' + if: github.event_name == 'release' || github.event_name == 'workflow_dispatch' runs-on: ubuntu-latest # contents: write lets the deploy action push the built site to gh-pages. permissions: @@ -62,15 +70,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 +163,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}/" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d59b3f3a..fe1c08f8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -104,3 +104,11 @@ 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 }} + run: gh workflow run docs.yml --ref "${{ steps.latest.outputs.output }}" diff --git a/docs/layouts/_partials/custom/head-end.html b/docs/layouts/_partials/custom/head-end.html new file mode 100644 index 00000000..ec3ce5c5 --- /dev/null +++ b/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 -}} + +{{- end -}} From 3aa10a70baa6fa9625df428b455e0afb25336e8d Mon Sep 17 00:00:00 2001 From: Christopher Date: Fri, 31 Jul 2026 01:25:17 +0200 Subject: [PATCH 2/4] fix: point the PR preview comment at the custom domain --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 12529298..3ac22058 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -173,3 +173,5 @@ jobs: source-dir: docs/public preview-branch: gh-pages umbrella-dir: pr-preview + # The PR comment's link defaults to .github.io/. + pages-base-url: sqlc-gen-better-python.rayakame.dev From 0fa22699ca12794fcecfad90521b0e865ca82555 Mon Sep 17 00:00:00 2001 From: Christopher Date: Fri, 31 Jul 2026 01:29:44 +0200 Subject: [PATCH 3/4] fix: pass the release tag to the docs dispatch via an env var --- .github/workflows/release.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index fe1c08f8..41675b7f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -111,4 +111,5 @@ jobs: - name: Deploy docs for the release env: GH_TOKEN: ${{ github.token }} - run: gh workflow run docs.yml --ref "${{ steps.latest.outputs.output }}" + RELEASE_TAG: ${{ steps.latest.outputs.output }} + run: gh workflow run docs.yml --ref "$RELEASE_TAG" From 6b8345ab2ef7c4cac509245302a19482065df3f4 Mon Sep 17 00:00:00 2001 From: Christopher Date: Fri, 31 Jul 2026 01:40:37 +0200 Subject: [PATCH 4/4] fix: redeploy the docs root when the release pin PR merges The release tag predates the pin-update PR, so the root deploy at the tag still shows the previous release's wasm url/sha in its examples. Deploy again from main when the release/update-readme-* branch merges; main is then exactly the tag plus the pin commit. --- .github/workflows/docs.yml | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3ac22058..a5c7ede0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -39,21 +39,30 @@ concurrency: jobs: # Production: build the site and publish it to the gh-pages branch root. - # Runs only for a release (the release workflow dispatches it at the tag) - # or a manual dispatch, so the root site always matches the latest release. + # 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 == 'release' || github.event_name == 'workflow_dispatch' + 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