Add cross-file anchor link check (use lychee for markdown link checking)

.github/workflows/checks.yml

@@ -43,6 +43,13 @@ jobs:
     - name: install dependencies
       run: npm install
 
+    - name: Restore lychee cache
+      uses: actions/cache@v4
+      with:
+        path: .lycheecache
+        key: cache-lychee-${{ github.sha }}
+        restore-keys: cache-lychee-
+
     - name: run markdown-link-check
       run: make markdown-link-check
 

.lychee.toml

@@ -0,0 +1,16 @@
+include-fragments = true
+
+accept = ["200..=299", "403"]
+
+exclude  = [
+    "^https://www.foo.bar",
+    # excluding links to pull requests and issues is done for performance
+    "^https://github.com/open-telemetry/semantic-conventions/pull/\\d+$",
+    "^https://github.com/open-telemetry/semantic-conventions/issue/\\d+$"
+]
+
+# better to be safe and avoid failures
+max-retries = 6
+
+# insecure is currently needed for https://osi-model.com
+insecure = true

Makefile

@@ -68,11 +68,13 @@ misspell-correction:	$(MISSPELL)
 
 .PHONY: markdown-link-check
 markdown-link-check:
-	@if ! npm ls markdown-link-check; then npm install; fi
-	@for f in $(ALL_DOCS); do \
-		npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json $$f \
-			|| exit 1; \
-	done
+	docker run --rm \
+		--mount 'type=bind,source=$(PWD),target=/home/repo' \
+		lycheeverse/lychee \
+		--config home/repo/.lychee.toml \
+		--root-dir /home/repo \
+		-v \
+		home/repo
 
 .PHONY: markdown-link-check-changelog-preview
 markdown-link-check-changelog-preview: