docs-links.yaml

name: Docs Links

on:
  push:
    branches: [main, develop]
    paths:
      - "README.md"
      - "docs/**"
      - ".github/workflows/docs-links.yaml"
  pull_request:
    branches: [main, develop]
    paths:
      - "README.md"
      - "docs/**"
      - ".github/workflows/docs-links.yaml"

permissions:
  contents: read

jobs:
  doc-links:
    name: Doc link check (README + docs/**)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Verify relative .md links resolve
        run: |
          python3 - <<'PY'
          import re, os, sys
          targets = ["README.md"]
          for root, _, files in os.walk("docs"):
              for f in files:
                  if f.endswith(".md"):
                      targets.append(os.path.join(root, f))
          bad = []
          for path in targets:
              with open(path) as fp:
                  text = fp.read()
              for m in re.finditer(r"\[([^\]]+)\]\(([^)]+\.md)(#[^)]*)?\)", text):
                  label, target = m.group(1), m.group(2)
                  if target.startswith("http"):
                      continue
                  resolved = os.path.normpath(os.path.join(os.path.dirname(path), target))
                  if not os.path.exists(resolved):
                      bad.append(f"  {path}: [{label}]({target})")
          if bad:
              print("Broken relative .md links:")
              for line in bad:
                  print(line)
              sys.exit(1)
          print(f"Checked {len(targets)} doc files: all relative .md links resolve")
          PY