name: Build & publish docs (rc + release)

on:
  push:
    tags:
      - "rc-*"
      - "v*"
  workflow_dispatch:

permissions:
  contents: read

env:
  MKDOCS_CONFIG: mkdocs/mkdocs.yml
  MKDOCS_OUTPUT_DIR: ${{ runner.temp }}/dist
  MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install deps
        run: |
          set -euo pipefail
          pip install -r mkdocs/requirements.txt

      - name: Build docs (strict gate)
        run: |
          set -euo pipefail

          FLAGS=()
          if [ "${MKDOCS_STRICT}" = "true" ]; then
            FLAGS+=(--strict)
          fi

          mkdir -p "${MKDOCS_OUTPUT_DIR}"

          OFFLINE="${OFFLINE}" mkdocs build \
            "${FLAGS[@]}" \
            -f "${MKDOCS_CONFIG}" \
            -d "${MKDOCS_OUTPUT_DIR}"

      - name: Zip site
        run: |
          set -euo pipefail
          cd "${MKDOCS_OUTPUT_DIR}"
          zip -r "${GITHUB_REF_NAME}.zip" .
  release:
    runs-on: ubuntu-latest
    needs: build
      steps:
      # -------------------------
      # RC-only step
      # -------------------------
      - name: Publish prerelease 
        if: startsWith(github.ref_name, 'rc-')
        uses: softprops/action-gh-release@v2
        with:
          prerelease: true
          name: ${{ github.ref_name }}
          tag_name: ${{ github.ref_name }}
          body: |
            Release candidate preview (if deployed): /rc/
          files: |
            ${{ runner.temp }}/${{ github.ref_name }}.zip

      # -------------------------
      # Final release-only step
      # -------------------------
      - name: Publish release
        if: startsWith(github.ref_name, 'v')
        uses: softprops/action-gh-release@v2
        with:
          name: ${{ github.ref_name }}
          tag_name: ${{ github.ref_name }}
          files: |
            ${{ runner.temp }}/${{ github.ref_name }}.zip
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        run: |
          echo "TBD :)"