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

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>

.lychee.toml

@@ -0,0 +1,15 @@
+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|issue)/\\d+$"
+]
+
+# better to be safe and avoid failures
+max-retries = 6
+
+# insecure is currently needed for https://osi-model.com
+insecure = true

.markdown_link_check_config.json

@@ -1,37 +0,0 @@
-{
-  "ignorePatterns": [
-    {
-      "pattern": "^https://github\\.com/open-telemetry/opentelemetry-specification/(issues|pull)"
-    },
-    {
-      "pattern": "^https://github\\.com/open-telemetry/semantic-conventions/(issues|pull|actions)"
-    },
-    {
-      "pattern": "^https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics$"
-    },
-    {
-      "pattern": "^#"
-    }
-  ],
-  "replacementPatterns": [
-    {
-      "pattern": "^/",
-      "replacement": "{{BASEURL}}/"
-    },
-    {
-      "pattern": "^https://github.com/open-telemetry/semantic-conventions/(blob|tree)/main/docs/",
-      "replacement": "LINK-CHECK-ERROR-USE-LOCAL-PATH-TO-DOC-PAGE-NOT-EXTERNAL-URL/"
-    }
-  ],
-  "httpHeaders": [
-    {
-      "urls": ["http", ".", "/"],
-      "headers": {
-        "User-Agent": "Mozilla/5.0 (compatible; OpenTelemetryDocsBot/1.0)"
-      }
-    }
-  ],
-  "retryOn429": true,
-  "timeout": "30s",
-  "aliveStatusCodes": [200, 403]
-}

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
+	docker run --rm \
-	@for f in $(ALL_DOCS); do \
+		--mount 'type=bind,source=$(PWD),target=/home/repo' \
-		npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json $$f \
+		lycheeverse/lychee \
-			|| exit 1; \
+		--config home/repo/.lychee.toml \
-	done
+		--root-dir /home/repo \
+		-v \
+		home/repo
 
 .PHONY: markdown-link-check-changelog-preview
 markdown-link-check-changelog-preview: