Why MDX, and when plain Markdown is enough
Components inside prose are worth it for a narrow set of reasons. Most pages do not need them.
MDX lets you import a component into a Markdown file and use it inline. That is the whole feature. Whether it earns its place depends on what your prose needs to do that Markdown cannot.
What Markdown cannot express
Markdown has a fixed vocabulary: headings, emphasis, lists, links, code, quotes, tables. It is a deliberately small set, and most writing fits inside it.
The friction shows up when a page needs a repeated, structured element that carries meaning:
With MDX, that becomes a component:
import Callout from "../../components/Callout.astro";
<Callout title="Order of operations">
Assets are matched first.
</Callout>
Change Callout.astro once and every post that uses it updates.
The real argument
The case for MDX is not that it can do more. It is that the alternative — copy-pasted HTML inside Markdown — degrades badly over time. Raw HTML in a content file cannot be type-checked, cannot be refactored, and drifts out of step with the rest of the design as soon as anything changes.
A component is a single definition with a schema.
The cost
MDX is not free:
- Build time. Every file compiles through the MDX pipeline, not a Markdown parser. On a few dozen posts it is unnoticeable; on a few thousand it is not.
- Portability. A
.mdfile renders anywhere. A.mdxfile that imports components renders in your build and nowhere else. - Syntax sharp edges. Curly braces become JavaScript expressions, so prose containing them needs escaping. This surprises people who write mathematics or template syntax.
A reasonable default
Use .md for anything that is only prose. Use .mdx for the pages that
genuinely need a component. Astro’s content collections accept both in the same
collection, so the choice is per file rather than per project:
const posts = defineCollection({
loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/posts" }),
});
Nothing forces the decision up front, which is the right way round.