EXP-2127: Cover content JSX images and frontmatter banners for subpath deploys

Literal <img> JSX written inside Markdown/MDX content bypasses the
MDXComponents mapping entirely (MDX v3 semantics), so the previous
MDXImg fix never saw it. Add a rehype plugin that rewrites absolute
img srcs at compile time, wired into the docs and blog pipelines; it
no-ops in production where baseUrl is "/".

Also make PageHeader (frontmatter banner_image/banner_icon) and
Clients (client logo paths) baseUrl-aware, the remaining components
that received absolute asset paths as props.

A clean subpath build now has zero unprefixed /img and /logos srcs
across the output (was 127).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: pmckinney-codat

docusaurus.config.js

@@ -80,6 +80,7 @@ import navbar from "./nav.config";
 import redirects from "./redirects.config";
 
 import { generateAPISitemaps } from "./src/utils/oas-sitemap.js";
+import rehypeImageBaseUrl from "./src/utils/rehype-image-base-url.js";
 
 // PR preview deploys serve the site from a subpath on GitHub Pages, so the
 // preview workflow overrides this. No trailing slash — baseUrl appends one.
@@ -131,6 +132,7 @@ const config = {
           routeBasePath: "/",
           sidebarPath: "./sidebars.js",
           editUrl: `https://github.com/codatio/codat-docs/edit/${process.env?.BRANCH || "main"}/`,
+          rehypePlugins: [[rehypeImageBaseUrl, { baseUrl: `${BASE_URL}/` }]],
           exclude: ["README.md"],
           lastVersion: "current",
           versions: {
@@ -142,6 +144,7 @@ const config = {
         },
         blog: {
           showReadingTime: true,
+          rehypePlugins: [[rehypeImageBaseUrl, { baseUrl: `${BASE_URL}/` }]],
           blogTitle: "Codat updates",
           blogDescription: "Engineering and product updates from Codat.",
           postsPerPage: 10,

src/components/Clients/index.js

@@ -1,14 +1,18 @@
 import React from "react";
+import { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
 
 import styles from "./styles.module.scss";
 
 const Client = (props) => {
   const { path, name, scale } = props;
+  // Callers pass absolute /img/ paths, which bypass baseUrl and break
+  // deploys served from a subpath (e.g. PR previews)
+  const { withBaseUrl } = useBaseUrlUtils();
 
   return (
     <div className={styles.client}>
       <img
-        src={path}
+        src={withBaseUrl(path)}
         alt={`${name} logo`}
         style={
           scale

src/components/PageHeader/index.js

@@ -1,6 +1,7 @@
 import React from "react";
 import clsx from "clsx";
 import { useColorMode } from "@docusaurus/theme-common";
+import { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
 
 import { ModalController } from "../Modal";
 
@@ -35,7 +36,12 @@ const PageHeader = ({
   videoText,
 }) => {
   const { colorMode } = useColorMode();
-  const resolvedIcon = iconDark && colorMode === "dark" ? iconDark : icon;
+  // icon/img arrive as absolute paths from frontmatter (banner_image etc.),
+  // which bypass baseUrl and break deploys served from a subpath
+  const { withBaseUrl } = useBaseUrlUtils();
+  const resolvedIcon = withBaseUrl(
+    iconDark && colorMode === "dark" ? iconDark : icon,
+  );
 
   return (
     <div className={clsx(styles.wrapper, className)}>
@@ -62,7 +68,7 @@ const PageHeader = ({
         {videoUrl && <BannerVideo text={videoText} url={videoUrl} />}
       </div>
 
-      {img && <img src={img} className={styles.heroImg} alt="" />}
+      {img && <img src={withBaseUrl(img)} className={styles.heroImg} alt="" />}
     </div>
   );
 };

src/utils/rehype-image-base-url.js

@@ -0,0 +1,40 @@
+// Literal <img> JSX written inside Markdown/MDX content bypasses the
+// MDXComponents mapping (and with it useBaseUrl), so absolute src paths
+// break when the site is served from a subpath (e.g. PR previews, where
+// baseUrl is /codat-docs/pr-preview/pr-<n>/). Rewrites those srcs at
+// compile time instead; a no-op for production builds, where baseUrl is "/".
+const rehypeImageBaseUrl = ({ baseUrl }) => {
+  const prefix = (src) =>
+    typeof src === "string" && src.startsWith("/") && !src.startsWith("//")
+      ? baseUrl + src.slice(1)
+      : src;
+
+  const visit = (node) => {
+    if (node.type === "element" && node.tagName === "img" && node.properties) {
+      node.properties.src = prefix(node.properties.src);
+    }
+
+    if (
+      (node.type === "mdxJsxFlowElement" ||
+        node.type === "mdxJsxTextElement") &&
+      node.name === "img"
+    ) {
+      for (const attr of node.attributes ?? []) {
+        if (attr.type === "mdxJsxAttribute" && attr.name === "src") {
+          attr.value = prefix(attr.value);
+        }
+      }
+    }
+
+    (node.children ?? []).forEach(visit);
+  };
+
+  return (tree) => {
+    if (!baseUrl || baseUrl === "/") {
+      return;
+    }
+    visit(tree);
+  };
+};
+
+export default rehypeImageBaseUrl;