apf_portal/.gitea/workflows/docs-site.yml

# Per ADR-0022 (Documentation site — VitePress).
# Builds the static docs site from `docs/`. On `pull_request` the
# build is a syntax / dead-link gate; on `push` to `main` the same
# build runs and the bundle is uploaded as an artifact so the
# operator can drop it on the static host until the future
# infrastructure ADR locks the rsync target.
#
# Path filter scopes the workflow to changes that can actually
# affect the rendered site: documentation content, the VitePress
# configuration itself, and dependency manifests (Vite/VitePress
# upgrades).

name: Docs site

on:
  pull_request:
    branches: [main]
    paths:
      - 'docs/**'
      - 'package.json'
      - 'pnpm-lock.yaml'
      - '.gitea/workflows/docs-site.yml'
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'package.json'
      - 'pnpm-lock.yaml'
      - '.gitea/workflows/docs-site.yml'

# See `.gitea/workflows/ci.yml` for the rationale — Node 24's
# bundled CA set rejects some chains the runner's OS trust store
# validates, and `--use-system-ca` (Node ≥ 22) tells Node to
# consult the OS CA bundle alongside its own.
env:
  NODE_OPTIONS: --use-system-ca

jobs:
  build:
    runs-on: [self-hosted, on-prem]
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v6
        with:
          node-version-file: '.nvmrc'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      # `pnpm docs:build` runs `vitepress build docs` per the script
      # added in this chantier. Fails the workflow on:
      #   - markdown / Vue-template parse errors,
      #   - genuine dead in-site links (the config's
      #     `ignoreDeadLinks` regex already covers the intentional
      #     cross-repo + localhost references that must not break
      #     the build).
      - name: Build docs site
        run: pnpm docs:build
      # Sanity-check: the build must produce HTML where the Mermaid
      # plugin has injected its diagram markers. Guards against a
      # silent regression on the plugin upgrade path — `pnpm install`
      # might happily resolve a new major that no longer hooks into
      # markdown-it the same way, leaving fenced ```mermaid blocks
      # as raw text. Per ADR-0022 §"Confirmation".
      - name: Assert Mermaid renders into the build output
        run: |
          if ! grep -RIlq 'class="mermaid"\|<svg' docs/.vitepress/dist/decisions/0009-auth-flow-oidc-pkce-msal-node.html; then
            echo "ADR-0009's Mermaid sequence diagram did not render — Mermaid plugin regression?" >&2
            exit 1
          fi
      # On push only — upload the static bundle so the operator can
      # rsync it to the host until the future infra ADR formalises
      # the deployment target. The artifact lives 30 days in Gitea's
      # storage by default.
      - name: Upload docs bundle
        if: github.event_name == 'push'
        uses: actions/upload-artifact@v3
        with:
          name: docs-site
          path: docs/.vitepress/dist/
          retention-days: 30