MDX Notes
HubMDX vs Markdown: A Detailed ComparisonWhat is MDX?Why Use MDX? Benefits and Use CasesCreate Your First MDX FileInstalling MDX - Complete Setup GuideMDX Project Structure - Organizing Your Content and ComponentsBlockquotes in MDXCode Blocks in MDXHeadings in MDXImages in MDXLinks in MDXLists in MDXParagraphs in MDXTables in MDXText Formatting in MDXFrontmatter BasicsDocument Metadata in MDXPage Configuration via FrontmatterSEO Fields in FrontmatterBuilding an Accordion/Collapsible ComponentBuilding an Alert/Admonition ComponentBuilding a Card ComponentCreating Custom Components for MDXBuilding a Tabs ComponentInteractive Documentation with MDXMDX LayoutsMDX PluginsPerformance Optimization for MDXReusable Content in MDXSyntax Highlighting in MDXAdmonitions in DocusaurusCode Tabs and CodeBlock in DocusaurusMDX in DocusaurusSidebar Configuration in DocusaurusTabs Component in DocusaurusDocument Versioning in DocusaurusAccessibility in MDXCommon MDX Mistakes and FixesSEO Optimization for MDX ContentMDX Writing Style GuideUsers API - Create UserGetting Started with React in 2024useTheme HookAlex Rivera - Full-Stack Developer & DesignerComplete MDX CheatsheetFurther Reading and MDX ResourcesMDX Interview Questions and AnswersTools for MDX DevelopmentDynamic Content in MDXExporting Variables in MDXImporting Components in MDXJSX Basics in MDXPassing Props in MDXReact Components in MDXMDX Learning RoadmapSetting Up MDX with Next.jsBuilding a Blog with Next.js and MDXCustom Components in Next.js MDXSEO with MDX in Next.js
How to add images in MDX — the syntax, writing good alt text, handling paths, responsive images, and building reusable image components.
You'll use images all the time in docs — screenshots, diagrams, logos. MDX gives you the simple Markdown image syntax, plus the ability to use <img> tags and custom React components when you need more control.
Basic Image Syntax
Here's the standard Markdown way:
Example
Want a tooltip on hover? Add a title:
Example
A Few Real Examples
Example
Alt Text — Why It Matters
Alt text isn't optional. Screen readers depend on it. It also shows up when images fail to load. Write it like you're describing the image to someone on the phone.
Good vs. Bad Alt Text
Example
{/* ❌ BAD — Non-descriptive */}
{/* ✅ GOOD — Descriptive and meaningful */}
Rules of Thumb
- Be specific — Describe what's actually in the image
- Keep it under 125 characters — Don't write a novel
- Don't say "image of" or "picture of" — Screen readers already say it's an image
- Match the context — Describe what's relevant to the surrounding text
- Decorative images — If it's just decoration, use empty alt:
!
Image Paths
Relative Paths
Example
{/* Same directory */}
{/* Subdirectory */}
{/* Parent directory */}
Absolute Paths
Example
{/* From project root (public folder) */}
{/* External URL */}
Importing Images (Framework-Specific)
Some frameworks (like Next.js) want you to import images so they can optimize them at build time:
Example
import heroImage from './images/hero.png'
import diagram from '../assets/diagram.svg'
{/* Or using an img tag */}
<img src={heroImage} alt="Hero section background" />
Responsive Images
Setting Width and Height
Always set dimensions. It prevents that annoying layout jump when the image loads:
mdx example
<img
src="./screenshot.png"
alt="Application screenshot"
width={800}
height={450}
style={{ maxWidth: '100%', height: 'auto' }}
/>CSS Class Approach
mdx example
<img
src="./diagram.png"
alt="System architecture diagram"
className="responsive-image"
/>
{/* Where CSS defines: .responsive-image { max-width: 100%; height: auto; } */}Art Direction with <picture>
Show different images at different screen sizes — like a detailed image on desktop and a cropped version on mobile:
mdx example
<picture>
<source media="(min-width: 768px)" srcSet="./hero-desktop.png" />
<source media="(min-width: 480px)" srcSet="./hero-tablet.png" />
<img src="./hero-mobile.png" alt="Product showcase" />
</picture>Srcset for Resolution Switching
Let the browser pick the right size based on viewport:
mdx example
<img
src="./photo.jpg"
srcSet="./photo-400w.jpg 400w, ./photo-800w.jpg 800w, ./photo-1200w.jpg 1200w"
sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
alt="High-resolution product photo"
/>Image Components
Basic Image Component
mdx example
import { Image } from '../components/Image'
<Image
src="./screenshot.png"
alt="Dashboard overview showing analytics widgets"
width={800}
height={450}
/>Next.js Image Component
Next.js has its own Image component that handles optimization automatically:
mdx example
import Image from 'next/image'
<Image
src="/images/hero.png"
alt="Landing page hero illustration"
width={1200}
height={600}
priority
/>Override All Images Globally
You can make every !alt in your MDX files automatically use your custom component:
Example
// mdx-components.js
import { OptimizedImage } from './components/OptimizedImage'
export function useMDXComponents(components) {
return {
img: (props) => <OptimizedImage {...props} />,
...components,
}
}
Now every Markdown image gets optimized without changing any MDX files.
Lazy Loading
Don't load images the user hasn't scrolled to yet. It makes your page faster.
Native Lazy Loading
The simplest approach — just add loading="lazy":
mdx example
<img
src="./large-diagram.png"
alt="Complex system diagram"
loading="lazy"
width={1000}
height={600}
/>With a Custom Component
For more control (like blur-up placeholders), build a component:
mdx example
import { LazyImage } from '../components/LazyImage'
<LazyImage
src="./heavy-image.png"
alt="Detailed infographic"
placeholder="./heavy-image-blur.png"
/>Example
// components/LazyImage.jsx
import { useState, useRef, useEffect } from 'react'
export function LazyImage({ src, alt, placeholder, ...props }) {
const [isLoaded, setIsLoaded] = useState(false)
const [isInView, setIsInView] = useState(false)
const imgRef = useRef()
useEffect(() => {
const observer = new IntersectionObserver(([entry]) => {
if (entry.isIntersecting) {
setIsInView(true)
observer.disconnect()
}
})
if (imgRef.current) observer.observe(imgRef.current)
return () => observer.disconnect()
}, [])
return (
<div ref={imgRef} className="lazy-image-wrapper">
{isInView && (
<img
src={src}
alt={alt}
onLoad={() => setIsLoaded(true)}
className={isLoaded ? 'loaded' : 'loading'}
{...props}
/>
)}
{!isLoaded && placeholder && (
<img src={placeholder} alt="" className="placeholder" aria-hidden="true" />
)}
</div>
)
}
Image Optimization
Pick the Right Format
Example
{/* Use appropriate formats */}
 {/* SVG for icons, logos */}
 {/* WebP for photos (modern) */}
 {/* JPEG for photos (fallback) */}
 {/* PNG for screenshots with text */}
Format Cheat Sheet
| Format | Best For | Compression |
|---|---|---|
| SVG | Icons, logos, simple graphics | Vector (lossless) |
| WebP | Photos and complex images | Both lossy/lossless |
| AVIF | Next-gen photo format | Superior compression |
| PNG | Screenshots, text-heavy images | Lossless |
| JPEG | Photographs | Lossy |
| GIF | Simple animations | Limited colors |
Prevent Layout Shift
Always specify dimensions. This stops the page from jumping around as images load:
mdx example
{/* Always specify dimensions to prevent layout shift */}
<img
src="./optimized-image.webp"
alt="Optimized product image"
width={600}
height={400}
decoding="async"
/>Figure and Caption Patterns
HTML Figure/Figcaption
When you want a caption under your image, use the <figure> element:
mdx example
<figure>
<img src="./architecture.png" alt="Microservices architecture showing 5 services connected via message queue" />
<figcaption>Figure 1: Microservices architecture with event-driven communication</figcaption>
</figure>Custom Figure Component
If you use figures a lot, make a component:
mdx example
import { Figure } from '../components/Figure'
<Figure
src="./performance-chart.png"
alt="Line chart showing 40% performance improvement after optimization"
caption="Figure 2: Response time improvement after implementing caching layer"
number={2}
/>Example
// components/Figure.jsx
export function Figure({ src, alt, caption, number, width }) {
return (
<figure className="mdx-figure">
<img src={src} alt={alt} style={{ maxWidth: width || '100%' }} />
{caption && (
<figcaption className="mdx-figcaption">
{number && <span className="figure-number">Figure {number}:</span>}
{caption}
</figcaption>
)}
</figure>
)
}
Before/After Comparisons
mdx example
<figure>
<div style={{ display: 'flex', gap: '1rem' }}>
<img src="./before.png" alt="UI before redesign" width={400} />
<img src="./after.png" alt="UI after redesign" width={400} />
</div>
<figcaption>Before (left) and after (right) the UI redesign</figcaption>
</figure>Image Gallery Pattern
mdx example
import { Gallery } from '../components/Gallery'
<Gallery columns={3}>
<Gallery.Item src="./photo1.jpg" alt="Mountain landscape" caption="Rocky Mountains" />
<Gallery.Item src="./photo2.jpg" alt="Ocean sunset" caption="Pacific Coast" />
<Gallery.Item src="./photo3.jpg" alt="Forest trail" caption="Redwood Forest" />
</Gallery>Best Practices
- Always write alt text — The only exception is purely decorative images.
- Set width and height — Prevents layout shift (CLS).
- Use WebP or AVIF — Better compression than JPEG/PNG. Add fallbacks for older browsers.
- Lazy load below-the-fold images — Your initial page load will be faster.
- Compress before committing — Don't ship 5MB screenshots to your repo.
- Use SVG for anything scalable — Logos, icons, diagrams.
- Provide fallbacks — Not every browser supports the newest formats.
Common Mistakes
Missing Alt Text
Example
{/* ❌ BAD — No alt text */}
{/* ✅ GOOD — Descriptive alt text */}
Wrong Path
Example
{/* ❌ BAD — Broken path */}
{/* ✅ GOOD — Correct relative path */}
Notice the ./ — without it, some bundlers won't resolve the path correctly.
Giant Images With No Constraints
Example
{/* ❌ BAD — 5000px image with no constraints */}
{/* ✅ GOOD — Constrained size */}
<img
src="./huge-screenshot.png"
alt="Application screenshot"
style={{ maxWidth: '100%', height: 'auto' }}
loading="lazy"
/>
No Dimensions (Causes Layout Shift)
mdx example
{/* ❌ BAD — Causes layout shift */}
<img src="./photo.jpg" alt="Team photo" />
{/* ✅ GOOD — Dimensions prevent layout shift */}
<img src="./photo.jpg" alt="Team photo" width={800} height={600} />That's images in MDX. Write good alt text, set your dimensions, pick the right format, and lazy load anything below the fold. Your users (and their bandwidth) will thank you.
Exam Focus
Revise definitions, diagrams, examples, and short-answer points for Images in MDX.
Interview Use
Prepare one clear explanation, one practical example, and one common mistake for this MDX Tutorial topic.
Search Terms
mdx-tutorial, mdx tutorial, mdx, tutorial, basics, images, images in mdx
Related MDX Tutorial Topics
Continue learning this concept
BasicsBlockquotes in MDXHow to use blockquotes in MDX — simple quotes, nested quotes, callout patterns, and attribution.BasicsCode Blocks in MDXEverything about showing code in MDX — inline code, fenced blocks, syntax highlighting, line numbers, file names, copy buttons, live editors, and diffs.BasicsHeadings in MDXHow to use headings in MDX — from H1 to H6, proper hierarchy, accessibility tips, and when to use which level.BasicsLinks in MDXHow to create links in MDX — internal links, external links, anchor links, and link best practices.BasicsLists in MDXBullet points, numbered lists, nested lists, and task checklists in MDX. All the list types youBasicsParagraphs in MDXHow paragraphs work in MDX — spacing, line breaks, and the blank line rule.