When to Reach for MDX

import FigureNote from '../../components/FigureNote.astro';

Markdown handles most writing. Headings, paragraphs, links, lists, quotes, code, images. Stay in Markdown by default.

Switch to MDX when an Astro component needs to live inside the post — not next to it, not below it, but in the exact place the prose is referring to.

This file is an MDX file. Watch what FigureNote does here:

This block is an Astro component called from inside the post. The prose around it does not break, and the component shares the site's design tokens.

The component sits inline. The article continues. That is the only thing MDX is for.

How to switch a post to MDX

1. Rename the file from .md to .mdx.

2. After the frontmatter, import the component:

3. Use it like an HTML tag in the body:

That is the whole switch. Markdown still works around the component.

The example component

The starter includes one prose component: FigureNote. It is small on purpose.

src/components/FigureNote.astro:

Its style lives with the FigureNote.astro component and uses the same tokens as the rest of the theme. If you change --color-blue or --label-tertiary, the note follows.

Build your own

A useful prose component is small, reads like an HTML element, and earns its place by clarifying the explanation.

Good candidates:

• A callout with a specific tone (note, tip, warning).
• A side-by-side comparison block.
• A figure with a richer caption than caption allows.
• A pull quote that needs different styling from a blockquote.

Skip:

• Decoration between paragraphs.
• Cards that summarize what the prose already said.
• Anything with internal state, network calls, or its own routing.

If a component needs state or behavior, it usually belongs in a page route, not in a post. The post can link to it.

Where the files live

Astro components imported into MDX can live anywhere under src/components/. The starter keeps prose-specific components there too. FigureNote.astro is one.

Component-owned CSS can live in the same .astro file as a scoped