name: Build & publish docs (rc + release)

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

permissions:
  contents: read

env:
  MKDOCS_CONFIG: mkdocs/mkdocs.yml
  MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout (tag)
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Python
        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

          OUT_BASE="${RUNNER_TEMP}/mkdocs_out"
          SITE="${OUT_BASE}/site"
          SITE_OFFLINE="${OUT_BASE}/site_offline"

          rm -rf "${OUT_BASE}"
          mkdir -p "${SITE}" "${SITE_OFFLINE}"

          # Normal build
          mkdocs build "${FLAGS[@]}" -f "${MKDOCS_CONFIG}" -d "${SITE}"

          # Offline build (only matters if your mkdocs.yml/plugins read OFFLINE)
          OFFLINE=true mkdocs build "${FLAGS[@]}" -f "${MKDOCS_CONFIG}" -d "${SITE_OFFLINE}"

      - name: Upload site artifact (normal)
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: ${{ runner.temp }}/mkdocs_out/site

      - name: Upload site artifact (offline)
        uses: actions/upload-artifact@v4
        with:
          name: site_offline
          path: ${{ runner.temp }}/mkdocs_out/site_offline

  release:
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: write

    steps:
      - name: Download offline site artifact
        uses: actions/download-artifact@v4
        with:
          name: site_offline
          path: site_offline

      - name: Zip offline site
        run: |
          set -euo pipefail
          zip -r "${GITHUB_REF_NAME}.zip" site_offline

      - 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: |
            ${{ github.ref_name }}.zip

      - 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: |
            ${{ github.ref_name }}.zip

  deploy:
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: write

    steps:
      - name: Download normal site artifact
        uses: actions/download-artifact@v4
        with:
          name: site
          path: site

      - name: Checkout gh-pages branch
        uses: actions/checkout@v4
        with:
          ref: gh-pages
          fetch-depth: 0

      - name: Deploy release to gh-pages root
        if: startsWith(github.ref_name, 'v')
        run: |
          set -euo pipefail
          rm -rf ./*
          cp -a ../site/. .
          git add -A
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git commit -m "Deploy release ${GITHUB_REF_NAME}" || echo "No changes to commit"
          git push origin gh-pages

      - name: Deploy RC preview to /rc/
        if: startsWith(github.ref_name, 'rc')
        run: |
          set -euo pipefail
          rm -rf rc
          mkdir -p rc
          cp -a ../site/. rc/
          # optional metadata for your toolbar link idea:
          printf '{"tag":"%s"}\n' "${GITHUB_REF_NAME}" > rc/rc.json

          git add -A
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git commit -m "Deploy RC preview ${GITHUB_REF_NAME}" || echo "No changes to commit"
          git push origin gh-pages