MDX Migration Guide

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

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

Step 1: Rename .md to .mdx

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

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

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

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

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

---
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

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

Image Not Found

• Ensure relative paths are correct
• Check that image files exist in the assets/ directory

MDX Syntax Errors

• Ensure JSX is properly formatted
• Check for missing imports

Build Failures

• Ensure @astrojs/mdx is configured (built-in in Astro 7.x)
• Check content configuration in content.config.ts

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

• MDX Migration Guide
• Astro Assets Documentation
• Starlight MDX Support