Markdown Rendering in Next.js
🔬 2026-03-20
Research into the best approaches for rendering markdown content in Next.js applications.
Markdown Rendering in Next.js
Approaches Evaluated
1. next-mdx-remote
Server-side MDX compilation with support for custom React components.
Pros: Full MDX support, custom components, server-side rendering Cons: Slightly heavier, requires serialization step
2. react-markdown
Client-side markdown rendering with plugin support.
Pros: Simple API, lightweight, good plugin ecosystem Cons: Client-side only, no MDX component support
3. @next/mdx
Official Next.js MDX integration.
Pros: Native integration, file-based routing Cons: Less flexible for dynamic content
Decision
Using next-mdx-remote for maximum flexibility — it supports custom components (useful for wiki-links, callouts, and interactive elements) while still working with server components.
Key Libraries
| Library | Purpose |
|---|---|
next-mdx-remote | MDX compilation + rendering |
gray-matter | Frontmatter parsing |
rehype-highlight | Code syntax highlighting |
remark-gfm | GitHub-flavored markdown |
glob | Content file discovery |
Implementation Notes
- Content files stored in
content/directory at project root - Frontmatter provides metadata (title, date, tags, summary)
- Wiki-links (
[Slug](/slug)) transformed via custom remark plugin - Backlinks computed at build time by scanning all content files