feat(docs): support custom locally hosted icons in Card and Icon components (#5423)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Catherine Deskur <catherine@buildwithfern.com>
Co-authored-by: Catherine Deskur <46695336+chdeskur@users.noreply.github.com>

Author: devin-ai-integration[bot]

packages/fern-docs/bundle/src/mdx/components/card/Card.tsx

@@ -3,7 +3,9 @@ import { NoZoom } from "@fern-docs/components/contexts/NoZoom";
 import { DisableFernAnchor } from "@fern-docs/components/FernAnchor";
 import { FernCard } from "@fern-docs/components/FernCard";
 import { FernImage } from "@fern-docs/components/FernImage";
+import { FernSvgIcon } from "@fern-docs/components/FernSvgIcon";
 import { FaIcon } from "@fern-docs/components/fa-icon";
+import { processIconString } from "@fern-docs/components/util/processIconString";
 import { isValidElement } from "react";
 import { FernLinkCard } from "@/components/FernLinkCard";
 
@@ -79,6 +81,35 @@ export const Card: React.FC<Card.Props> = ({
         }
     }
 
+    const renderIcon = () => {
+        if (typeof icon === "string") {
+            return processIconString({
+                icon,
+                className: "card-icon",
+                renderFaIcon: (faIcon) => <FaIcon className="card-icon" icon={faIcon} />,
+                renderUrlIcon: (url, isSvg) =>
+                    isSvg ? (
+                        <NoZoom>
+                            <FernSvgIcon src={url} alt="" className="card-icon" />
+                        </NoZoom>
+                    ) : (
+                        <NoZoom>
+                            <FernImage src={url} alt="" className="card-icon" />
+                        </NoZoom>
+                    ),
+                wrap: (content) => <NoZoom>{content}</NoZoom>
+            });
+        }
+        if (isValidElement(icon)) {
+            return (
+                <span className="card-icon">
+                    <NoZoom>{icon}</NoZoom>
+                </span>
+            );
+        }
+        return null;
+    };
+
     const cardContent = (
         <>
             {badge != null && (
@@ -105,13 +136,7 @@ export const Card: React.FC<Card.Props> = ({
             }
           `}
                 </style>
-                {typeof icon === "string" ? (
-                    <FaIcon className="card-icon" icon={icon} />
-                ) : isValidElement(icon) ? (
-                    <span className="card-icon">
-                        <NoZoom>{icon}</NoZoom>
-                    </span>
-                ) : null}
+                {renderIcon()}
                 <div className="w-full space-y-1 overflow-hidden">
                     <div className="text-body text-base font-semibold">{title}</div>
                     {children != null && <div className="text-(color:--grayscale-a11)">{children}</div>}

packages/fern-docs/bundle/src/mdx/components/icon/Icon.tsx

@@ -1,5 +1,8 @@
 import { cn } from "@fern-docs/components/cn";
+import { FernImage } from "@fern-docs/components/FernImage";
+import { FernSvgIcon } from "@fern-docs/components/FernSvgIcon";
 import { FaIcon } from "@fern-docs/components/fa-icon";
+import { processIconString } from "@fern-docs/components/util/processIconString";
 
 export function Icon({
     className,
@@ -10,24 +13,60 @@ export function Icon({
     lightModeColor
 }: {
     className?: string; // you must specify the bg-color rather than text-color because this is a mask.
-    icon?: string; // e.g. "fas fa-home", or simply "home"
+    icon?: string; // e.g. "fas fa-home", or simply "home", or a URL (file: references are resolved by rehype-files)
     color?: string; // ignored if lightModeColor and darkModeColor are set
     darkModeColor?: string;
     lightModeColor?: string;
     size?: number; // size in 0.25rem increments. default is 4.
 }) {
+    const sizeInPixels = size * 4;
+
+    if (typeof icon !== "string" || !icon) {
+        return null;
+    }
+
     return (
-        <FaIcon
-            className={cn(className, "fern-mdx-icon")}
-            icon={icon ?? ""}
-            style={
-                {
-                    color: lightModeColor ?? color,
-                    "--fa-icon-dark": darkModeColor ?? color,
-                    width: size * 4,
-                    height: size * 4
-                } as React.CSSProperties
-            }
-        />
+        processIconString({
+            icon,
+            className: cn(className, "fern-mdx-icon"),
+            renderFaIcon: (faIcon) => (
+                <FaIcon
+                    className={cn(className, "fern-mdx-icon")}
+                    icon={faIcon}
+                    style={
+                        {
+                            color: lightModeColor ?? color,
+                            "--fa-icon-dark": darkModeColor ?? color,
+                            width: sizeInPixels,
+                            height: sizeInPixels
+                        } as React.CSSProperties
+                    }
+                />
+            ),
+            renderUrlIcon: (url, isSvg) =>
+                isSvg ? (
+                    <span
+                        className={cn(className, "fern-mdx-icon")}
+                        style={{
+                            width: sizeInPixels,
+                            height: sizeInPixels,
+                            display: "inline-block"
+                        }}
+                    >
+                        <FernSvgIcon src={url} alt="" />
+                    </span>
+                ) : (
+                    <FernImage
+                        src={url}
+                        alt=""
+                        className={cn(className, "fern-mdx-icon")}
+                        style={{
+                            width: sizeInPixels,
+                            height: sizeInPixels
+                        }}
+                    />
+                ),
+            wrap: (content) => <>{content}</>
+        }) ?? null
     );
 }

packages/fern-docs/bundle/src/mdx/plugins/rehype-files.ts

@@ -56,40 +56,50 @@ export const rehypeFiles: Unified.Plugin<[RehypeFilesOptions?], Hast.Root> = ({
 
                 // TODO: do we need to add support for `href` and `<object data=...>`?
                 const srcAttribute = attributes.find((attr) => attr.name === "src");
+                const iconAttribute = attributes.find((attr) => attr.name === "icon");
 
                 // TODO: handle more gracefully, temporary fix for jambonz
                 const playsInlineAttribute = attributes.find((attr) => attr.name === "playsinline");
                 if (playsInlineAttribute) {
                     playsInlineAttribute.name = "playsInline";
                 }
 
-                if (srcAttribute == null) {
-                    return;
-                }
+                // Handle src attribute
+                if (srcAttribute != null) {
+                    const src = mdxJsxAttributeToString(srcAttribute);
+                    if (!src) {
+                        console.warn(`[rehype-files]: src attribute is not parseable for ${node.name}`);
+                    } else {
+                        const { src: newSrc, height, width, blurDataURL } = replaceSrc?.(src, node.name) ?? {};
 
-                const src = mdxJsxAttributeToString(srcAttribute);
-                if (!src) {
-                    console.warn(`[rehype-files]: src attribute is not parseable for ${node.name}`);
-                    return;
-                }
-                const { src: newSrc, height, width, blurDataURL } = replaceSrc?.(src, node.name) ?? {};
+                        if (newSrc != null) {
+                            srcAttribute.value = newSrc;
+                        }
 
-                if (newSrc != null) {
-                    srcAttribute.value = newSrc;
+                        setDimension(node, attributes, width, height);
+
+                        if (
+                            blurDataURL &&
+                            node.name?.toLowerCase().startsWith("im") &&
+                            !attributes.find((attr) => attr.name === "blurDataURL")
+                        ) {
+                            node.attributes.unshift({
+                                name: "blurDataURL",
+                                value: blurDataURL,
+                                type: "mdxJsxAttribute"
+                            });
+                        }
+                    }
                 }
 
-                setDimension(node, attributes, width, height);
-
-                if (
-                    blurDataURL &&
-                    node.name?.toLowerCase().startsWith("im") &&
-                    !attributes.find((attr) => attr.name === "blurDataURL")
-                ) {
-                    node.attributes.unshift({
-                        name: "blurDataURL",
-                        value: blurDataURL,
-                        type: "mdxJsxAttribute"
-                    });
+                if (iconAttribute != null) {
+                    const icon = mdxJsxAttributeToString(iconAttribute);
+                    if (icon?.startsWith("file:")) {
+                        const { src: newSrc } = replaceSrc?.(icon, node.name) ?? {};
+                        if (newSrc != null) {
+                            iconAttribute.value = newSrc;
+                        }
+                    }
                 }
             } else if (node.type === "element") {
                 // TODO: do we need to add support for `href` and `<object data=...>`?

packages/fern-docs/components/src/FernSvgIcon.tsx

@@ -46,5 +46,5 @@ export const FernSvgIcon: React.FC<FernSvgIconProps> = ({ src, alt, className })
         return <span className={className} />;
     }
 
-    return <span dangerouslySetInnerHTML={{ __html: modifiedSvgContent }} />;
+    return <span className={className} dangerouslySetInnerHTML={{ __html: modifiedSvgContent }} />;
 };

packages/fern-docs/components/src/FernSvgIconServer.tsx

@@ -35,7 +35,7 @@ async function FernSvgIconServerInternal({ src, alt, className }: FernSvgIconSer
             }
         }
 
-        return <span dangerouslySetInnerHTML={{ __html: modifiedSvgContent }} />;
+        return <span className={className} dangerouslySetInnerHTML={{ __html: modifiedSvgContent }} />;
     } catch (error) {
         console.error(`[FernSvgIconServer] Failed to fetch SVG: ${src}`, error);
         // Fallback to Next.js Image on error

packages/fern-docs/components/src/util/processIconString.tsx

@@ -9,21 +9,31 @@ export interface ProcessIconStringOptions {
     className?: string;
     renderFaIcon: (icon: string) => ReactNode;
     wrap?: (content: ReactNode) => ReactNode;
+    renderUrlIcon?: (url: string, isSvg: boolean) => ReactNode;
+}
+
+function isUrlIcon(icon: string): boolean {
+    return icon.startsWith("http://") || icon.startsWith("https://") || icon.startsWith("/");
+}
+
+function isSvgUrl(url: string): boolean {
+    return url.toLowerCase().endsWith(".svg");
 }
 
 export const processIconString = ({
     icon,
     files,
     className = "size-5",
     renderFaIcon,
-    wrap = (content) => content
+    wrap = (content) => content,
+    renderUrlIcon
 }: ProcessIconStringOptions): ReactNode | undefined => {
     if (icon.startsWith("file:")) {
         const fileId = icon.slice(5);
         const fileData = files?.[fileId];
 
         if (fileData) {
-            if (fileData.src.endsWith(".svg")) {
+            if (fileData.src.toLowerCase().endsWith(".svg")) {
                 return wrap(<FernSvgIcon src={fileData.src} alt={fileData.alt ?? ""} className={className} />);
             }
 
@@ -42,6 +52,10 @@ export const processIconString = ({
         return undefined;
     }
 
+    if (renderUrlIcon && isUrlIcon(icon)) {
+        return wrap(renderUrlIcon(icon, isSvgUrl(icon)));
+    }
+
     if (icon.startsWith("<") && icon.endsWith(">")) {
         return wrap(<span className={className} dangerouslySetInnerHTML={{ __html: icon }} />);
     }