docs.yml

name: Docs

# The docs site is served from GitHub Pages at https://reactunity.github.io/,
# and that URL comes from the *repository name* -- only ReactUnity/<name>.github.io
# can serve it. So the source lives here and the built output is pushed to the
# gh-pages branch of ReactUnity/reactunity.github.io, which becomes a deploy target only.
on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

concurrency:
  group: docs
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    # Hoisted to job level so the steps below can branch on whether the token
    # exists. The `secrets` context is NOT available in a step-level `if`
    # (allowed there: github, needs, strategy, matrix, job, runner, env, vars,
    # steps, inputs) but `env` is, and `jobs.<id>.env` may read secrets. This is
    # the documented way to make a step conditional on a secret being set.
    env:
      DOCS_DEPLOY_TOKEN: ${{ secrets.DOCS_DEPLOY_TOKEN }}
    steps:
      # persist-credentials: false is what makes the cross-repo deploy below work.
      # checkout@v7 stores its GITHUB_TOKEN as an `AUTHORIZATION: basic` header in a
      # temp config included via `includeIf.gitdir:` -- covering `.git/worktrees/*`,
      # which is where github-pages-deploy-action does its work. That header outranks
      # the token in the remote URL, so the push went out as github-actions[bot] and
      # was denied 403; the action's cleanup only clears the pre-v7 `--local` location.
      # Nothing here needs git credentials after the checkout.
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version-file: .node-version
          cache: pnpm
      - run: pnpm install --frozen-lockfile

      # Always built, even when the deploy is skipped -- that keeps this workflow
      # useful as a check that the docs still compile.
      #
      # This used to run on a second, downgraded `setup-node@v6` pinned to Node 22: the
      # site was a Next 12.3 app, and Next 12 bundles jsonwebtoken, which reaches for
      # `require('buffer').SlowBuffer` -- removed in Node 24. It is an Astro site now and
      # runs on the Node that .node-version pins, like everything else in the repo.
      - name: Build
        working-directory: docs
        env:
          PUBLIC_GA_TRACKING_ID: ${{ secrets.ANALYTICS_ID }}
        run: pnpm build

      # clean-exclude is load-bearing. Two sets of Unity WebGL artifacts live permanently
      # on the target branch under Unity/. Both are built by hand from kitchen-sink's
      # WebInjectable and Previewer build profiles and uploaded there -- see
      # kitchen-sink/README.md; nothing in CI produces them, which has no WebGL module:
      #
      #   Unity/injectable/Build/WebInjectable.*  (~26 MB) - the players embedded in
      #     the docs examples. docs/src/components/unity/instance.tsx loads
      #     /Unity/<sample>/Build/WebInjectable.{wasm,data,framework.js}.unityweb plus
      #     an uncompressed .loader.js, and defaultUnityInstanceName makes <sample>
      #     `injectable`. Same-origin with the site, so no CORS involved.
      #   Unity/previewer/<version>/Build/Previewer.*  (~26 MB) - served to the
      #     @reactunity/scripts dev server, which is cross-origin. That works because
      #     GitHub Pages sends Access-Control-Allow-Origin: *. It cannot be told to send
      #     Content-Encoding, which is why the three big files are .unityweb -- gzip the
      #     loader inflates itself. See packages/scripts/config/public/index.html.
      #
      # This deploy runs with clean: true, so anything outside Unity/** is replaced on
      # every run. Dropping the exclude would delete ~52 MB that only exists there and
      # would have to be rebuilt in Unity by hand.
      - name: Deploy to ReactUnity/reactunity.github.io@gh-pages
        if: env.DOCS_DEPLOY_TOKEN != ''
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: docs/dist
          branch: gh-pages
          repository-name: ReactUnity/reactunity.github.io
          token: ${{ secrets.DOCS_DEPLOY_TOKEN }}
          clean: true
          clean-exclude: |
            Unity/**

      # Never fail silently: without this the run is green and indistinguishable
      # from a successful deploy.
      - name: Deploy skipped
        if: env.DOCS_DEPLOY_TOKEN == ''
        run: |
          echo "::warning title=Docs deploy skipped::DOCS_DEPLOY_TOKEN is not set, so the built site was not pushed to ReactUnity/reactunity.github.io. The docs build itself passed."
          {
            echo "### Docs deploy skipped"
            echo
            echo "The site built successfully but was **not deployed**: the"
            echo "**DOCS_DEPLOY_TOKEN** secret is not set."
            echo
            echo "Add a token with write access to **ReactUnity/reactunity.github.io** to enable"
            echo "deploys. Until then this workflow only checks that the docs compile,"
            echo "and the built site is attached as the *docs-site* artifact."
          } >> "$GITHUB_STEP_SUMMARY"

      # The built site is kept as an artifact either way, so a skipped deploy can
      # still be inspected (and uploaded by hand if needed). `!cancelled()` is what
      # makes "either way" true: a *failed* deploy would otherwise skip this step,
      # throwing away the one copy of the build that could be pushed by hand.
      - name: Upload built site
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@v7
        with:
          name: docs-site
          path: docs/dist
          retention-days: 7