Integrating MDX into a Next.js blog

A step-by-step guide for a junior developer

1. Why MDX?

MDX is a superset of Markdown that lets you embed React (or Next.js) components directly inside your Markdown files.
This is super useful for a blog or content site, because you can write normal markdown for text, headings, lists, etc., and include interactive or custom UI components when needed.

In the “blog” example from Vercel see the repository the content is managed via Markdown/MDX files and then rendered in Next.js pages. Using this pattern gives you:

• A nice authoring experience (just write .mdx files)
• The ability to pull metadata (front-matter) from each file (title, date, tags)
• The power to import custom React components into your content.

2. Set up your Next.js project

1. Create a new Next.js project (or navigate to your existing one).

1234

npx create-next-app@latest my-blog
cd my-blog

2. Configure Next.js to support .mdx files

In your project root, edit or create next.config.mjs (or next.config.js) to include MDX support. For example:

123456789101112
import createMDX from '@next/mdx'
/*_ @type {import('next').NextConfig} _/
const nextConfig = {
pageExtensions: ['js','jsx','ts','tsx','md','mdx'],
// …other config options
}
const withMDX = createMDX({
extension: /.(md|mdx)$/,
// you can add remark/rehype plugins here if needed
})
export default withMDX(nextConfig)

This allows you to define apps/routes using .mdx or .md files. Next.js

If you’re using the App Router (Next.js 13+) you’ll also want to create an mdx-components.tsx/jsx file (or similar) to define MDX component mappings.

4. Create your content files (posts)

In your project, create a directory (e.g., posts/ or content/posts/) where you’ll store your blog post files. For example:

12345

/posts
├── first-post.mdx
├── second-post.mdx

Each file should begin with front-matter metadata, then the content. Example:

1234567891011121314151617

---
title: "My First Blog Post"
date: 2025-10-30
description: "This is the first post using MDX in Next.js"
---

# Hello, world!

This is a blog post written in MDX.

Here’s a custom component:

<MyCustomComponent highlight="yes">
Check out this dynamic content!
</MyCustomComponent>

In this example you’re able to import and use <MyCustomComponent /> because MDX allows embedding React components.

5. Fetch and generate pages for each MDX file

Now you need to wire up Next.js so that each MDX file becomes a page. Depending on whether you use the Pages Router or App Router, the setup differs a little, but conceptually:

Read the file system to get all posts (metadata + content)

For each post, generate a URL path (slug)

Render a page for each slug, passing the front-matter and the rendered MDX content.

Example (Pages Router style)

In apps/posts/[slug].tsx, you might do something like:

12345678910111213141516171819202122232425262728293031323334

import fs from 'fs'
import path from 'path'
import matter from 'gray-matter'
import { bundleMDX } from 'mdx-bundler' // or other renderer

export async function getStaticPaths() {
const files = fs.readdirSync(path.join(process.cwd(), 'posts'))
const paths = files.map(filename => ({
  params: {
    slug: filename.replace(/.mdx?$/, '')
  }
}))
return { paths, fallback: false }
}

export async function getStaticProps({ params }) {
const filePath = path.join(process.cwd(), 'posts', passSlug.mdx)
const source = fs.readFileSync(filePath, 'utf8')
const { data: frontMatter, content } = matter(source)
const { code } = await bundleMDX({ source: content, /* options */ })
  return {
      props: { frontMatter, code }
  }
}

export default function PostPage({ frontMatter, code }) {
return (
  <article>
    <p>{frontMatter.title}</p>
    <div dangerouslySetInnerHTML={{ __html: codez }} />
  </article>
)
}

Example (App Router style – Next.js 13+)

• In app/posts/[slug]/page.tsx:

1234567891011121314151617181920

import { getPost, allPosts } from '@/lib/posts'

export async function generateStaticParams() {
return allPosts.map(post => ({
  slug: post.slug
}))
}
export default async function PostPage({ params }) {
const post = await getPost(params.slug)
if (!post) {
  notFound()
}
return (
  <div className="prose mx-auto">
    <p>{post.frontMatter.title}</p>
    <div>{post.body}</div> 
  </div>
    )} 

You’ll need a helper like getPost(slug) that reads the MDX file, parses front-matter, renders the MDX to React components (or HTML). Many examples (including the Vercel “blog” example) show this style.

6. Render the content and define mappings for MDX components

To style your Markdown/MDX content nicely and support custom components, create an mdx-components.tsx/jsx file to define which React components map to Markdown elements (h1, p, img, etc.). Example:

1234567891011121314
import Image from 'next/image'
import type { MDXComponents } from 'mdx/types'

const components: MDXComponents = {
h1: ({ children }) => <h1 className="text-3xl font-bold">{children}</h1>,
img: (props) => <Image {...props} alt={props.alt} className="rounded" />,
MyCustomComponent: (props) => <MyCustomComponent {...props} />,
// … more custom mappings
}

export function useMDXComponents() {
return components
}

Then when rendering your MDX you'll pass these components (depending on renderer) so that your MDX file will know how to render <MyCustomComponent /> or other elements. The official Next.js guide covers this.

Also you can apply a global styling wrapper (for example using Tailwind’s prose class) so your markdown content looks good.

7. List posts / build blog index

On your home or blog-index page, you’ll want to fetch all posts (metadata only) and display a list of links. For example:

123456789101112131415161718192021

import Link from 'next/link'
import { getAllPosts } from '@/lib/posts'

export default async function BlogIndex() {
const posts = await getAllPosts()

return (

<div className="space-y-4">
{posts.map(post => (
<Link key={post.slug} href={/posts/slug}>
<a className="block p-4 border rounded hover:bg-gray-100">
<h2 className="text-xl font-semibold">{post.frontMatter.title}</h2>
<time className="text-sm text-gray-500">{post.frontMatter.date}</time>
<p>{post.frontMatter.description}</p>
</a>
</Link>
))}
</div>)}

This way you build a blog-index and then each link goes to the corresponding MDX-based post page.

8. Tips & best practices

Use front-matter to store metadata such as title, date, description, tags, thumbnail.

Use a consistent file naming scheme for posts, e.g. yyyy-mm-dd-post-title.mdx or /posts/slug/index.mdx.

Use prose classes (Tailwind typography plugin) or CSS to style the markdown content nicely.

If you embed components in MDX, keep them small and reusable (e.g., <Alert>, <EmbedVideo>, <CodeSnippet>).

For performance, use static generation (SSG) when possible so your pages build at build time.

If you’re using the App Router in Next.js 13+, you may take advantage of React Server Components and streaming.

Consider supporting syntax-highlighting for code blocks (e.g., via rehype-prism or shiki).

Keep your posts directory clean and only commit final versions of posts (drafts might be hidden).

Always test linking between the blog index and post pages, and verify that metadata (e.g., date) is correct.

9. Summary

By following the structure from the Vercel blog example, you’ll end up with a blog powered by Next.js and MDX where:

Content lives in .mdx files, with front-matter metadata.

Next.js builds static pages for each post (or dynamically if you prefer).

You can embed React components inside your posts.

You have a blog index listing all posts with links.

Styling and component mapping ensures your markdown/MDX content looks polished.

Once you have this working, you can extend it with features like: tags/categories, pagination, search, RSS feed, share buttons, reading-time calculation, comments, and more.

10. Next steps for you

Clone or browse the Vercel example (vercel/examples → solutions/blog) to see the folder structure and how they’ve implemented the MDX integration.

Set up your own Next.js project and replicate the key pieces: next.config.mjs, posts/ folder, MDX renderer, blog index, post page.

Write a sample .mdx post that uses a custom React component.

Style the content, deploy to Vercel (if you like), and test everything.

Then, iterate: add tags, add search, add syntax highlighting, etc.

✍️ Written by Moses Kisakye

• Published on October 30, 2025