build-docs.yml

name: Documentation Build

on:
  pull_request:
    branches: [ main ]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  changes:
    name: Detect Documentation Changes
    runs-on: ubuntu-latest
    outputs:
      docs: ${{ steps.filter.outputs.docs }}
    steps:
      # Step 1: Checkout code
      - name: Checkout Code
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
        with:
          fetch-depth: 0

      # Step 2: Check if documentation files changed
      - name: Check for documentation changes
        id: filter
        run: |
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- \
            'docs/' \
            '.github/workflows/build-docs.yml')
          if [ -n "$CHANGED" ]; then
            echo "docs=true" >> "$GITHUB_OUTPUT"
          else
            echo "docs=false" >> "$GITHUB_OUTPUT"
          fi

  build:
    name: Build Documentation
    needs: changes
    if: needs.changes.outputs.docs == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6

      - name: Setup Node.js
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: 22
          cache: npm
          cache-dependency-path: docs/package-lock.json

      - name: Enforce pinned npm dependencies
        uses: miragon/pin-npm-dependencies@58fe24377aef66748a1444ff69ab05e3f938a798 # v1
        with:
          root-path: docs

      - name: Install Dependencies
        run: npm ci
        working-directory: docs

      - name: Build Documentation
        run: npm run build
        working-directory: docs