Skip to content
Michael Wegener's Learn & Projects
Blog

MDX Migration Guide

MDX Migration Guide

Section titled “MDX Migration Guide”

This guide explains how to convert .md files to .mdx files and implement image optimization using the Image component from astro:assets.

Migration Strategy

Section titled “Migration Strategy”

Selective vs Full Conversion

Section titled “Selective vs Full Conversion”

Selective Conversion (Recommended):

  • Convert only files with images
  • Lower risk, focused changes
  • Easier to test and verify

Full Conversion:

  • Convert all documentation to MDX
  • Consistent format everywhere
  • Higher risk, larger refactoring

Step-by-Step Migration

Section titled “Step-by-Step Migration”

Step 1: Rename .md to .mdx

Section titled “Step 1: Rename .md to .mdx”
Terminal window
mv site/src/content/docs/blog/2026-07-06-stable-diffusion-bilder-generieren.md \
   site/src/content/docs/blog/posts/2026-07-06-stable-diffusion-bilder-generieren.mdx

Step 2: Add Imports

Section titled “Step 2: Add Imports”

Add the Image and getImage imports at the top of the MDX file (after the frontmatter):

---
title: "My Blog Post"
date: 2026-07-09
---


import { Image, getImage } from 'astro:assets';
import myImage from '../../../assets/images/my-image.png';

Step 3: Generate Optimized Images

Section titled “Step 3: Generate Optimized Images”

Add getImage() calls to generate optimized images:

const optimizedImage = await getImage({
  src: myImage,
  width: 1200,
  quality: 75,
  formats: ['webp', 'avif', 'jpeg'],
});

Step 4: Replace Markdown Images

Section titled “Step 4: Replace Markdown Images”

Replace markdown image syntax with the Image component:

Before (Markdown):

![Alt text](/assets/images/my-image.png)

After (MDX):

<Image src={optimizedImage} alt="Alt text" loading="lazy" />

Complete Example

Section titled “Complete Example”

Original Markdown File

Section titled “Original Markdown File”
---
title: "Stable Diffusion - Bilder generieren"
date: 2026-07-06
---


# Stable Diffusion


![Nature Landscape](/assets/images/image-generation/1-nature-landscape.png)

Converted MDX File

Section titled “Converted MDX File”
---
title: "Stable Diffusion - Bilder generieren"
date: 2026-07-06
---


import { Image, getImage } from 'astro:assets';
import natureImage from '../../../assets/images/image-generation/1-nature-landscape.png';


const optimizedNatureImage = await getImage({
  src: natureImage,
  width: 1200,
  quality: 75,
  formats: ['webp', 'avif', 'jpeg'],
});


# Stable Diffusion


<Image src={optimizedNatureImage} alt="Nature Landscape" loading="lazy" />

Verification Steps

Section titled “Verification Steps”
  1. Build the site: pnpm build in the site/ directory
  2. Check for optimized images: Look for WebP/AVIF files in site/dist/
  3. Verify srcset attributes: Check generated HTML for srcset attributes
  4. Browser automation: Use playwright-cli to verify image loading and formats

Common Issues

Section titled “Common Issues”

Image Not Found

Section titled “Image Not Found”
  • Ensure relative paths are correct
  • Check that image files exist in the assets/ directory

MDX Syntax Errors

Section titled “MDX Syntax Errors”
  • Ensure JSX is properly formatted
  • Check for missing imports

Build Failures

Section titled “Build Failures”
  • Ensure @astrojs/mdx is configured (built-in in Astro 7.x)
  • Check content configuration in content.config.ts

Benefits of Migration

Section titled “Benefits of Migration”
  1. Optimized Images: WebP/AVIF formats with srcset attributes
  2. Faster Loading: Smaller file sizes improve LCP
  3. Responsive Images: Optimal image size for each device
  4. Component Integration: Use Astro components in content

Further Reading

Section titled “Further Reading”