Serve images from Cloudflare R2 instead of the repo

.gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!scripts/.env.publish-image.example
 
 # vercel
 .vercel

README.md

@@ -7,6 +7,9 @@ Documentation site for [Cube AI](https://github.com/ultravioletrs/cube), served
 
 Built with [Next.js](https://nextjs.org) and [Fumadocs](https://fumadocs.dev), deployed to Cloudflare Workers as a static export nested under `/docs/cube-ai/`.
 
+Images are served from a shared Cloudflare R2 bucket rather than committed to the repo —
+see [`scripts/README.md`](./scripts/README.md).
+
 ## Development
 
 ```bash
@@ -49,18 +52,22 @@ lib/
   metadata.ts         # createMetadata helper
   source.ts           # Fumadocs source loader
 public/
-  img/                # Images referenced by docs
   _headers            # Cloudflare cache headers
   _redirects          # Cloudflare redirects
   robots.txt
 scripts/
   nest-static-export.mjs  # Post-build: nest out/ under docs/cube-ai/
-wrangler.jsonc        # Cloudflare Workers config
+  publish-image.mjs       # Maintainer-only: upload an image to R2 + purge cache
+worker/
+  index.ts             # Cloudflare Worker (main): serves /img/... from R2, else static assets
+  r2-proxy.ts           # Shared R2 lookup + streaming logic
+wrangler.jsonc        # Cloudflare Workers config (assets + Worker + R2 binding)
 biome.json            # Linter / formatter (Biome)
 ```
 
 ## Tooling
 
 - **Linter / Formatter**: [Biome](https://biomejs.dev)
-- **Deployment**: Cloudflare Workers (static assets via `wrangler deploy`)
+- **Deployment**: Cloudflare Workers (static assets + a small Worker for the R2-backed
+  image route, via `wrangler deploy`)
 - **CI**: GitHub Actions — lint → type check → build

mdx-components.tsx

@@ -1,22 +1,41 @@
+import { ImageZoom } from "fumadocs-ui/components/image-zoom";
 import defaultMdxComponents from "fumadocs-ui/mdx";
 import type { MDXComponents } from "mdx/types";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ComponentPropsWithoutRef } from "react";
 import { Mermaid } from "@/components/mdx/mermaid";
 import { assetPath } from "@/lib/base-path";
+import { cn } from "@/lib/utils";
 
-const DefaultImage = defaultMdxComponents.img as
-  | ((props: ComponentPropsWithoutRef<"img">) => ReactNode)
-  | undefined;
-
+// Doc content images (content/docs/**/*.mdx) are served from the shared
+// Cloudflare R2 bucket, not committed to this repo (see scripts/README.md),
+// so fumadocs-mdx's static-import-based width/height inference is disabled
+// (source.config.ts: remarkImageOptions: false) - it requires the file on
+// disk at build time, which doesn't hold here. Rendered as a plain,
+// zoomable <img> -- no next/image, no width/height needed, so there's
+// nothing to keep in sync when images change.
 export function getMDXComponents(components?: MDXComponents): MDXComponents {
   return {
     ...defaultMdxComponents,
-    img: (props) => {
-      const src =
-        typeof props.src === "string" ? assetPath(props.src) : props.src;
+    img: (props: ComponentPropsWithoutRef<"img">) => {
+      const { src: rawSrc, alt, className } = props;
+      if (typeof rawSrc !== "string") return null;
+
+      const src = assetPath(rawSrc);
 
-      if (DefaultImage) return <DefaultImage {...props} src={src} />;
-      return null;
+      return (
+        // src/alt passed here too, not just to the inner <img>: ImageZoom's
+        // zoomed-in view reads its image from these props directly, not
+        // from `children`.
+        <ImageZoom src={src} alt={alt ?? ""}>
+          {/* biome-ignore lint/performance/noImgElement: doc content images are served from R2, not Next's image pipeline */}
+          <img
+            src={src}
+            alt={alt ?? ""}
+            loading="lazy"
+            className={cn("rounded-lg", className)}
+          />
+        </ImageZoom>
+      );
     },
     Mermaid,
     ...components,

package.json

@@ -13,7 +13,8 @@
     "lint": "biome check",
     "format": "biome format --write",
     "lint:fix": "biome check --write",
-    "lint:md": "markdownlint --disable MD013 MD033 MD007 MD029 MD059 MD024 MD025 -- content/docs"
+    "lint:md": "markdownlint --disable MD013 MD033 MD007 MD029 MD059 MD024 MD025 -- content/docs",
+    "publish-image": "node scripts/publish-image.mjs"
   },
   "dependencies": {
     "@orama/orama": "^3.1.18",

scripts/.env.publish-image.example

@@ -0,0 +1,10 @@
+# Copy to scripts/.env.publish-image (gitignored) and fill in the token.
+# Create the token under My Profile -> API Tokens -> Create Token -> Custom Token, with:
+#   - Workers R2 Storage: Edit
+#   - Zone -> Cache Purge -> Purge (scoped to the ultraviolet.rs zone)
+CLOUDFLARE_API_TOKEN=
+
+# Not secret - the ultraviolet.rs zone ID. Confirmed via a live Cloudflare
+# API lookup while migrating the sibling ultraviolet/website repo; reused
+# here since this site is served under the same domain/zone.
+CLOUDFLARE_ZONE_ID=cbb18a791e53fb24efbeb169e48634df