fix(links): stop GitHub 503s from filing false broken-link issues

.github/workflows/external-links.yml

@@ -26,22 +26,45 @@ jobs:
   lychee:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    env:
+      # --cache saves passing links to .lycheecache so the re-check below only
+      # re-requests the links that failed. lychee never caches a failure.
+      LYCHEE_ARGS: "--config lychee.toml --no-progress --cache '**/*.md' '**/*.mdx'"
     steps:
       - uses: actions/checkout@v4
 
       - name: Check external links
         id: lychee
         uses: lycheeverse/lychee-action@v2
         with:
-          args: "--config lychee.toml --no-progress '**/*.md' '**/*.mdx'"
+          args: ${{ env.LYCHEE_ARGS }}
           fail: false
           format: markdown
-          output: ./lychee-report.md
+          # Keep the report outside the checkout, or the re-check's '**/*.md'
+          # glob reads it as a docs page and lists every failure twice.
+          output: ${{ runner.temp }}/lychee-report.md
 
-      - name: Open or update tracking issue on broken links
+      # Throttled or briefly unavailable hosts (GitHub in particular) answer
+      # live pages with a 503, and lychee reports that without retrying. Only
+      # links that still fail after a pause count as broken.
+      - name: Wait before re-checking failures
+        if: steps.lychee.outputs.exit_code != 0
+        run: sleep 120
+
+      - name: Re-check failed links
+        id: recheck
         if: steps.lychee.outputs.exit_code != 0
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: ${{ env.LYCHEE_ARGS }}
+          fail: false
+          format: markdown
+          output: ${{ runner.temp }}/lychee-report.md
+
+      - name: Open or update tracking issue on broken links
+        if: steps.lychee.outputs.exit_code != 0 && steps.recheck.outputs.exit_code != 0
         uses: peter-evans/create-issue-from-file@v5
         with:
           title: 🔗 Broken external links detected
-          content-filepath: ./lychee-report.md
+          content-filepath: ${{ runner.temp }}/lychee-report.md
           labels: broken-links, automated

evm/wallet-integrations/particle.mdx

@@ -77,7 +77,7 @@
 NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID='WALLETCONNECT_PROJECT_ID'
 ```
 
 ## Configuring Particle Connect
 
 To get started, we'll configure and initialize Particle Connect. Begin by
 creating a new `ConnectKit.tsx` file in your `src` directory.
@@ -137,7 +137,7 @@
 configured `ConnectKitProvider` component then wraps the app’s content, making
 this configuration available.
 
 ## Integrate Particle Connect in Your App
 
 Once configured, wrap your application with the `ParticleConnectKit` component
 to make the Particle Connect SDK accessible throughout the app. Update the
@@ -171,7 +171,7 @@
 }
 ```
 
 ## Building the Application
 
 With your project set up, dependencies installed, and Particle Connect
 configured, you can start building in the `page.tsx` file.
@@ -179,7 +179,7 @@
 In `page.tsx`, you’ll define the core features: login flow, transaction
 handling, and the UI.
 
 ### Connecting the Wallet
 
 With `layout.tsx` configured, the next step is to add a primary **Connect
 Wallet** button to facilitate user login. Import `ConnectButton` from
@@ -213,7 +213,7 @@
 export default HomePage;
 ```
 
 ### Sending Transactions with an EIP-1193 Provider
 
 Particle Connect includes AA features out of the box, but using it with the
 Particle AA SDK allows you to work with EIP-1193 providers, like `ethers`. This
@@ -267,7 +267,7 @@
 This example demonstrates how to use an existing EIP-1193 provider, but you can
 also construct a `userOp` directly with Particle Connect. For an example, refer
 to the
-[starter repository](https://github.com/Particle-Network/connectkit-aa-usage/blob/2017262daf297624362d51f3d50cccd3b4606ef9/app/page.tsx#L117).
+[starter repository](https://github.com/Particle-Network/connectkit-aa-demo/blob/2017262daf297624362d51f3d50cccd3b4606ef9/app/page.tsx#L117).
 
 ## Full app example
 
@@ -392,7 +392,7 @@
 }
 ```
 
 ### Available Particle Connect Hooks
 
 This example illustrates a basic use of Particle Connect. For a complete list of
 available hooks, refer to the

lychee.toml

@@ -60,6 +60,16 @@ exclude = [
 # Don't check mailto: links (this is the default; set explicitly for clarity).
 include_mail = false
 
+# Check GitHub file links (github.com/<owner>/<repo>/blob/<ref>/<path>) against
+# raw.githubusercontent.com, the CDN that serves the same file for scripted
+# downloads. A missing file, ref, or repo still returns 404 there, while
+# github.com's rendered blob pages are the ones that answer the checker with
+# 503s for files that exist. Reports show the raw URL. A blob link must point
+# at a file; the CDN returns 404 for directories, so use /tree/ for those.
+remap = [
+  "^https://github\\.com/([^/]+)/([^/]+)/blob/([^?#]+).* https://raw.githubusercontent.com/$1/$2/$3",
+]
+
 # Per-host throttling. NOTE: TOML table headers capture every key that follows
 # them, so keep all top-level options above this line.
 #
@@ -69,8 +79,10 @@ include_mail = false
 # for pages that are perfectly fine. That produced the false positives in
 # https://github.com/sei-protocol/sei-docs/issues/77. lychee does not retry a
 # 503, and the GITHUB_TOKEN API fallback can only validate bare owner/repo URLs
-# (not blob/tree paths), so the fix is to slow down instead. Measured cost:
-# ~80 GitHub requests at one per second adds about 40 seconds to the weekly run.
+# (not blob/tree paths), so slowing down is what keeps 503s rare. It does not
+# stop them entirely, which is why external-links.yml re-checks every failure
+# before reporting it. Measured cost: with blob links remapped above, ~45
+# github.com requests at one per second keep the full run under a minute.
 [hosts."github.com"]
 concurrency = 2
 request_interval = "1s"