build-docs.yml

name: Build and Deploy Docs


on:
  push:
    branches: [main]

env:
  ACTIONS_STEP_DEBUG: true

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

jobs:
  build-and-deploy-docs:
    # Skip the docs deploy on automated version-bump commits. These were previously
    # suppressed by the "[skip ci]" in the bump-commit message, which was removed so the
    # release workflow's tag trigger can fire (see publish-version.mjs). A version bump
    # only changes version numbers, so there is nothing new to deploy.
    if: ${{ !startsWith(github.event.head_commit.message, 'chore(version):') }}
    timeout-minutes: 60
    runs-on: ubuntu-latest
    # Need permissions to read actions and pull requests
    permissions:
      actions: read
      contents: read
      pull-requests: read
    steps:
      - uses: actions/checkout@v6.0.3
      - uses: pnpm/action-setup@v6.0.8
      - uses: actions/setup-node@v6.4.0
        with:
          node-version: '24.15.0'
          cache: 'pnpm'

      - name: Install root dependencies
        run: pnpm install --frozen-lockfile

      # Removed Playwright tests and coverage generation steps

      - name: Find PR and associated workflow run
        id: find_pr_run
        env:
          GH_TOKEN: ${{ github.token }}
          MERGE_COMMIT_SHA: ${{ github.sha }}
        run: |
          # Coverage is a best-effort enhancement bundled into the docs site. A push
          # to main may have no associated PR (e.g. a direct push or a squash where
          # the search misses) or no completed playwright run carrying the coverage
          # artifact. None of that should block the docs deploy, so this step never
          # fails - it only reports whether coverage is available via an output.
          COVERAGE_AVAILABLE=false

          # Find the PR associated with the merge commit SHA.
          PR_DATA=$(gh pr list --state merged --search "$MERGE_COMMIT_SHA" --json number,headRefOid --jq '.[0]' 2>/dev/null || echo "")
          if [ -z "$PR_DATA" ] || [ "$PR_DATA" = "null" ]; then
            echo "::warning::No merged PR found for commit $MERGE_COMMIT_SHA - skipping coverage, continuing deploy."
          else
            PR_HEAD_SHA=$(echo "$PR_DATA" | jq -r '.headRefOid')
            PR_NUMBER=$(echo "$PR_DATA" | jq -r '.number')
            echo "Found PR #$PR_NUMBER (head SHA: $PR_HEAD_SHA)"

            # Find the latest playwright.yml run on the PR head commit (carries the
            # coverage-report-pr artifact).
            RUN_ID=$(gh run list --workflow playwright.yml --commit "$PR_HEAD_SHA" --event pull_request --json databaseId --jq '.[0].databaseId' 2>/dev/null || echo "")
            if [ -z "$RUN_ID" ] || [ "$RUN_ID" = "null" ]; then
              echo "::warning::No playwright.yml run found for PR #$PR_NUMBER (head SHA: $PR_HEAD_SHA) - skipping coverage, continuing deploy."
            else
              echo "Found playwright run ID: $RUN_ID"
              echo "run_id=$RUN_ID" >> "$GITHUB_OUTPUT"
              COVERAGE_AVAILABLE=true
            fi
          fi

          echo "coverage_available=$COVERAGE_AVAILABLE" >> "$GITHUB_OUTPUT"

      - name: Download coverage artifact from PR run
        if: steps.find_pr_run.outputs.coverage_available == 'true'
        id: download_coverage
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          mkdir -p ./coverage-artifact
          # Treat a missing/failed artifact as non-fatal: warn and skip coverage
          # rather than failing the deploy.
          if gh run download ${{ steps.find_pr_run.outputs.run_id }} -n coverage-report-pr --dir ./coverage-artifact && [ -f ./coverage-artifact/base.css ]; then
            echo "Coverage artifact downloaded successfully."
            echo "downloaded=true" >> "$GITHUB_OUTPUT"
          else
            echo "::warning::Could not download artifact 'coverage-report-pr' from run ${{ steps.find_pr_run.outputs.run_id }} - skipping coverage, continuing deploy."
            echo "downloaded=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Install docs dependencies
        run: pnpm install --frozen-lockfile

      - name: Copy coverage to docs static directory
        if: steps.download_coverage.outputs.downloaded == 'true'
        run: |
          # Copy files from the downloaded artifact directory
          mkdir -p packages/docs/static/coverage
          cp -r ./coverage-artifact/* packages/docs/static/coverage/
          # Copy specific asset files from the downloaded artifact root to static root.
          # Tolerate a missing asset so a partial artifact doesn't fail the deploy.
          for f in base.css block-navigation.js prettify.css prettify.js favicon.png sort-arrow-sprite.png sorter.js; do
            cp "./coverage-artifact/$f" packages/docs/static/ 2>/dev/null || echo "::warning::coverage asset '$f' not found in artifact"
          done

      - name: Build docs
        run: pnpm --filter docs run build:docs
        # This runs
        # 1. prepare-markdown-files.js - which copies markdown files to /docs/llm directory
        #    making them available at cornerstonejs.org/docs/llm/[folder]/[filename.md]
        # 2. generate-llms-txt.js - which creates a llms.txt file in the build directory
        #    following the llms.txt specification
        # 3. generate-llms-full-txt.js - which creates a llms-full.txt file containing
        #    the concatenated content of all documentation files

      - name: Deploy to Netlify
        run: |
          # Run netlify-cli via npx to avoid the pnpm global-bin-dir / PATH setup
          # issue ("global bin directory ... is not in PATH") on the runner.
          #
          # --no-build stops newer netlify-cli from re-running the site's
          # UI-configured build command on deploy (which also doubled the publish
          # dir via the UI "base" setting). The docs are already built above
          # ("Build docs") into packages/docs/build.
          #
          # Use an ABSOLUTE --dir: netlify-cli resolves a relative --dir against the
          # git repo root (not the shell cwd), so "--dir=build" from packages/docs
          # pointed it at <repo>/build, which does not exist.
          #
          # --filter docs: with --no-build, netlify-cli does not read the site's UI
          # "base" (packages/docs) and instead scans the repo, finds the pnpm
          # workspace, and refuses to deploy ("multiple projects detected"). Naming
          # the docs workspace package (package.json "name": "docs") disambiguates it.
          npx -y netlify-cli deploy --no-build --filter docs --dir="$GITHUB_WORKSPACE/packages/docs/build" --prod
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}