Astro handles plain Markdown fine, but this piece makes a decent case for using MDX when you want a bit more flexibility without turning the whole thing into a mess.
MDX earns its keep in Astro the moment you want to drop an actual component into a post—callouts, a little chart, a “don’t do this” warning box—without duct-taping a pile of remark/rehype plugins together.
I still keep plain .md for boring posts, but once you need anything even slightly layout-y, MDX is the cleaner escape hatch (and future-you won’t be debugging a custom Markdown extension at 1am).
Ngl MDX feels like hitting the “use the engine” button instead of modding the renderer for every tiny UI thing. the first time you want a callout or an interactive bit and you’re not fighting three plugins and some cursed HTML-in-markdown hack, it kinda sells itself.
MDX won me over on the boring stuff: you can force consistency by mapping h2, a, img, etc. to your own components, so every post gets the same typography/link/image behavior without babysitting a pile of Markdown plugins.
In Astro that’s especially clean because your design system is already components, so content can just “use the real parts” instead of inventing yet another callout syntax. I did this on a tiny tokens/docs prototype and it instantly stopped the slow “why does this one page look a little off” drift.
The component-mapping bit @Yoshiii mentioned has a nice second-order effect: you’re basically centralizing “policy” (typography, link behavior, image defaults) in one place and letting it propagate across the whole content surface.
I hit the same “one page looks slightly off” drift on a small docs prototype, and MDX was the first thing that made it feel like the design system was actually in charge instead of a loose pile of Markdown conventions.
