Skip to content
Back to snippets
nextjsmdxreactseofrontend

Using MDX with Next.js for a Modern Developer Blog

•6 min read•701 views

Learn how to build a scalable, SEO-friendly developer blog using MDX, Next.js, and reusable React components.

Modern developer blogs are no longer just static markdown pages.

Today’s technical blogs often include:

  • Interactive React components
  • Dynamic code blocks
  • Embedded demos
  • Custom UI elements
  • Advanced SEO optimization

This is exactly where MDX shines.

By combining Markdown with React, MDX allows developers to build content-rich blogs that feel more like applications than traditional websites.

In this article, we’ll explore how to build a scalable MDX blog using Next.js while keeping performance, maintainability, and SEO in mind.

What is MDX?

MDX is an extension of Markdown that supports JSX and React components directly inside markdown files.

This means you can write content like this:

# Hello MDX
 
<Button>Click Me</Button>

Instead of being limited to plain text, your content becomes fully interactive.

Why Developers Prefer MDX

MDX solves several common problems in modern documentation and blogging systems.

Reusable Components

Without MDX, developers often duplicate HTML snippets across multiple articles.

For example:

<div class="warning">Important warning message</div>

With MDX, this becomes reusable:

<Warning>Important warning message</Warning>

This improves consistency and reduces duplicated markup.

Interactive Documentation

MDX makes it easy to embed:

  • React components
  • API demos
  • Charts
  • Videos
  • Interactive examples

directly inside articles.

This creates a significantly better developer experience.

Better Content Architecture

MDX helps separate:

  • Content
  • Presentation
  • Business logic

while still keeping everything flexible.

Writers can focus on content while developers maintain shared UI components.

Setting Up MDX in Next.js

Next.js provides excellent support for MDX.

Installing Dependencies

Start by installing the required packages:

npm install @next/mdx @mdx-js/loader @mdx-js/react

Configuring Next.js

Update your `next.config.ts`:

import createMDX from '@next/mdx'
 
const withMDX = createMDX({
  extension: /\.mdx?$/,
})
 
const nextConfig = {
  pageExtensions: ['ts', 'tsx', 'md', 'mdx'],
}
 
export default withMDX(nextConfig)

This enables MDX support throughout your application.

Creating Your First MDX Page

Inside the `app` directory:

app/
├── blog/
│   └── hello-world.mdx

Example page:

# My First MDX Post
 
This is written using MDX.
 
<Button>Interactive Button</Button>

At this point, your markdown files can render React components directly.

Creating Reusable Components

One of MDX’s biggest strengths is component reuse.

Example Button Component

type ButtonProps = {
  children: React.ReactNode
}
 
export function Button({
  children,
}: ButtonProps) {
  return (
    <button className="rounded-lg bg-black px-4 py-2 text-white">
      {children}
    </button>
  )
}

Registering MDX Components

Create an `mdx-components.tsx` file:

import { Button } from '@/components/button'
 
export const mdxComponents = {
  Button,
}

Then provide these components globally:

import { MDXProvider } from '@mdx-js/react'
import { mdxComponents } from './mdx-components'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <MDXProvider components={mdxComponents}>
          {children}
        </MDXProvider>
      </body>
    </html>
  )
}

Now every MDX file can use shared React components automatically.

Organizing Blog Content

As your blog grows, organization becomes extremely important.

A scalable structure might look like this:

content/
├── blog/
│   ├── nextjs-seo.mdx
│   ├── react-performance.mdx
│   └── mdx-guide.mdx

This keeps content separate from application logic.

Using Frontmatter for Metadata

Frontmatter stores metadata about each article.

Example:

---
title: "My Blog Post"
description: "Learning MDX with Next.js"
date: "2026-05-15"
tags: ["nextjs", "mdx"]
---

This metadata powers:

  • SEO
  • Open Graph tags
  • Blog listings
  • RSS feeds
  • Search indexing

Parsing Frontmatter

A common approach uses `gray-matter`.

Installing gray-matter

npm install gray-matter

Reading MDX Files

import fs from 'fs'
import matter from 'gray-matter'
 
export async function getPost(slug: string) {
  const file = fs.readFileSync(
    `content/blog/${slug}.mdx`,
    'utf8'
  )
 
  const { data, content } = matter(file)
 
  return {
    frontmatter: data,
    content,
  }
}

This gives you structured metadata alongside raw content.

Improving SEO for MDX Blogs

SEO is one of the most overlooked parts of developer blogs.

Proper Heading Hierarchy

A well-structured article should contain:

  • One H1
  • Multiple H2 sections
  • Nested H3 subsections

Example:

# Main Title
 
## Main Section
 
### Subsection

This helps search engines understand your content structure.

Adding Metadata

Next.js App Router makes SEO simple.

Example:

export async function generateMetadata() {
  return {
    title: 'Using MDX with Next.js',
    description:
      'Learn how to build a modern developer blog.',
  }
}

This improves discoverability across search engines and social platforms.

Automatic Table of Contents

You can generate section navigation automatically using headings.

Useful plugins include:

  • `remark-toc`
  • `rehype-slug`
  • `rehype-autolink-headings`

Benefits include:

  • Better navigation
  • Improved accessibility
  • Enhanced SEO

Syntax Highlighting

Code blocks are critical for developer blogs.

Popular Solutions

Most developers use:

  • Shiki
  • Prism
  • Rehype Pretty Code

Example installation:

npm install rehype-pretty-code

Configuration:

tailwind.config.js
rehypePlugins: [
  [
    rehypePrettyCode,
    {
      theme: 'github-dark',
    },
  ],
]

This produces beautiful production-grade code snippets.

Performance Considerations

Large MDX blogs can become slow if poorly optimized.

Static Generation

Use static rendering whenever possible.

generateStaticParams()

This dramatically improves page speed and SEO.

Optimizing Images

Always use the Next.js image component:

import Image from 'next/image'

Benefits include:

  • Responsive images
  • Lazy loading
  • Automatic optimization

Avoid Excessive Client Components

Interactive widgets are useful, but too many can increase JavaScript bundle size.

Keep articles primarily server-rendered whenever possible.

Common Mistakes with MDX

Many developers misuse MDX during early projects.

Overusing Interactive Components

Not every paragraph needs animations or dynamic widgets.

Content readability should remain the priority.

Poor File Organization

As articles grow, scattered content becomes difficult to maintain.

Separate:

  • Content
  • Components
  • Utilities
  • Layouts

from the beginning.

Ignoring SEO Structure

Using multiple H1 headings is a common mistake.

Proper semantic structure matters for:

  • Search engines
  • Accessibility
  • Reader navigation

Advanced MDX Features

Once your blog matures, MDX can support:

  • Interactive code editors
  • Embedded sandboxes
  • Math rendering
  • Mermaid diagrams
  • Dynamic charts
  • API playgrounds

This flexibility is why many engineering teams now use MDX for both blogging and documentation.

Final Thoughts

MDX has become the standard solution for modern developer blogs because it combines:

  • Markdown simplicity
  • React flexibility
  • Component reuse
  • SEO-friendly architecture
  • Interactive experiences

into a single workflow.

Combined with Next.js, MDX enables developers to build fast, scalable, and highly customizable publishing platforms.

Instead of treating content as static pages, MDX allows your blog to evolve into a fully interactive application — while still maintaining the simplicity of markdown writing.