Building an MDX Blog in Next.js

After experimenting with various CMS solutions, we came back to one of the simplest and most powerful approaches: an MDX-based blog system powered by Next.js. MDX gives us the portability of Markdown combined with the expressiveness of React — the best of both worlds.

Markdown vs MDX

Markdown is great for content. MDX takes it a step further by letting you use React components directly inside your posts — no plugins, no shortcodes, no post-processing step.

The Architecture

Each post lives in its own folder under storage/posts/, named with the publication date and slug. The system reads these at build time — no database queries, no API calls at runtime.

storage/posts/
├── 2026-02-02-markdown-blog-in-next-js/
│   ├── post.mdx          ← content + frontmatter
│   ├── cover.jpg         ← hero background
│   ├── cover.webp        ← hero (webp)
│   ├── thumb.jpg         ← card preview (2× retina)
│   └── thumb.webp        ← card preview (webp)
└── ...

Frontmatter with gray-matter

We use gray-matter to parse YAML frontmatter for post metadata:

import matter from 'gray-matter'

const { data, content } = matter(fileContent)

const meta = {
  title: data.title,
  description: data.description,
  heroImage: data.heroImage,
  thumbImage: data.thumbImage,
}

MDX Components

This is where MDX really shines over plain Markdown. We register custom components globally — they are available in every post with no imports needed inside the MDX file.

Using Components in Practice

Here's how a Grid of Callouts looks in MDX source:

<Grid cols={2}>
  <Callout variant="info" title="First">
    Content here...
  </Callout>
  <Callout variant="success" title="Second">
    More content...
  </Callout>
</Grid>

And a timeline:

<TimelineItem date="Jan 1" color="blue">
  Project kickoff — picked the tech stack
</TimelineItem>
<TimelineItem date="Jan 15" color="purple">
  First post published
</TimelineItem>

Rendering with next-mdx-remote

next-mdx-remote handles the heavy lifting on the rendering side:

• Full App Router support with server components
• Custom component registration via the components prop
• Syntax highlighting via rehype-highlight
• GitHub Flavored Markdown via remarkGfm
• Auto-generated heading anchors via rehypeSlug

Handling Removed Posts

Posts can be "removed" without deleting the folder — truncate the file to 0 bytes:

const stats = await fs.stat(postPath)
if (stats.size === 0) {
  // Return 410 Gone — the SEO-friendly way to retire content
}

The folder, images, and URL all stay intact. The server returns a proper HTTP 410 status instead of a 404.

Performance

Writing a New Post

No login required, no admin interface, no database migrations. Just files in git.