docs-preview.yml

name: Build docs

on:
  push:
    branches: [master]
  pull_request:
    types: [opened, synchronize, reopened, closed]
    paths:
      # Documentation pages and the browser playground shell.
      - "docs/**"
      - "playground/**"
      # WASM playground server inputs. The WASM crate links the root server
      # browser entry point, so request/IDE changes can affect PR previews.
      - "src/**"
      - "crates/**"
      - "Cargo.toml"
      - "Cargo.lock"
      - "build.rs"
      - "rust-toolchain.toml"
      - ".github/actions/setup-emscripten/**"
      - ".github/actions/setup-rust/**"
      - ".github/actions/setup-sccache/**"
      - ".github/workflows/docs-preview.yml"
      - ".github/workflows/deploy-docs.yml"

permissions:
  contents: read

env:
  ASTRO_SITE: https://vide.pascal-lab.net
  ASTRO_BASE: ${{ github.event_name == 'pull_request' && format('/preview/pr-{0}/', github.event.pull_request.number) || '/staging/' }}
  PREVIEW_URL: ${{ github.event_name == 'pull_request' && format('https://vide.pascal-lab.net/preview/pr-{0}/', github.event.pull_request.number) || '' }}
  STAGING_URL: https://vide.pascal-lab.net/staging/
  EMSDK_VERSION: 5.0.2

jobs:
  metadata:
    name: Prepare preview metadata
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: Write preview metadata
        env:
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_ACTION: ${{ github.event.action }}
        run: |
          set -euo pipefail

          preview_path="preview/pr-${PR_NUMBER}/"
          preview_url="https://vide.pascal-lab.net/${preview_path}"

          mkdir -p preview-metadata
          printf '%s\n' "${PR_NUMBER}" > preview-metadata/pr-number
          printf '%s\n' "${PR_ACTION}" > preview-metadata/action
          printf '%s\n' "${preview_path}" > preview-metadata/path
          printf '%s\n' "${preview_url}" > preview-metadata/url

          if [ "${PR_ACTION}" = "closed" ]; then
            echo "Docs preview will be removed from ${preview_url}" >> "${GITHUB_STEP_SUMMARY}"
          else
            echo "Docs preview will be deployed to ${preview_url}" >> "${GITHUB_STEP_SUMMARY}"
          fi

      - name: Upload preview metadata
        uses: actions/upload-artifact@v4
        with:
          name: vide-docs-preview-metadata
          path: preview-metadata
          retention-days: 7

  build:
    name: Build Starlight
    if: github.event_name != 'pull_request' || github.event.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Restore playground WASM cache
        id: playground-wasm-cache
        uses: actions/cache/restore@v4
        with:
          path: playground/public/wasm
          key: playground-wasm-${{ runner.os }}-${{ env.EMSDK_VERSION }}-${{ hashFiles('Cargo.toml', 'Cargo.lock', 'build.rs', 'rust-toolchain.toml', 'src/**', 'crates/**', 'playground/scripts/build-vide-wasm.mjs', 'playground/scripts/script-utils.mjs', '.github/actions/setup-emscripten/**', '.github/actions/setup-rust/**') }}

      - name: Verify cached playground WASM
        if: steps.playground-wasm-cache.outputs.cache-hit == 'true'
        run: |
          test -s playground/public/wasm/vide-lsp.js
          test -s playground/public/wasm/vide-core.js
          test -s playground/public/wasm/vide-core.wasm

      - name: Install Rust
        if: steps.playground-wasm-cache.outputs.cache-hit != 'true'
        uses: ./.github/actions/setup-rust

      - name: Setup sccache
        if: steps.playground-wasm-cache.outputs.cache-hit != 'true'
        uses: ./.github/actions/setup-sccache
        with:
          cmake-launcher: "true"

      - name: Rust Cache
        if: steps.playground-wasm-cache.outputs.cache-hit != 'true'
        uses: Swatinem/rust-cache@v2
        continue-on-error: true
        with:
          shared-key: docs-wasm-${{ runner.os }}-${{ env.EMSDK_VERSION }}
          key: wasm-src-${{ hashFiles('Cargo.toml', 'Cargo.lock', 'build.rs', 'rust-toolchain.toml', 'src/**', 'crates/**', 'playground/scripts/build-vide-wasm.mjs', 'playground/scripts/script-utils.mjs', '.github/actions/setup-emscripten/**', '.github/actions/setup-rust/**') }}
          cache-workspace-crates: true
          cache-on-failure: true

      - name: Install Emscripten SDK
        if: steps.playground-wasm-cache.outputs.cache-hit != 'true'
        uses: ./.github/actions/setup-emscripten
        with:
          version: ${{ env.EMSDK_VERSION }}

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

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

      - name: Build playground WASM
        if: steps.playground-wasm-cache.outputs.cache-hit != 'true'
        run: |
          source "${EMSDK}/emsdk_env.sh"
          npm run build:wasm
        working-directory: playground

      - name: Save playground WASM cache
        if: steps.playground-wasm-cache.outputs.cache-hit != 'true'
        uses: actions/cache/save@v4
        continue-on-error: true
        with:
          path: playground/public/wasm
          key: ${{ steps.playground-wasm-cache.outputs.cache-primary-key }}

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

      - name: Build docs
        run: npm run build
        working-directory: docs

      - name: Add preview summary
        if: github.event_name == 'pull_request'
        run: |
          set -euo pipefail
          echo "Docs preview will be deployed to ${PREVIEW_URL}" >> "${GITHUB_STEP_SUMMARY}"

      - name: Upload preview artifact
        if: github.event_name == 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: vide-docs-preview
          path: docs/dist
          retention-days: 7

      - name: Add master docs summary
        if: github.event_name == 'push'
        run: |
          set -euo pipefail
          echo "Master docs will be deployed to ${STAGING_URL}" >> "${GITHUB_STEP_SUMMARY}"

      - name: Upload master docs artifact
        if: github.event_name == 'push'
        uses: actions/upload-artifact@v4
        with:
          name: vide-docs-master
          path: docs/dist
          retention-days: 7