docs.yml

name: Deploy docs

on:
  push:
    branches:
      - stable
      - unstable
  workflow_run:
    workflows: ["Version docs"]
    types:
      - completed
  workflow_dispatch:
    inputs:
      ref:
        description: "Ref to deploy docs from, defaults to `unstable`"
        required: false
        default: "unstable"
        type: string

jobs:
  docs:
    # For workflow_run, only deploy if Version docs succeeded
    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    env:
      # Always build "current" (Next) docs from unstable
      # Versioned docs come from docs-versions branch
      DEPLOY_REF: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.ref || 'unstable' }}
    steps:
      - name: Log Deployment Ref
        run: echo "Deploying docs from ref $DEPLOY_REF"

      - uses: actions/checkout@v4
        with:
          ref: ${{ env.DEPLOY_REF }}

      - name: Install pnpm before setup node
        uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          check-latest: true
          cache: pnpm

      - name: Node.js version
        id: node
        run: echo "v8CppApiVersion=$(node --print "process.versions.modules")" >> $GITHUB_OUTPUT

      - name: Restore dependencies
        uses: actions/cache@v4
        id: cache-deps
        with:
          path: |
            node_modules
            packages/*/node_modules
          key: ${{ runner.os }}-${{ steps.node.outputs.v8CppApiVersion }}-${{ hashFiles('**/pnpm-lock.yaml', '**/package.json') }}

      - name: Install & build
        if: steps.cache-deps.outputs.cache-hit != 'true'
        run: pnpm install --frozen-lockfile && pnpm build

      - name: Build
        run: pnpm build
        if: steps.cache-deps.outputs.cache-hit == 'true'

      - name: Build and collect docs
        run: pnpm docs:build

      - name: Lint built docs
        run: pnpm docs:lint:fix

      # Fetch versioned docs from docs-versions branch (if it exists)
      - name: Fetch versioned docs
        run: |
          git fetch origin docs-versions 2>/dev/null || true
          if git rev-parse origin/docs-versions >/dev/null 2>&1; then
            echo "Found docs-versions branch, fetching versioned content..."
            git worktree add /tmp/docs-versions origin/docs-versions
            cp -r /tmp/docs-versions/versioned_docs docs/ 2>/dev/null || echo "No versioned_docs"
            cp -r /tmp/docs-versions/versioned_sidebars docs/ 2>/dev/null || echo "No versioned_sidebars"
            cp /tmp/docs-versions/versions.json docs/ 2>/dev/null || echo "No versions.json"
            git worktree remove /tmp/docs-versions
            echo "Versioned docs fetched successfully"
          else
            echo "No docs-versions branch found, building without versioning"
          fi

      - name: Build docs
        working-directory: docs
        run: pnpm install && pnpm build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build