build.yml

name: Build & Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

# Allow the workflow to publish to GitHub Pages via the deploy-pages action.
permissions:
  contents: read
  pages: write
  id-token: write

# Never let two deploys race; queue them instead of cancelling, so a push is
# not silently dropped from production.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          coverage: none

      - name: Validate composer.json and composer.lock
        run: composer validate --strict

      - name: Get Composer cache directory
        id: composer-cache
        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer-

      # The realtime compiler is only needed for `hyde serve`, so the production
      # build does not install dev dependencies.
      - name: Install dependencies
        run: composer install --no-dev --prefer-dist --no-progress --no-interaction

      # Torchlight highlights code blocks through its API at build time. Without
      # the token the build still succeeds, but every code block ships as plain
      # text, so the verification step below treats that as a failure.
      - name: Build the site
        run: php hyde build --no-interaction
        env:
          TORCHLIGHT_TOKEN: ${{ secrets.TORCHLIGHT_TOKEN }}

      # A failing post-build task does not fail `hyde build`, because
      # runPostBuildTasks() discards task exit codes. The redirects that keep the
      # pre-migration URLs alive are generated by such a task, so assert them here
      # rather than trusting the build to have reported a problem.
      - name: Verify the build output
        run: |
          set -euo pipefail

          for file in \
            _site/index.html \
            _site/docs/index.html \
            _site/docs/installation.html \
            _site/docs/architecture.html \
            _site/docs/search.html
          do
            test -f "$file" || { echo "::error::missing expected page $file"; exit 1; }
          done

          # Both spellings of a pre-migration URL, since GitHub Pages serves
          # /foo from foo.html but /foo/ only from foo/index.html.
          for file in \
            _site/docs/usage/installation.html \
            _site/docs/usage/installation/index.html \
            _site/docs/middleware/attributes.html \
            _site/docs/middleware/attributes/index.html
          do
            test -f "$file" || { echo "::error::missing expected redirect $file"; exit 1; }
          done

          redirects=$(find _site/docs \
            \( -path '*/usage/*' -o -path '*/guides/*' \
               -o -path '*/middleware/*' -o -path '*/advanced/*' \) \
            -name '*.html' | wc -l | tr -d ' ')
          if [ "$redirects" -ne 42 ]; then
            echo "::error::expected 42 redirect pages, found $redirects"
            exit 1
          fi

          # A redirect must never have replaced a real page with a self-redirect.
          grep -q 'sidebar-navigation' _site/docs/architecture.html \
            || { echo "::error::docs/architecture.html is not a real page"; exit 1; }

          # Code blocks must come back highlighted. Torchlight failing open, whether
          # from a missing secret or an API outage, is otherwise invisible.
          # Assert the user-visible outcome, not a class name: Torchlight marks the
          # block with data-lang and colours each token with an inline style. Note
          # it emits single-quoted attributes, so do not grep for class="torchlight".
          colours=$(grep -o 'style="color:' _site/docs/setup.html | wc -l | tr -d ' ')
          if ! grep -q 'data-lang=' _site/docs/setup.html || [ "$colours" -lt 10 ]; then
            echo "::error::code blocks are not highlighted (found $colours coloured tokens); is the TORCHLIGHT_TOKEN secret set?"
            exit 1
          fi

          # The copy-to-clipboard script must be published and referenced.
          test -f _site/media/copy-code.js \
            || { echo "::error::missing _site/media/copy-code.js"; exit 1; }
          grep -q 'media/copy-code.js' _site/docs/setup.html \
            || { echo "::error::copy-code.js is not referenced by the pages"; exit 1; }

          # Kramdown attribute lists and Liquid tags must not survive into output.
          if grep -rlE '\{%|\{:' _site --include='*.html' | grep -qv 'search'; then
            echo "::error::unrendered Kramdown or Liquid syntax found in output"
            exit 1
          fi

      # GitHub Pages takes the custom domain from the repository settings, but the
      # CNAME file is kept as the in-repo record of it and costs nothing to ship.
      - name: Add CNAME
        run: cp CNAME _site/CNAME

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4