check-links.yml

# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

name: Documentation Links

on:
  # Run on all pull requests
  pull_request:
  # Run on pushes to main branches
  push:
    branches:
      - main
      - develop
      - 'release/**'
      - 'feature/isaacsim-6-0'
  # Allow manual trigger
  workflow_dispatch:
  # Run weekly to catch external links that break over time
  schedule:
    - cron: '0 0 * * 0'  # Every Sunday at midnight UTC

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check-links:
    name: Check for Broken Links
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 2
        filter: tree:0

    - name: Check if latest commit touched documentation
      id: check_docs
      run: |
        # Get the files changed by this PR/commit.
        # For PRs: HEAD is the merge commit, HEAD^1 is the base branch tip.
        # Diffing HEAD^1..HEAD shows exactly what the PR introduces — files only
        # changed on the base branch (not by the PR) are identical in both and
        # won't appear. Works for push events too (last commit vs its parent).
        CHANGED=$(git diff --name-only HEAD^1 HEAD || true)
        echo "Files changed:"
        echo "$CHANGED"

        # Check against doc file types and doc paths
        if echo "$CHANGED" | grep -qE '\.md$|\.rst$|^docs/|\.github/workflows/check-links\.yml'; then
          echo "Documentation or workflow files changed. Proceeding..."
          echo "run_job=true" >> "$GITHUB_OUTPUT"
        else
          echo "No documentation files changed in this specific commit. Skipping."
          echo "run_job=false" >> "$GITHUB_OUTPUT"
        fi

    - name: Restore lychee cache
      if: steps.check_docs.outputs.run_job == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
      uses: actions/cache@v4
      with:
        path: .lycheecache
        key: cache-lychee-${{ github.sha }}
        restore-keys: cache-lychee-

    - name: Run Link Checker
      if: steps.check_docs.outputs.run_job == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
      uses: lycheeverse/lychee-action@v2
      with:
        # Check all markdown files and documentation
        # Excluded are known crawl blockers
        args: >-
          --verbose
          --no-progress
          --cache
          --max-cache-age 1d
          --exclude-path './docs/_build'
          --exclude-path './apps/warp-*'
          --exclude-path './logs'
          --exclude-path './outputs'
          --exclude-loopback
          --exclude '^file://'
          --exclude '^mailto:'
          --exclude 'localhost'
          --exclude '127\.0\.0\.1'
          --exclude 'example\.com'
          --exclude 'your-organization'
          --exclude 'YOUR_'
          --exclude 'yourdomain'
          --exclude 'user@'
          --exclude 'helm\.ngc\.nvidia\.com'
          --exclude 'slurm\.schedmd\.com'
          --exclude 'graphics\.pixar\.com'
          --exclude 'openpbs\.org'
          --exclude 'docutils\.sourceforge\.io'
          --exclude 'huggingface\.co/datasets/nvidia/PhysicalAI-Robotics-NuRec'
          --exclude 'huggingface\.co/nvidia/COMPASS'
          --exclude 'huggingface\.co/nvidia/X-Mobility'
          --exclude 'openusd\.org'
          --max-retries 5
          --retry-wait-time 10
          --timeout 20
          --user-agent 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
          --accept 200,201,202,203,204,206,301,302,303,307,308,429
          --scheme https
          --scheme http
          '*.md'
          '**/*.md'
          'docs/**/*.rst'
          'docs/**/*.html'
        # Output results to a file
        output: ./lychee-output.md
        # Fail action on broken links
        fail: true
        # Optional: Use GitHub token for authenticated requests (higher rate limit)
        token: ${{ secrets.GITHUB_TOKEN }}

    - name: Print results to logs
      if: always() && (steps.check_docs.outputs.run_job == 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule')
      run: |
        echo "========================================"
        echo "Link Checker Results:"
        echo "========================================"
        if [ -f ./lychee-output.md ]; then
          cat ./lychee-output.md
          echo ""
          echo "========================================"

          # Also add to GitHub step summary for easy viewing
          echo "## Link Checker Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          cat ./lychee-output.md >> $GITHUB_STEP_SUMMARY
        else
          echo "No output file generated"
          echo "========================================"
        fi

    - name: Fail job if broken links found
      if: failure()
      run: |
        echo "❌ Broken links were found in the documentation!"
        echo "Please review the link checker report above and fix all broken links."
        exit 1