Why MDX?
Astro ships with native support for Markdown through .md files, but there are two ways to extend that experience: MDX and the Markdown Component. This piece concentrates on the first.
MDX is a Markdown superset. Alongside every ordinary Markdown feature, it allows components and simple JSX inside your content. Within Astro you can additionally pull in components from any frontend framework you have installed, so a file can mix plain prose with framework components:
---
# Frontmatter...
---
import AstroComp from '@/components/AstroComp.astro'
import SvelteComp from '@/components/AstroComp.astro'
<AstroComp> ... </AstroComp>
<SvelteComp> ... </SvelteComp>
That mix is what makes MDX a strong fit for content-heavy pages, where you might otherwise be hand-writing a lot of HTML:
<div class="card">
### Card Title
Content goes here
- List
- Of
- Items
Second paragraph
</div>
Astro compiles the MDX above into this output:
<div class="card">
<h2>Card Title</h2>
<p>Content goes here </p>
<ul>
<li> List </li>
<li> Of </li>
<li> Items </li>
</ul>
<p>Second paragraph</p>
</div>
Three things are worth noticing about the authoring experience:
##stands in for a fullh2tag.-replaces<ul>and<li>for lists.- Paragraph tags aren't needed at all.
Doing all of that in raw HTML would be a chore.
Adding MDX to a Project
Astro provides an MDX integration, so wiring it in is a matter of following the documented installation steps.
Once installed, there are three main ways to consume MDX files — and each of them applies to standard Markdown files too:
- Import the file directly into an Astro component.
- Route it through a content collection.
- Attach a layout via frontmatter.
Direct import
Import the MDX file and render it as a component:
---
import MDXComp from '../components/MDXComp.mdx'
---
<MDXComp />
Used this way, an MDX file can behave much like a partial.
Content collections
For collections, the glob definition needs the mdx pattern added alongside Markdown. Then fetch the entry like any other collection item:
---
import { getEntry, render } from 'astro:content'
const { slug } = Astro.props
const post = await getEntry('blog', slug)
const { Content } = await render(post)
---
<Content />
A useful property of this route: components can be handed to the MDX files, which means you avoid importing them one by one in every file. Here is how an Image component from Splendid Labz can be passed into each entry:
---
import { Image } from '@splendidlabz/astro'
// ...
const { Content } = await render(post)
const components = { Image }
---
<Content {components} />
Inside the MDX files, Image is then available with no import statement:
<Image src="..." alt="..." />
Layout through frontmatter
A layout frontmatter entry in the MDX file can point at an Astro file:
---
title: Blog Post Title
layout: @/layouts/MDX.astro
---
In that layout file, frontmatter properties are available via Astro.props.content, and the MDX body is rendered through <slot>:
---
import Base from './Base.astro'
const props = Astro.props.content
const { title } = props
---
<Base>
<h1>{title}</h1>
<slot />
</Base>
Things to Watch For
Formatting and linting
ESLint and Prettier don't handle MDX well, which in practice means most markup ends up indented by hand. That's tolerable when there is only a little markup; on files with a lot of it, the Markdown Component becomes the better option.
RSS
The Astro RSS integration does not support MDX out of the box. Astro containers make this straightforward to work around.



