What MDX Unlocks
MDX is Markdown with superpowers. Everything you can write in a regular .md file works exactly the same here — paragraphs, bold, italic, headings, lists, code blocks, and so on. The difference is that you can also import React components and drop them anywhere in the content.
Importing components
At the top of this file (below the frontmatter) the Box component is imported:
import { Box } from '@/components/shared/Box.tsx';It can then be used anywhere in the body, just like regular JSX:
This paragraph is rendered inside the Box component — the same one used throughout the site for sidebars and UI cards. No wrapper page needed, no custom layout. It’s just a component call, right here in the post.
Inline JavaScript expressions
MDX evaluates {expression} blocks as JavaScript. This means you can compute values inline:
- Current year: 2026
- Simple arithmetic: 42
- Formatted date: 12 March 2026
These are evaluated at build time, so the output is static HTML — no JavaScript is shipped to the browser for these expressions.
Inline JSX
You can write raw HTML or JSX elements anywhere in the prose. This is useful for one-off styling that doesn’t warrant a full component:
Exported variables
MDX files can export named values. These are accessible in Astro pages that render the collection entry via const { Content, ...exports } = await entry.render().
The exported summary above can be read programmatically by any page that renders this post.
Mixing Markdown and JSX freely
One of the most natural things about MDX is that you don’t have to choose. A section can start as a Markdown heading, flow into a paragraph, drop into a component, return to a paragraph, and end with a code block — all in the same file.
A note on hydration
Components used in MDX content collections are server-rendered by default. If you need a component to be interactive in the browser, import it in the page’s frontmatter (not the MDX file) and pass it in as a prop, or use Astro’s client:load directive at the page level.
For static, presentational components like Box, server rendering is all you need — and the result is zero JavaScript shipped to the browser for the component itself.
When to use MDX vs Markdown
| Use case | Recommendation |
|---|---|
| Long-form prose with standard formatting | .md — simpler, less overhead |
| Post needs a custom component or layout element | .mdx — import what you need |
| Computed values or dynamic expressions | .mdx |
| Reusing a design pattern from the codebase | .mdx — import the existing component |
| Guest post or external contribution | .md — lower barrier for contributors |
Both formats live side by side in src/content/blog/ and are handled identically by the content collection schema and all the site’s utilities.