When to reach for MDX
Plain Markdown for almost everything; MDX for the post that needs a real component in the middle of it.
Most posts should be plain .md. It’s less machinery, it renders faster, and
you can move the file anywhere later without untangling imports.
Switch the extension to .mdx when a single post needs something Markdown
can’t express — a live chart, a small calculator, a diagram component you’ve
already built.
How it works
Import the component under the frontmatter, then use it anywhere in the body:
---
title: 'A post with a component'
description: '…'
pubDate: 2026-09-28
---
import Callout from '../../components/Callout.astro';
<Callout type="warning" title="Heads up">
Body text, which can contain **Markdown** too.
</Callout>Both extensions live in the same collection and share the same frontmatter schema, so you can mix them freely — the listings, tags and RSS feed don’t care which is which.