Implement DocImage component to handle <img> tags with ImageZoom and prepend basePath in rehype plugin

Author: cklei-carly

mdx-components.tsx

@@ -139,6 +139,42 @@ const mdxComponents = {
   Tab,
   Check,
   Cross: X,
+  // DocImage is used by the rehypeDocImage plugin which renames explicit <img> JSX tags
+  // to <DocImage> so they go through this components map and get ImageZoom wrapping.
+  // The src it receives already has basePath prepended by the rehype plugin.
+  DocImage: (props: any) => {
+    const src = typeof props.src === 'object' && props.src !== null && 'src' in props.src ? props.src.src : props.src;
+
+    if (
+      !src ||
+      (typeof src === 'string' && (
+        src.endsWith('.svg') ||
+        src.startsWith('data:') ||
+        src.includes('img.shields.io')
+      ))
+    ) {
+      return <img {...props} src={src} />;
+    }
+
+    const defaultHeight = 300;
+    const defaultWidth = 700;
+    const width = props.width ? (typeof props.width === 'number' ? props.width : parseInt(props.width) || defaultWidth) : defaultWidth;
+    const height = props.height ? (typeof props.height === 'number' ? props.height : parseInt(props.height) || defaultHeight) : defaultHeight;
+
+    console.debug('Rendering DocImage with src:', src, 'width:', width, 'height:', height);
+    
+    return (
+      <ImageZoom
+        src={src}
+        alt={props.alt || ''}
+        height={height}
+        width={width}
+        // unoptimized
+        loading="lazy"
+        className="rounded-lg"
+      />
+    );
+  },
   img: (props: any) => {
     // Resolve src if it's an object (static import)
     const src = typeof props.src === 'object' && props.src !== null && 'src' in props.src ? props.src.src : props.src;

source.config.ts

@@ -19,16 +19,20 @@ export const docs = defineDocs({
   },
 });
 
-// Rehype plugin that prepends basePath to local <img src="/..."> paths.
-// In MDX, <img> tags are parsed as JSX (mdxJsxFlowElement / mdxJsxTextElement),
-// NOT as rehype `element` nodes. Their attributes live in node.attributes[],
-// not node.properties — so we must handle both node types.
-function rehypePrependBasePath() {
+// Rehype plugin for local <img src="/..."> tags in MDX files.
+//
+// Problem: In MDX, explicit <img> JSX tags are compiled as React.createElement('img', ...)
+// and do NOT reliably go through the components map (unlike Markdown ![]() images).
+// This means the `img` override in mdx-components.tsx is never called for them.
+//
+// Solution: Rename those nodes to <DocImage> (uppercase). Uppercase components ARE always
+// resolved from the components context, so DocImage in mdx-components.tsx will be called.
+// We also prepend basePath here since Next.js <Image> does NOT do it automatically —
+// the src must already include basePath before being passed to next/image.
+function rehypeDocImage() {
   const basePath =
     process.env.NEXT_PUBLIC_BASE_PATH ||
     (process.env.NODE_ENV === 'production' ? '/plugins-doc-site' : '');
- 
-  if (!basePath) return (tree: any) => tree;
 
   function walk(node: any) {
     // MDX JSX nodes: mdxJsxFlowElement / mdxJsxTextElement
@@ -37,29 +41,32 @@ function rehypePrependBasePath() {
       node.name === 'img' &&
       Array.isArray(node.attributes)
     ) {
+      // Rename to DocImage so the components map entry is used (enabling ImageZoom)
+      node.name = 'DocImage';
+
+      // Prepend basePath to local src paths
       for (const attr of node.attributes) {
         if (
           attr.type === 'mdxJsxAttribute' &&
           attr.name === 'src' &&
           typeof attr.value === 'string'
         ) {
           const src: string = attr.value;
-          if (src.startsWith('/') && !src.startsWith('//') && !src.startsWith(basePath)) {
+          if (basePath && src.startsWith('/') && !src.startsWith('//') && !src.startsWith(basePath)) {
             attr.value = basePath + src;
-            console.debug('MDX img src after basePath:', attr.value);
           }
         }
       }
     }
 
-    // Standard rehype element nodes (fallback)
+    // Standard rehype element nodes (fallback for any genuine HTML <img> nodes)
     if (
       node.type === 'element' &&
       node.tagName === 'img' &&
       typeof node.properties?.src === 'string'
     ) {
       const src: string = node.properties.src;
-      if (src.startsWith('/') && !src.startsWith('//') && !src.startsWith(basePath)) {
+      if (basePath && src.startsWith('/') && !src.startsWith('//') && !src.startsWith(basePath)) {
         node.properties.src = basePath + src;
       }
     }
@@ -78,6 +85,6 @@ export default defineConfig({
       external: false, // Disable fetching external image sizes
     },
     remarkPlugins: [],
-    rehypePlugins: [rehypePrependBasePath],
+    rehypePlugins: [rehypeDocImage],
   },
 });