.github/workflows/docs.yml

name: Docs

on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:

env:
  FORCE_COLOR: 2
  NODE: 22

permissions:
  contents: read

jobs:
  build-dist:
    runs-on: ubuntu-latest

    steps:
      - name: Clone repository
        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
        with:
          node-version: "${{ env.NODE }}"
          cache: npm

      - name: Install npm dependencies
        run: npm ci

      - name: Build CSS
        run: npm run css

      - name: Build JS
        run: npm run js

      - name: Upload CSS artifacts
        id: css-artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: css-dist
          path: dist/css/
          retention-days: 1

      - name: Upload JS artifacts
        id: js-artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: js-dist
          path: dist/js/
          retention-days: 1

  docs:
    needs: build-dist
    runs-on: ubuntu-latest

    steps:
      - name: Clone repository
        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
        with:
          node-version: "${{ env.NODE }}"
          cache: npm

      - name: Install npm dependencies
        run: npm ci

      - name: Download CSS artifacts
        uses: actions/download-artifact@v4
        with:
          name: css-dist
          path: dist/css/

      - name: Download JS artifacts
        uses: actions/download-artifact@v4
        with:
          name: js-dist
          path: dist/js/

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

      - name: Validate HTML
        run: npm run docs-html-validate

      - name: Run linkinator
        uses: JustinBeckwith/linkinator-action@3d5ba091319fa7b0ac14703761eebb7d100e6f6d # v1.11.0
        with:
          paths: _site
          recurse: true
          verbosity: error
          skip: "^http://localhost"