From 36cc0b43623c210fb0c1b03bcc6abf24da9b464b Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Mon, 20 Jul 2026 10:53:56 +0800
Subject: [PATCH] fix(site): make docs build resilient to remote badge fetch
 failures (#2695)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`Build Docs` (@object-ui/site#build) runs fumadocs' remark-image plugin,
which fetches every remote image at build time to inline its width/height.
For remote badges (shields.io / skills.sh) this turns an external service's
availability into a hard build dependency: a shields.io hiccup (Cloudflare
520 / 1200 "Too many requests") throws and fails the entire docs build,
unrelated to the PR under test (observed on #2684).

Configure remark-image via source.config.ts:
- external: { timeout: 10_000 } — bound each remote fetch so a hung
  connection can't stall CI.
- onError — warn (don't fail the build) when a remote image can't be sized,
  while re-throwing for local/authored images so broken in-repo paths stay
  fatal.

The only live remote badge triggering a build-time fetch is the skills.sh
badge in content/docs/guide/agent-skills.md; the shields.io references live
inside code fences and are never fetched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/site/source.config.ts | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/apps/site/source.config.ts b/apps/site/source.config.ts
index 8b5c7c1ba..93e104db2 100644
--- a/apps/site/source.config.ts
+++ b/apps/site/source.config.ts
@@ -17,6 +17,27 @@ export const docs = defineDocs({
 
 export default defineConfig({
   mdxOptions: {
-    // MDX options
+    // `remark-image` probes every image at build time to inline width/height.
+    // For remote images (e.g. shields.io / skills.sh badges) that is a
+    // build-time network fetch, which turns an external service's availability
+    // into a hard build dependency: a shields.io hiccup (Cloudflare 520 / 1200
+    // "Too many requests") would otherwise fail the entire docs build. Make the
+    // build resilient to remote-image outages. See objectui#2695.
+    remarkImageOptions: {
+      // Bound each remote fetch so a hung connection can't stall CI.
+      external: { timeout: 10_000 },
+      // Warn (don't fail the build) when a remote image can't be sized, but keep
+      // strict behaviour for local/authored images so broken in-repo paths are
+      // still caught. Note: in the Next.js bundler pipeline local images resolve
+      // via `import` and never reach here — this guard only matters if that ever
+      // changes, at which point local failures must still be fatal.
+      onError: (error) => {
+        if (/https?:\/\//.test(error.message)) {
+          console.warn(`[remark-image] skipped remote image (build continues): ${error.message}`);
+          return;
+        }
+        throw error;
+      },
+    },
   },
 });