MDX

MDX is Markdown in which you can use components and JavaScript expressions. Plain text is written as in Markdown, and a component goes where you need it, such as a warning box or a button. MDX support in Astro comes from an official integration.

Adding it

An integration is a package that extends Astro. It is installed with the astro add command:

npx astro add mdx

The command installs the @astrojs/mdx package and adds it to astro.config.mjs by itself:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
 
export default defineConfig({
  integrations: [mdx()],
});

Restart the dev server: it does not always pick up config changes on its own.

A component inside text

Create a box component, src/components/Note.astro:

<aside class="note">
  <slot />
</aside>
 
<style>
  .note {
    padding: 1rem;
    background: #fff8e1;
    border-left: 4px solid #f5b400;
  }
</style>

Now create the page src/pages/uses.mdx:

---
layout: ../layouts/MarkdownLayout.astro
title: What I use
---
import Note from '../components/Note.astro';
 
My editor is **VS Code**, my browser is Firefox.
 
<Note>
  The list was updated in spring 2025.
</Note>

Open /uses: the text is formatted like ordinary Markdown, with a yellow box between the paragraphs. The component is imported right after the frontmatter and written as a tag.

Expressions

Curly braces work in MDX. The frontmatter variable holds the data from the file's frontmatter:

---
layout: ../layouts/MarkdownLayout.astro
title: What I use
---
 
The page "{frontmatter.title}" appeared in 2025.
 
The list has {2 + 1} programs.

Below the heading from the layout you see two lines: the first gets the title "What I use" from the frontmatter, and in the second {2 + 1} becomes the number 3.

Markdown or MDX

Both formats work as pages in src/pages/ and as entries of content collections.

Common mistake

In MDX the characters {, } and < have a special meaning. A phrase like "if a < b" or a curly brace in ordinary text breaks the build with a parse error. Wrap such characters in backticks (as code) or use plain .md for that text.