Merge branch 'master' into gw/raft-auth-fixes

.github/workflows/pr-preview.yml

@@ -35,12 +35,45 @@ jobs:
             echo "should-run=true" >> $GITHUB_OUTPUT
           fi
 
-  # Build and deploy preview
-  preview:
+  # Notify fork PRs that preview is not available
+  fork-notice:
     needs: check-draft
     if: |
       needs.check-draft.outputs.should-run == 'true' &&
-      github.event.action != 'closed'
+      github.event.action != 'closed' &&
+      github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post fork notice comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            const marker = '<!-- pr-preview-fork-notice -->';
+            const existing = comments.find(c => c.body.includes(marker));
+
+            if (!existing) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: `${marker}\n## 📝 PR Preview Not Available\n\nPR previews are not available for pull requests from forks due to GitHub Actions security restrictions.\n\nTo preview your changes locally, run:\n\`\`\`bash\nnpx hugo server\n\`\`\`\n\nOnce merged, your changes will be visible on the production site.`
+              });
+            }
+
+  # Build and deploy preview
+  preview:
+    needs: check-draft
+    # Skip fork PRs - GITHUB_TOKEN doesn't have write access to push to gh-pages
+    if: |
+      needs.check-draft.outputs.should-run == 'true' &&
+      github.event.action != 'closed' &&
+      github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

DOCS-DEPLOYING.md

@@ -221,6 +221,34 @@ The Cypress tests validate:
 
 See [DOCS-TESTING.md](DOCS-TESTING.md) for comprehensive testing documentation.
 
+### PR Preview
+
+Generates previews for docs-v2 pull requests for manual validation in GitHub using the PR Preview Action.
+
+#### Workflow Files
+
+| File                                           | Purpose                               |
+| ---------------------------------------------- | ------------------------------------- |
+| `.github/scripts/parse-pr-urls.js`             | Extract docs URLs from PR description |
+| `.github/scripts/detect-preview-pages.js`      | Determine which pages to preview      |
+| `.github/scripts/prepare-preview-files.js`     | Stage files for selective deployment  |
+| `.github/scripts/preview-comment.js`           | Manage sticky PR comments             |
+| `.github/workflows/pr-preview.yml`             | Main preview workflow                 |
+| `.github/workflows/cleanup-stale-previews.yml` | Weekly orphan cleanup                 |
+| `.github/PREVIEW_SETUP.md`                     | Setup documentation                   |
+
+#### Key Design Decisions
+
+1. **Selective deployment** - Only changed pages deployed (not full 529MB site)
+2. **Reuse existing infrastructure** - Uses `content-utils.js` for change detection
+3. **GitHub Pages** - Deploys to `gh-pages` branch under `pr-preview/pr-{number}/`
+4. **Security hardening** - XSS protection, path traversal prevention, input validation
+5. **50-page limit** - Prevents storage bloat on large PRs
+
+#### Related links
+
+- **Deploy PR Preview action:** <https://github.com/rossjrw/pr-preview-action>
+
 ## Troubleshooting
 
 ### s3deploy Not Found

layouts/partials/sidebar.html

@@ -1,8 +1,10 @@
 {{ $currentPage := . }}
 {{ $productPathData := findRE "[^/]+.*?" .RelPermalink }}
-{{ $product := index $productPathData 0 }}
+{{/* Support deployments (such as CI tools) with subdirectory baseURL */}}
+{{ $pathOffset := .Site.Params.prPreviewPathOffset | default 0 }}
+{{ $product := index $productPathData (add $pathOffset 0) }}
 {{ $productName := (index .Site.Data.products $product).name }}
-{{ $currentVersion := index $productPathData 1 }}
+{{ $currentVersion := index $productPathData (add $pathOffset 1) }}
 
 <!-- Menu Key -->
 {{ .Scratch.Set "menuKey" "menu"}}

layouts/shortcodes/product-name.html

@@ -1,5 +1,7 @@
 {{- $productPathData := findRE "[^/]+.*?" .Page.RelPermalink -}}
-{{- $currentProduct := index $productPathData 1 -}}
+{{- /* Support deployments (such as CI tools) with subdirectory baseURL */ -}}
+{{- $pathOffset := .Site.Params.prPreviewPathOffset | default 0 -}}
+{{- $currentProduct := index $productPathData (add $pathOffset 1) -}}
 {{- $length := .Get 0 | default "long" -}}
 {{- $omit := .Get "omit" | default "" -}}
 {{- $scratch := newScratch -}}