Skip external URL checks in CI; add weekly link check

HTMLProofer remote URL checks frequently fail in CI due to rate
limiting on third-party sites. Make external checks opt-in via the
CHECK_EXTERNAL_LINKS env var (default off) so normal CI runs stay
fast and reliable, and add a weekly scheduled workflow that runs the
full external link check.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: ahpook

.github/workflows/link-check.yml

@@ -0,0 +1,30 @@
+name: Weekly External Link Check
+on:
+  schedule:
+    # Every Monday at 08:00 UTC
+    - cron: "0 8 * * 1"
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Git repository
+        uses: actions/checkout@v6
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@89f90524b88a01fe6e0b732220432cc6142926af # v1
+        with:
+          bundler-cache: true
+      - name: Set up Node
+        uses: actions/setup-node@v6.4.0
+      - name: Bootstrap
+        run: script/bootstrap
+        env:
+          SKIP_BUNDLER: true
+      - name: Build site
+        run: script/build --config _config.yml,test/_config.yml
+      - name: Check links (including external URLs)
+        run: script/html-proofer
+        env:
+          CHECK_EXTERNAL_LINKS: true

script/html-proofer

@@ -22,6 +22,26 @@
 require "bundler/setup"
 require "html-proofer"
 
+# ---------------------------------------------------------
+# External (remote) link checking is opt-in.
+#
+# Remote URL checks are slow and frequently fail in CI due to
+# rate limiting and transient network errors on third-party
+# sites. By default we skip them so normal CI runs stay fast
+# and reliable. Set CHECK_EXTERNAL_LINKS=true to enable the
+# full remote link check (used by the scheduled weekly run).
+# ---------------------------------------------------------
+check_external = %w[1 true yes].include?(
+  ENV.fetch("CHECK_EXTERNAL_LINKS", "").strip.downcase
+)
+
+if check_external
+  puts "==> Running HTMLProofer WITH external link checks"
+else
+  puts "==> Running HTMLProofer WITHOUT external link checks " \
+       "(set CHECK_EXTERNAL_LINKS=true to enable)"
+end
+
 # ---------------------------------------------------------
 # URLs & patterns to ignore during link checking.
 # Some websites block automated requests, cause false
@@ -63,6 +83,7 @@ HTMLProofer::Runner.new(
   ["_site"],                        # Directory containing the generated site
   parallel: { in_threads: 4 },      # Speed up checks using 4 threads
   type: :directory,
+  disable_external: !check_external, # Skip remote URL checks unless opted in
   ignore_urls: url_ignores,         # Skip known-problematic URLs
   check_html: true,                 # Validate HTML structure
   check_opengraph: true,            # Check for OpenGraph tags

script/test

@@ -7,7 +7,11 @@ bundle exec rake
 
 set +e
 
-script/html-proofer
+# Skip remote/external URL checks in normal CI runs. They are slow and
+# frequently fail due to rate limiting on third-party sites. The full
+# external link check runs on a weekly schedule (see
+# .github/workflows/link-check.yml).
+CHECK_EXTERNAL_LINKS=false script/html-proofer
 HTML_PROOFER_EXIT="$?"
 test/prose
 PROSE_EXIT="$?"