docs.yml

name: Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'site/**'
      - 'src/**'
      - 'scripts/build-activity-snapshot.mjs'
      - 'scripts/optimize-images.mjs'
      - '.github/workflows/docs.yml'
  # Refresh on every published release so the community-page "Activity on deck"
  # pane picks up new release names + cadence the moment they ship.
  release:
    types: [published]
  # Daily refresh so the "last push X d ago" timer doesn't slowly age when no
  # release has shipped recently but commits keep landing on main.
  schedule:
    - cron: '17 6 * * *'
  # Bowire.Bootcamp pushes to its own main → it dispatches `bootcamp-updated`
  # at us so the next bowire.io deploy carries the new Bootcamp content
  # under /bootcamp/. No daily polling — only fires when the Bootcamp repo
  # actually changed.
  repository_dispatch:
    types: [bootcamp-updated]
  workflow_dispatch:

env:
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true
  DOTNET_NOLOGO: true

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

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

jobs:
  build:
    name: Build Documentation
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Setup .NET
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: '10.0.x'

      # Node is needed for both the activity-snapshot generator (runs before
      # Jekyll, populates site/_data/activity.json) and Pagefind (runs after
      # the build, indexes the combined output). One setup serves both.
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: '20'

      - name: Build projects (for API docs)
        run: dotnet build Kuestenlogik.Bowire.slnx --configuration Release

      # Build DocFX documentation
      - name: Install DocFX
        run: dotnet tool install -g docfx

      - name: Build DocFX documentation
        run: docfx docs/docfx.json

      # Bowire.Bootcamp lives in its own repo so the lesson catalogue can
      # version independently. We clone the latest main, build its DocFX
      # alongside ours, and mount the output under /bootcamp/ in the
      # combined Pages bundle. The repository_dispatch trigger above means
      # a Bootcamp push triggers this build; a Bowire-side push picks up
      # whatever HEAD of Bowire.Bootcamp/main looks like at build time.
      - name: Checkout Bowire.Bootcamp
        uses: actions/checkout@v6
        with:
          repository: Kuestenlogik/Bowire.Bootcamp
          path: bootcamp-source
          fetch-depth: 1

      - name: Build Bootcamp DocFX
        working-directory: bootcamp-source
        run: docfx .docfx/docfx.json

      # Refresh the activity snapshot (releases + last-push) that powers the
      # community page's "Activity on deck" pane. Runs before Jekyll so the
      # build picks up site/_data/activity.json from this step. Auth via the
      # workflow's GITHUB_TOKEN keeps the call well under the 5000 req/h
      # authenticated rate. Snapshot script writes a fallback JSON on failure
      # so the page never renders broken values.
      - name: Refresh activity snapshot
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: node scripts/build-activity-snapshot.mjs

      # Image transcodes (AVIF + WebP responsive variants) are committed
      # alongside their .png/.jpg sources. CI runs --check to fail the
      # build if any source has a stale or missing variant -- forcing
      # contributors to regenerate locally before committing. Saves
      # 25-40 min/build vs. the prior "regenerate from scratch" approach.
      - name: Install sharp
        run: npm install --no-audit --no-fund
      - name: Check image transcodes are up to date
        run: node scripts/optimize-images.mjs --check

      # Build Jekyll landing page
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
          working-directory: site

      - name: Build Jekyll site
        run: |
          cd site
          bundle install
          bundle exec jekyll build

      # Combine: Jekyll output + DocFX output + Bootcamp DocFX output
      - name: Combine outputs
        run: |
          mkdir -p _combined
          cp -r site/_site/* _combined/
          cp -r artifacts/docs _combined/docs/
          cp -r bootcamp-source/artifacts/docs-learn _combined/bootcamp/

      # DocFX renders README.md as README.html, so bare directory URLs
      # (.../unit-1-cli/) 404 on GitHub Pages because there's no
      # index.html. Materialise the README as the directory index for
      # both DocFX outputs. Idempotent; safe to re-run.
      - name: Alias README.html as directory index.html
        run: |
          find _combined/docs _combined/bootcamp -name README.html -type f -print0 |
            while IFS= read -r -d '' f; do
              cp -f "$f" "$(dirname "$f")/index.html"
            done

      # Pagefind crawls the already-rendered HTML under _combined/ (both
      # marketing site and docs) and emits a single full-text index into
      # _combined/pagefind/. Client-side only, no runtime server.
      - name: Generate Pagefind search index
        run: npx -y pagefind --site _combined --output-path _combined/pagefind

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: _combined

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    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@v5