Add Lychee Doc Links Check to Local and CI (#19742)

Co-authored-by: Zijie Xia <zijie_xia@icloud.com>
Co-authored-by: Zijie Xia <zijiexia@users.noreply.github.com>
Co-authored-by: zijiexia <37504505+zijiexia@users.noreply.github.com>

.github/linters/lychee-ci.toml

@@ -0,0 +1,42 @@
+no_progress = true
+verbose = "warn"
+timeout = 20
+max_concurrency = 8
+retry_wait_time = 2
+max_retries = 2
+
+# CI should validate external links over the network.
+offline = false
+scheme = ["http", "https"]
+
+exclude_path = [
+  # Exclude generated Sphinx build artifacts.
+  # - "(\\./)?" allows both "docs/..." and "./docs/..."
+  # - "[/\\\\]" supports both slash styles in CI environments
+  "^(\\./)?docs[/\\\\]_build[/\\\\]",
+]
+
+exclude = [
+  # Local-only endpoints referenced in docs/examples.
+  # These are expected to be unreachable in GitHub-hosted CI.
+  "^https?://localhost(:[0-9]+)?(/|$)",
+  "^http://127\\.0\\.0\\.1(:[0-9]+)?(/|$)",
+  # Vendor pages that frequently block/deny CI user-agents (transient 403/anti-bot).
+  "^https://www\\.intel\\.com/content/www/us/en/ark/products/series/240391/intel-arc-b-series-graphics\\.html$",
+  "^https://www\\.intel\\.com/content/www/us/en/ark/products/series/242616/intel-arc-pro-b-series-graphics\\.html$",
+  "^https://www\\.intel\\.com/content/www/us/en/products/sku/241598/intel-arc-b580-graphics/specifications\\.html$",
+
+  # Non-routable bind address used in examples, never externally reachable.
+  "^http://0\\.0\\.0\\.0(/|$)",
+
+  # Large doc portals with anti-bot/rate-limit behavior in CI.
+  # We keep API docs references in content but do not fail CI on access policy.
+  "^https://platform\\.openai\\.com/docs/",
+  "^https://gamma\\.app/docs/Optimizing-RL-with-SGLang-y0kqgj877k34779$",
+  "^https://aflah02\\.substack\\.com/p/multi-node-llm-inference-with-sglang/?$",
+
+  # Known noisy image URLs used in notebook-rendered examples.
+  "^https://github\\.com/sgl-project/sglang/blob/main/examples/assets/example_image\\.png\\?raw=true$",
+  "^https://raw\\.githubusercontent\\.com/sgl-project/sglang/main/examples/assets/example_image\\.png/?$",
+  "^https://raw\\.githubusercontent\\.com/sgl-project/sglang/main/assets/logo\\.png/?$",
+]

.github/linters/lychee.toml

@@ -0,0 +1,18 @@
+# .github/linters/lychee.toml
+no_progress = true
+verbose = "warn"
+timeout = 20
+max_concurrency = 8
+
+offline = true
+
+# Ignore generated docs output; check source docs only.
+exclude_path = [
+  "^(\\./)?docs[/\\\\]_build[/\\\\]",
+]
+
+exclude = [
+  "^https?://localhost(:[0-9]+)?(/|$)",
+  "^http://127\\.0\\.0\\.1(:[0-9]+)?(/|$)",
+  "^http://0\\.0\\.0\\.0(/|$)",
+]

.github/workflows/lint.yml

@@ -25,6 +25,11 @@ jobs:
       - name: Run pre-commit checks
         run: SKIP=no-commit-to-branch pre-commit run --all-files --show-diff-on-failure
 
+      - name: Run lychee docs checks (offline references)
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
+        with:
+          args: --config .github/linters/lychee.toml README.md "docs/**/*.md" "docs/**/*.rst" "docs/**/*.ipynb"
+
       - name: Run sgl-kernel clang-format checks
         uses: DoozyX/clang-format-lint-action@v0.20
         with:

.github/workflows/nightly-link-check.yml

@@ -0,0 +1,32 @@
+name: Nightly Link Check
+
+on:
+  schedule:
+    - cron: "0 2 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: nightly-link-check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lychee-online:
+    if: github.repository == 'sgl-project/sglang'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run lychee online link checks
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
+        with:
+          fail: true
+          args: >-
+            --config .github/linters/lychee-ci.toml
+            README.md
+            docs/**/*.md
+            docs/**/*.rst
+            docs/**/*.ipynb
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}