Make it easier to run lychee locally

.github/scripts/check-links.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+set -e
+
+export MSYS_NO_PATHCONV=1 # for Git Bash on Windows
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LYCHEE_CONFIG="$SCRIPT_DIR/../../lychee.toml"
+DEPENDENCIES_DOCKERFILE="$SCRIPT_DIR/dependencies.dockerfile"
+
+# Extract lychee version from dependencies.dockerfile
+LYCHEE_VERSION=$(grep "FROM lycheeverse/lychee:" "$DEPENDENCIES_DOCKERFILE" | sed 's/.*FROM lycheeverse\/lychee:\([^ ]*\).*/\1/')
+
+# Build the lychee command with optional GitHub token
+CMD="lycheeverse/lychee:$LYCHEE_VERSION --verbose --config ./lychee.toml"
+
+# Add GitHub token if available
+if [[ -n "$GITHUB_TOKEN" ]]; then
+    CMD="$CMD --github-token $GITHUB_TOKEN"
+fi
+
+# Add the target directory
+CMD="$CMD ."
+
+# Determine if we should allocate a TTY
+DOCKER_FLAGS="--rm --init"
+if [[ -t 0 ]]; then
+    DOCKER_FLAGS="$DOCKER_FLAGS -it"
+else
+    DOCKER_FLAGS="$DOCKER_FLAGS -i"
+fi
+
+# Run lychee with proper signal handling
+# shellcheck disable=SC2086
+exec docker run $DOCKER_FLAGS -v "$(dirname "$LYCHEE_CONFIG")":/data -w /data $CMD

.github/scripts/dependencies.dockerfile

@@ -0,0 +1,3 @@
+# this file exists so that Renovate can auto-update docker image versions that are then used elsewhere
+
+FROM lycheeverse/lychee:sha-2aa22f8@sha256:2e3786630482c41f9f2dd081e06d7da1c36d66996e8cf6573409b8bc418d48c4 AS lychee

.github/workflows/build.yml

@@ -118,8 +118,8 @@ jobs:
           name: integration-test-results
           path: jmx-metrics/build/reports/tests/integrationTest
 
-  markdown-link-check:
-    uses: ./.github/workflows/reusable-markdown-link-check.yml
+  check-links:
+    uses: ./.github/workflows/reusable-check-links.yml
 
   markdown-lint-check:
     uses: ./.github/workflows/reusable-markdown-lint.yml

.github/workflows/reusable-check-links.yml

@@ -0,0 +1,18 @@
+name: Reusable - Check links
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Check links
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: ./.github/scripts/check-links.sh

CONTRIBUTING.md

@@ -67,6 +67,17 @@ $ ./gradlew test
 $ ./gradlew integrationTest
 ```
 
+### Link checking
+
+To check for broken links in documentation:
+
+```bash
+$ ./.github/scripts/check-links.sh
+```
+
+This will run [lychee](https://github.com/lycheeverse/lychee) in a Docker container to check all markdown files for broken links. 
+You can optionally set the `GITHUB_TOKEN` environment variable to avoid hitting GitHub API rate limits.
+
 Follow the Java Instrumentation [Style Guide](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/style-guideline.md) from the opentelemetry-java-instrumentation repository.
 
 Failure? Check logs for errors or mismatched dependencies.

lychee.toml

@@ -0,0 +1,16 @@
+# Configuration for lychee link checker
+# Based on the existing workflow arguments
+
+# Include fragments in links
+include_fragments = true
+
+# Maximum number of retries for failed links
+max_retries = 6
+
+# Maximum concurrency for link checking
+max_concurrency = 1
+
+# Exclude links to pull requests and issues for performance
+exclude = [
+  '^https://github.com/open-telemetry/opentelemetry-java-contrib/(issues|pull)/\d+$',
+]