---
title: "20 — Markdown and MDX — Content with Components Inside"
uid: markdown-mdx
tags: ["roadmap:nextjs", "mdx", "content", "app-router", "nextjs", "markdown"]
excerpt: "Markdown is a lightweight markup language for text; MDX is its superset that embeds React components inside the prose. Next.js handles both local and remote sources."
date: 2026-08-13T03:27:59+0000
source: https://www.aveshina.my.id/en/blog/markdown-mdx
---
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.
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].
```figure
```
## 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](https://nextjs.org/docs/app/guides/mdx)
[2] MDX, "MDX — Markdown for the component era," mdxjs.com, 2024. [Online]. Available: [https://mdxjs.com/](https://mdxjs.com/)
[3] "Markdown — getting started," markdownguide.org, 2024. [Online]. Available: [https://www.markdownguide.org/](https://www.markdownguide.org/)
```quiz
Q: What's the relationship between Markdown and MDX?
- MDX is a faster Markdown parser
- MDX is a superset of Markdown that lets you write JSX (React components) directly inside the markdown
correct: 1
explain: MDX extends Markdown with JSX, so prose and interactive components can coexist in the same file.
Q: Does MDX work in Server Components in the App Router?
- No — it requires 'use client'
- Yes — the Next.js plugin transforms MDX at build time so it renders server-side by default
correct: 1
explain: The App Router handles the MDX transform so it works in Server Components by default, no 'use client' required.
Q: What distinguishes local MDX from remote MDX?
- Local is faster; remote is more secure
- Local MDX lives as .mdx files in the project; remote MDX is fetched dynamically (from a CMS/API) and compiled server-side
correct: 1
explain: The source differs: local files versioned with the code versus remote content authored outside the codebase. The choice depends on who authors the content.
Q: A good use case for MDX is…
- a static landing page with no interactivity
- a blog post that needs an embedded interactive chart alongside the prose
correct: 1
explain: MDX's strength is mixing prose and components. A blog post with an embedded chart, demo, or widget is exactly the case it was built for.
```