docs.yml

name: Docs

# CI calls this when the docs or what they read changes, so a failing build
# blocks the merge
on:
  workflow_call:
  workflow_dispatch:

permissions: {}

jobs:
  build:
    if: github.repository == 'cutenode/nodevu'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout the repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Setup Node.js
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: .node-version
          # no npm cache in a job that deploys the docs, so a poisoned cache can't
          # reach the site
          package-manager-cache: false
      - name: Run npm ci
        run: npm ci --workspaces=false
      - name: Build the docs
        run: npm run docs
      # PRs check relative links offline in CI's lint job. External links go
      # stale on their own, so the weekly run checks them, on the built site too
      - name: Check external links
        if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
        with:
          args: --include-fragments --no-progress --exclude-path tools/oxlint/anti-slop . out
          output: ${{ runner.temp }}/lychee.md
      - name: Upload the site
        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: out

  deploy:
    needs: build
    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    # never cancel a deploy halfway
    concurrency:
      group: docs-deploy
      cancel-in-progress: false
    permissions:
      pages: write # publish the site
      id-token: write # prove the deployment comes from this workflow
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1