Enhance Markdown components to support eager loading for the first image

Author: LadyBluenotes

src/components/markdown/Markdown.tsx

@@ -13,33 +13,41 @@ import {
 
 type MarkdownRenderOptions = {
   preserveTabPanels?: boolean
+  eagerFirstImage?: boolean
 }
 
 export type MarkdownProps = {
   content?: string
   document?: MarkdownDocument
   preserveTabPanels?: boolean
+  /** Render the first image in the document as high-priority/eager (e.g. blog post hero images) */
+  eagerFirstImage?: boolean
 }
 
 export function Markdown({
   content,
   document,
   preserveTabPanels,
+  eagerFirstImage,
 }: MarkdownProps) {
   const parsed = React.useMemo(
     () => document ?? parseSiteMarkdown(content ?? ''),
     [content, document],
   )
+  const heroConsumedRef = React.useRef(false)
+  heroConsumedRef.current = false
 
   return React.useMemo(() => {
     return renderMarkdownReact(parsed, {
       allowHtml: true,
       components: createMarkdownComponents({
         preserveTabPanels,
+        eagerFirstImage,
+        heroConsumedRef,
       }),
       headingAnchors,
     })
-  }, [parsed, preserveTabPanels])
+  }, [parsed, preserveTabPanels, eagerFirstImage])
 }
 
 const headingAnchors = {
@@ -160,7 +168,11 @@ function TableElement({
   )
 }
 
-function createMarkdownComponents(options: MarkdownRenderOptions = {}) {
+function createMarkdownComponents(
+  options: MarkdownRenderOptions & {
+    heroConsumedRef?: React.RefObject<boolean>
+  } = {},
+) {
   function MdCommentComponentWithOptions(
     props: React.ComponentProps<typeof MdCommentComponent>,
   ) {
@@ -172,6 +184,18 @@ function createMarkdownComponents(options: MarkdownRenderOptions = {}) {
     )
   }
 
+  function ImgElement(props: React.ComponentProps<typeof MarkdownImg>) {
+    const heroConsumedRef = options.heroConsumedRef
+    const isFirstImage =
+      options.eagerFirstImage && heroConsumedRef && !heroConsumedRef.current
+
+    if (isFirstImage) {
+      heroConsumedRef.current = true
+    }
+
+    return <MarkdownImg {...props} priority={isFirstImage} />
+  }
+
   return {
     a: LinkElement,
     code: CodeElement,
@@ -184,7 +208,7 @@ function createMarkdownComponents(options: MarkdownRenderOptions = {}) {
     h5: createHeadingComponent('h5'),
     h6: createHeadingComponent('h6'),
     iframe: MarkdownIframe,
-    img: MarkdownImg,
+    img: ImgElement,
     'md-comment-component': MdCommentComponentWithOptions,
     'md-framework-panel': MdFrameworkPanel,
     'md-tab-panel': MdTabPanel,

src/components/markdown/MarkdownContent.tsx

@@ -33,6 +33,8 @@ type MarkdownContentProps = {
   pagePath?: string
   /** Current framework for filtering markdown content */
   currentFramework?: string
+  /** Render the first image in the document as high-priority/eager (e.g. blog post hero images) */
+  eagerFirstImage?: boolean
 }
 
 function CopyPageDropdownFallback() {
@@ -76,6 +78,7 @@ export function MarkdownContent({
   libraryVersion,
   pagePath,
   currentFramework,
+  eagerFirstImage,
 }: MarkdownContentProps) {
   const [canLoadCopyControls, setCanLoadCopyControls] = React.useState(false)
 
@@ -84,7 +87,11 @@ export function MarkdownContent({
   }, [])
 
   const renderedMarkdown = (
-    <Markdown document={markdown} preserveTabPanels={preserveTabPanels} />
+    <Markdown
+      document={markdown}
+      preserveTabPanels={preserveTabPanels}
+      eagerFirstImage={eagerFirstImage}
+    />
   )
 
   const contentNode =

src/routes/blog.$.tsx

@@ -182,6 +182,7 @@ function BlogPost() {
                         branch={branch}
                         filePath={filePath}
                         containerRef={markdownContainerRef}
+                        eagerFirstImage
                       />
                     </div>
                     {isTocVisible && (

src/ui/MarkdownImg.tsx

@@ -5,16 +5,21 @@ import { getPublicImageDimensions } from '~/utils/publicImageDimensions'
 
 const DEFAULT_TRANSFORM_WIDTH = 1200
 
+export type MarkdownImgProps = HTMLProps<HTMLImageElement> & {
+  priority?: boolean
+}
+
 export const MarkdownImg = React.memo(function MarkdownImg({
   alt,
   src,
   className,
   width,
   height,
   style,
+  priority,
   children: _,
   ...props
-}: HTMLProps<HTMLImageElement>) {
+}: MarkdownImgProps) {
   const sourceDimensions = src ? getPublicImageDimensions(src) : undefined
   const providedWidth = parseDimension(width)
   const providedHeight = parseDimension(height)
@@ -64,7 +69,8 @@ export const MarkdownImg = React.memo(function MarkdownImg({
         ...style,
       }}
       className={`block max-w-full h-auto rounded-lg shadow-md ${className ?? ''}`}
-      loading="lazy"
+      loading={priority ? 'eager' : 'lazy'}
+      fetchPriority={priority ? 'high' : undefined}
       decoding="async"
     />
   )