docs-broken-links.yml

name: Check Documentation Broken Links

on:
  pull_request:
    paths:
      - "docs/**"
  push:
    branches:
      - main
    paths:
      - "docs/**"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  check-links:
    name: Check broken links
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Set up Node
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: "22"

      - name: Install Mint CLI
        run: npm i -g mint@4.2.741

      # Pruning immutable snapshots keeps the check fast (--files still parses every
      # page); the default version must stay because unprefixed links resolve to it.
      - name: Prune frozen doc versions (keep edge and latest)
        if: github.event_name != 'workflow_dispatch'
        run: |
          python3 - <<'EOF'
          import json
          import shutil
          from pathlib import Path

          docs = Path("docs")
          spec_path = docs / "docs.json"
          spec = json.loads(spec_path.read_text())

          keep_dirs = {"edge"}
          for lang in spec["navigation"]["languages"]:
              kept = [v for v in lang["versions"] if v["version"] == "Edge" or v.get("default")]
              lang["versions"] = kept
              keep_dirs.update(v["version"] for v in kept if v["version"] != "Edge")

          missing = [d for d in keep_dirs if not (docs / d).is_dir()]
          if missing:
              raise SystemExit(f"docs.json version labels do not match directories: {missing}")

          spec_path.write_text(json.dumps(spec, indent=2))

          for path in docs.glob("v*"):
              if path.is_dir() and path.name not in keep_dirs:
                  shutil.rmtree(path)
          EOF

      - name: Run broken link checker
        run: mint broken-links
        working-directory: ./docs