docs.yml

name: Docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [published]
  workflow_dispatch:

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

concurrency:
  group: pages
  cancel-in-progress: false

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

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: docs/package-lock.json

      - name: Install docs dependencies
        working-directory: docs
        run: npm ci

      - name: Resolve latest release version
        id: resolve_version
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # For deployment builds:
          # - On release events, use the event's tag name (source of truth for that deployment).
          # - On main pushes, resolve the latest release tag from GitHub.
          # For pull requests and workflow_dispatch, fall back to "dev" so preview builds still succeed.
          if [[ "${{ github.event_name }}" == "release" ]]; then
            VERSION="${{ github.event.release.tag_name }}"
          elif [[ "${{ github.event_name }}" == "push" ]]; then
            VERSION=$(gh release view --repo "${{ github.repository }}" --json tagName -q '.tagName' 2>/dev/null || true)
          else
            VERSION="dev"
          fi

          if [[ "${{ github.event_name }}" == "push" || "${{ github.event_name }}" == "release" ]]; then
            if [[ -z "$VERSION" ]]; then
              echo "ERROR: Could not resolve docs version." >&2
              exit 1
            fi
            if ! [[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
              echo "ERROR: Resolved version '$VERSION' does not match expected semver format (vX.Y.Z)." >&2
              exit 1
            fi
          fi
          echo "Resolved docs version: $VERSION"
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"

      - name: Prepare logo asset
        run: cp assets/clockworks-display-resized.png docs/public/logo.png

      - name: Build VitePress site
        working-directory: docs
        env:
          DOCS_VERSION: ${{ steps.resolve_version.outputs.version }}
        run: npm run docs:build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main' || github.event_name == 'release'
    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