Astro MDX Basics

Astro MDX Basics

MDX (Markdown for the component era) combines the simplicity of Markdown with the power of React components. In Astro 7.x, MDX is fully supported and provides a powerful way to create dynamic content.

MDX vs Markdown

Markdown (.md)

• Pure text formatting
• Limited to basic elements (headers, lists, links, images)
• No component integration
• Static content only

MDX (.mdx)

• Markdown syntax + JSX components
• Can import and use React components
• Dynamic content generation
• Access to Astro’s astro:assets and other modules

Astro 7.x MDX Configuration

Astro 7.x has built-in MDX support through @astrojs/mdx. The MDX integration is automatically enabled when you use MDX files in your content collections.

Content Configuration

In site/src/content.config.ts:

import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { blogSchema } from 'starlight-blog/schema';

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({ extend: (context) => blogSchema(context) }),
  }),
  i18n: defineCollection({
    loader: i18nLoader(),
    schema: i18nSchema,
  }),
};

This configuration automatically supports both .md and .mdx files in the docs collection.

MDX Component Integration

In MDX files, you can import and use components:

---
title: My MDX Page
---

import { MyComponent } from '../../components/MyComponent.astro';

# My Page

This is a markdown paragraph with an Astro component:

<MyComponent prop="value" />

Astro Assets in MDX

Astro 7.x provides the astro:assets module for image optimization:

---
title: Image Optimization
---

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

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

<Image src={optimizedImage} alt="Optimized image" loading="lazy" />

Benefits of MDX

1. Component Integration: Use React/Astro components in content
2. Dynamic Content: Generate content dynamically with JavaScript
3. Image Optimization: Use astro:assets for optimized images
4. Consistent Format: Single content format for all documentation

Further Reading

• Astro MDX Documentation
• Starlight MDX Support
• Astro Assets Documentation