pages.yml

# This workflow builds and deploys the app and optional documentation to
# GitHub Pages. It is intentionally guarded by repository variables so forks
# do not publish pages unless explicitly enabled.
#
# Triggers:

# - `push` to `main`: a deployment is possible but only runs when
#   `ENABLE_GH_PAGES` repository variable is set to `true`.
# - `workflow_dispatch`: manual trigger with an `enable_docs` input to build
#   documentation on demand.
#
# Key points for contributors:

# - `ENABLE_GH_PAGES` (repo variable) controls automatic deployments from CI.
# - `ENABLE_JSDOC_BUILD` (repo variable) or the `enable_docs` input controls
#   whether the documentation (`docs-html`) is built and published.
# - The job creates a `gh-pages/` directory containing the app, docs, and a
#   landing page, which is uploaded using `actions/upload-pages-artifact`.

# Note: Publishing with `actions/deploy-pages` uploads an artifact and then
# GitHub runs its own Pages publish pipeline. That will appear as a separate
# "pages build and deployment" run in the Actions UI in addition to this
# workflow run. This is expected behavior.

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      enable_docs:
        description: 'Build and deploy API documentation'
        required: false
        type: boolean
        default: false

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  log-context:
    name: Log workflow context
    runs-on: ubuntu-latest
    # Run only when this workflow would otherwise run (same guard as `build`).
    if: vars.ENABLE_GH_PAGES == 'true' || github.event_name == 'workflow_dispatch'
    steps:
      - uses: actions/checkout@v4

      - name: Debug Info
        uses: ./.github/actions/debug-info
        with:
          show-env: 'false'

      - name: Log workflow context
        run: |
          echo "[Pages][log-context] Triggered by $GITHUB_EVENT_NAME on ref $GITHUB_REF for $GITHUB_REPOSITORY"
          echo "[Pages][log-context] ENABLE_GH_PAGES=${{ vars.ENABLE_GH_PAGES }}"

  build:
    name: Build
    runs-on: ubuntu-latest
    # Only run if ENABLE_GH_PAGES is explicitly set to 'true' OR workflow_dispatch is used
    # For forks: Set this in Settings → Secrets and variables → Actions → Variables
    needs: log-context
    if: vars.ENABLE_GH_PAGES == 'true' || github.event_name == 'workflow_dispatch'
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Cache Vite build cache
        # Cache Vite build artifacts to speed up the `npm run build` step for
        # the Pages job. This is separate from the node/npm cache provided by
        # `actions/setup-node` and targets Vite's local cache directories.
        uses: actions/cache@v4
        with:
          path: |
            node_modules/.vite
            .vite
          # Include lockfile and vite config in key so cache invalidates when
          # dependencies or build configuration change.
          key: ${{ runner.os }}-vite-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/vite.config.ts') }}
          restore-keys: |
            ${{ runner.os }}-vite-

      - name: Install dependencies
        run: npm ci

      - name: Build app
        # `VITE_BASE_PATH` sets the app base used by Vite so the app can be
        # hosted under `/modern-react-template/app/` on GitHub Pages.
        env:
          VITE_BASE_PATH: /modern-react-template/app/
        run: npm run build

      - name: Generate documentation (optional)
        # Builds HTML docs when `ENABLE_JSDOC_BUILD` repo var is true or when
        # the manual `enable_docs` input is provided at dispatch.
        if: vars.ENABLE_JSDOC_BUILD == 'true' || inputs.enable_docs == true
        run: npm run docs:html

      - name: Build GitHub Pages landing (optional)
        # Some repositories produce a separate landing page build; this step
        # runs only when the `ENABLE_GH_PAGES` variable is enabled.
        if: ${{ vars.ENABLE_GH_PAGES == 'true' }}
        run: npm run build:gh-pages

      - name: Create GitHub Pages structure
        # Prepare the `gh-pages/` directory structure that will be uploaded.
        run: |
          mkdir -p gh-pages
          # Copy the main app
          cp -r dist gh-pages/app
          # Copy documentation (if built)
          if [ -d docs-html ]; then
            cp -r docs-html gh-pages/docs
          fi
          # Copy the landing page
          if [ -f dist/gh-pages-index.html ]; then
            cp dist/gh-pages-index.html gh-pages/index.html
          else
            cp public/gh-pages-index.html gh-pages/index.html
          fi

      - name: Upload artifact
        # Upload the `gh-pages/` folder as the Pages artifact. The separate
        # `deploy` job consumes this artifact to publish the site.
        uses: actions/upload-pages-artifact@v3
        with:
          path: gh-pages

  deploy:
    name: Deploy to GitHub Pages
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        # `actions/deploy-pages` reads the uploaded artifact and publishes it to
        # the repository's GitHub Pages site. Check the Actions run logs and the
        # Pages settings in the repo to verify the published URL.
        uses: actions/deploy-pages@v4