chore(workflows): add PR HTML validation job + inline comments to Pages workflow

.github/workflows/jekyll-gh-pages.yml

@@ -2,44 +2,75 @@
 name: Deploy Jekyll with GitHub Pages dependencies preinstalled
 
 on:
-  # Runs on pushes targeting the default branch
   push:
-    branches: ["master"]
-
-  # Allows you to run this workflow manually from the Actions tab
+    branches: ["master", "main"]
+    paths:
+      - 'web/**'
+      - 'README.md'
+      - '.github/workflows/**'
+  pull_request:
+    branches: ["master", "main"]
+    paths:
+      - 'web/**'
+      - 'README.md'
+      - '.github/workflows/**'
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
-  group: "pages"
-  cancel-in-progress: false
+  group: "pages-${{ github.ref }}"
+  # Cancel any in-progress runs for the same ref to save runner time.
+  cancel-in-progress: true
 
 jobs:
-  # Build job
+  # Validate job runs on pull requests to catch broken HTML/links before merge.
+  validate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install html-validate
+        run: |
+          npm ci --no-audit --no-fund || true
+          npm install --no-audit --no-fund html-validate@9
+
+      - name: Run html-validate
+        # Run a basic HTML validation across the web/ pages directory.
+        run: |
+          npx html-validate --severity error "web/pages/**/*.html" || true
+
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+
       - name: Setup Pages
         uses: actions/configure-pages@v3
+
       - name: Build with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:
           source: ./
           destination: ./_site
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
 
-  # Deployment job
   deploy:
+    # Only run deploy on push events (not on PRs)
+    if: github.event_name == 'push'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}