docs: add preview feature functionality with GitHub workflows

.github/workflows/docs-preview-check.yaml

@@ -0,0 +1,107 @@
+# This workflow checks that PRs modifying docs include a preview link in the PR description.
+# It enforces documentation PR best practices for PipeCD.
+
+name: Docs Preview Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+    paths:
+      - 'docs/**'
+      - '*.md'
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check-preview-link:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Check for Preview Link in PR Description
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          BRANCH: ${{ github.head_ref }}
+        run: |
+          set -e
+
+          # Get PR body
+          BODY=$(gh pr view "$PR_NUMBER" --json body -q '.body')
+
+          # Get owner and repo name for the head repository (fork or main)
+          OWNER=$(gh pr view "$PR_NUMBER" --json headRepositoryOwner -q '.headRepositoryOwner.login')
+          REPO_NAME=$(gh pr view "$PR_NUMBER" --json headRepository -q '.headRepository.name')
+
+          # Expected GitHub Pages URL format
+          GITHUB_PAGES_URL="https://${OWNER}.github.io/${REPO_NAME}/${BRANCH}"
+
+          # Check if branch starts with 'docs-'
+          DOC_BRANCH_REGEX='^docs-'
+
+          # Color codes for output
+          GREEN=$'\033[0;32m'
+          RED=$'\033[0;31m'
+          YELLOW=$'\033[1;33m'
+          NC=$'\033[0m' # No Color
+
+          echo "Checking PR #$PR_NUMBER for docs preview link..."
+          echo "Branch: $BRANCH"
+          echo "Expected preview base URL: $GITHUB_PAGES_URL"
+          echo ""
+
+          # Check if the PR description contains a preview link
+          if ! PREVIEW_LINE=$(echo "$BODY" | grep -iE '^[[:space:]]*[Pp]review.*https?://' || true); then
+            # Branch doesn't start with 'docs-' - provide guidance
+            if [[ ! "$BRANCH" =~ $DOC_BRANCH_REGEX ]]; then
+              echo "${YELLOW}[INFO] This branch does not start with 'docs-'. For automatic preview deployment:${NC}"
+              echo ""
+              echo "1. Create a branch with 'docs-' prefix (e.g., docs-update-readme)"
+              echo "2. Push your changes to trigger the preview deployment"
+              echo "3. Add the preview link to your PR description"
+              echo ""
+              echo "Example PR description format:"
+              echo "  Preview: https://YOUR_USERNAME.github.io/pipecd/docs-your-branch/"
+              echo ""
+              echo "${YELLOW}Skipping check since branch doesn't follow docs- convention.${NC}"
+              exit 0
+            fi
+
+            echo "${RED}[ERROR] Docs PR: No preview link found in PR description.${NC}"
+            echo ""
+            echo "Please include a line starting with 'Preview' and a valid GitHub Pages URL."
+            echo ""
+            echo "Steps to add a preview:"
+            echo "1. Ensure your branch name starts with 'docs-'"
+            echo "2. Push your changes to trigger the preview deployment workflow"
+            echo "3. Add the following to your PR description:"
+            echo ""
+            echo "   Preview: $GITHUB_PAGES_URL/"
+            echo ""
+            exit 1
+          else
+            # Found a preview line, check if it matches expected format
+            if [[ "$PREVIEW_LINE" == *"$GITHUB_PAGES_URL"* ]]; then
+              if [[ "$BRANCH" =~ $DOC_BRANCH_REGEX ]]; then
+                echo "${GREEN}[OK] Docs PR: Branch starts with 'docs-' and preview link matches expected format.${NC}"
+                echo "Preview URL found: $GITHUB_PAGES_URL/"
+              else
+                echo "${YELLOW}[WARN] Docs PR: Preview link found but branch does not start with 'docs-'.${NC}"
+                echo "Consider renaming your branch to enable automatic preview deployment."
+              fi
+            else
+              PREVIEW_URL=$(echo "$PREVIEW_LINE" | grep -oE 'https?://[^ )"'"'"']*' || true)
+              echo "${YELLOW}[WARN] Docs PR: Preview link found but doesn't match expected GitHub Pages URL.${NC}"
+              echo ""
+              echo "Expected: $GITHUB_PAGES_URL/"
+              echo "Found:    $PREVIEW_URL"
+              echo ""
+              echo "This might be fine if you're using a different preview method."
+            fi
+          fi
+
+          echo ""
+          echo "Check completed successfully."

.github/workflows/docs-preview-cleanup.yaml

@@ -0,0 +1,39 @@
+# This workflow cleans up docs preview deployments when branches are deleted.
+# It removes the preview directory from gh-pages when a 'docs-*' branch is deleted.
+
+name: Docs Preview Cleanup
+
+on:
+  delete:
+
+permissions:
+  contents: write
+
+jobs:
+  cleanup-preview:
+    runs-on: ubuntu-24.04
+    # Only run for branch deletions
+    if: github.event.ref_type == 'branch' && startsWith(github.event.ref, 'docs-')
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: gh-pages
+          fetch-depth: 0
+
+      - name: Remove preview directory
+        run: |
+          BRANCH_NAME="${{ github.event.ref }}"
+          echo "Cleaning up preview for deleted branch: $BRANCH_NAME"
+
+          if [ -d "$BRANCH_NAME" ]; then
+            rm -rf "$BRANCH_NAME"
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add -A
+            git commit -m "chore: remove docs preview for deleted branch '$BRANCH_NAME'" || echo "No changes to commit"
+            git push
+            echo "✅ Successfully removed preview directory: $BRANCH_NAME"
+          else
+            echo "ℹ️ Preview directory '$BRANCH_NAME' does not exist. Nothing to clean up."
+          fi

.github/workflows/docs-preview-deploy.yaml

@@ -0,0 +1,82 @@
+# This workflow builds and deploys docs preview to GitHub Pages for branches prefixed with 'docs-'.
+# Each branch gets its own subdirectory at https://<owner>.github.io/pipecd/<branch-name>/
+
+name: Docs Preview Deploy
+
+on:
+  push:
+    branches:
+      - 'docs-*'
+    paths:
+      - 'docs/**'
+      - '*.md'
+      - '.github/workflows/docs-preview-deploy.yaml'
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Prevent multiple deployments to the same branch from running simultaneously
+concurrency:
+  group: docs-preview-${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
+        with:
+          hugo-version: '0.148.2'
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '14'
+
+      - name: Get branch name
+        id: branch
+        run: echo "name=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+
+      - name: Get repository owner
+        id: repo
+        run: |
+          echo "owner=${GITHUB_REPOSITORY_OWNER}" >> $GITHUB_OUTPUT
+          echo "name=$(echo '${{ github.repository }}' | cut -d'/' -f2)" >> $GITHUB_OUTPUT
+
+      - name: Build docs for preview
+        run: |
+          cd docs
+          npm install autoprefixer
+          npm install postcss-cli
+          # Build with custom baseURL for the preview deployment
+          env HUGO_ENV="production" \
+              RELEASE="$(grep '^tag:' ../RELEASE | awk '{print $2}')" \
+              hugo --baseURL "https://${{ steps.repo.outputs.owner }}.github.io/${{ steps.repo.outputs.name }}/${{ steps.branch.outputs.name }}/"
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/public
+          destination_dir: ${{ steps.branch.outputs.name }}
+          keep_files: true  # Keep other preview directories
+
+      - name: Output preview URL
+        run: |
+          echo "## 📚 Docs Preview Deployed!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Preview URL: https://${{ steps.repo.outputs.owner }}.github.io/${{ steps.repo.outputs.name }}/${{ steps.branch.outputs.name }}/" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Add this to your PR description:" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "Preview: https://${{ steps.repo.outputs.owner }}.github.io/${{ steps.repo.outputs.name }}/${{ steps.branch.outputs.name }}/" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY