MDX

MDX is Markdown plus the ability to import and use components. Perfect for content that needs interactive widgets or custom layouts.

4 min read Level 2/5 #astro#mdx#content

What you'll learn

Install the MDX integration
Use components inside `.mdx` content
Pass JSX-style expressions inline

MDX is Markdown + JSX-style components. A .mdx file can import Astro components, use them inline, and run JavaScript expressions in { }. Perfect for technical writing that needs interactive widgets.

Install

npx astro add mdx

That installs @astrojs/mdx and wires up the integration.

A Typical MDX File

---
title: Hello, MDX
pubDate: 2026-05-12
---

import Callout from "../components/Callout.astro";
import Counter from "../components/Counter.tsx";

# Hello, MDX

You can use Astro components inline:

<Callout kind="tip">
  This is a tip rendered by a component.
</Callout>

Or even hydrated framework components:

<Counter client:load initial={5} />

JS expressions work too: 2 + 2 is {2 + 2}.

When to Use MDX

Use case	Reach for…
Plain article with text, images, code blocks	Markdown
Article with custom callouts, tabs, demos	MDX
Article with interactive widgets	MDX + islands
Page that’s mostly UI	`.astro` page

If you don’t need components, stick with Markdown — it’s faster to parse and simpler.

Configuring Components Globally

Tired of importing the same components into every MDX file? Configure global components in astro.config.mjs:

import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";

export default defineConfig({
  integrations: [
    mdx({
      // …
    }),
  ],
});

You can also pass a components map when you render the MDX (next section).

Rendering With Custom Components

When you render MDX, you can map default HTML elements to custom components:

---
import { Content } from "../content/post-1.mdx";
import H1 from "../components/MyH1.astro";
---

<Content components={{ h1: H1 }} />

Every # Heading in the MDX renders as <MyH1> instead of <h1>.

Up Next

The schema — typing frontmatter with Zod.

Frontmatter Schema →