20 — Markdown and MDX — Content with Components Inside

The content layer for blogs, docs, and prose-driven sites has two names that differ by one capability. The model that clicked: Markdown is a lightweight markup language that turns plain-text syntax into structurally valid HTML; MDX is its superset that lets me write JSX directly inside the markdown, embedding React components within the prose [1]. Next.js supports both local MDX (files in the project) and remote MDX (fetched dynamically), with the App Router handling the transform so MDX works in Server Components by default.

Markdown — the plain-text baseline

Markdown lets me write structured content in plain text — # for headings, **bold**, lists, links — that converts to valid HTML. It's the lingua franca of blog posts, README files, and documentation because it's readable as text and renders as structured markup. For pure-prose content with no interactivity, plain Markdown is enough.

MDX — components inside prose

MDX adds JSX to Markdown. The payoff is content that can include interactive or data-driven components: a chart inside a blog post, a live code playground, an embedded widget. Instead of choosing between "a markdown page" and "a React page," MDX lets the prose carry components where they're needed.

# My Post

Here's a paragraph of prose.

<Chart data={salesData} />

And here's more prose after the chart.

The Next.js plugin transforms MDX into React components at build time, so the result is a regular component tree that renders server-side in the App Router [1].

Local vs remote MDX

Two source patterns:

• Local MDX — .mdx files inside the project, imported as components or rendered via the file-system router. Best when content is versioned with the code.
• Remote MDX — MDX fetched dynamically on the server (from a CMS, a database, an API) and compiled at runtime or build. Best when content is authored outside the codebase.

The roadmap is explicit that Next.js supports both, including the use of MDX in Server Components — the App Router's default [1].

How I use this

For anything prose-heavy with occasional interactivity — a blog, docs with embedded demos — MDX is the natural fit. I keep long-form content in .mdx files, drop in React components where the prose needs them (a chart, a callout, an interactive example), and let the build transform it. For pure-prose pages with zero interactivity, plain Markdown suffices. For content owned by non-developers (a CMS), I fetch it remotely and compile MDX server-side. The principle: match the source to who authors the content, and reach for MDX when prose and components need to coexist.

References

[1] Vercel, "How to use markdown and MDX in Next.js," Next.js Docs, 2024. [Online]. Available: https://nextjs.org/docs/app/guides/mdx

[2] MDX, "MDX — Markdown for the component era," mdxjs.com, 2024. [Online]. Available: https://mdxjs.com/

[3] "Markdown — getting started," markdownguide.org, 2024. [Online]. Available: https://www.markdownguide.org/