Building a Blog with Next.js and MDX: Full Tutorial

Why Next.js and MDX for a Blog?

MDX is Markdown with embedded JSX — you can write blog posts in Markdown and embed React components anywhere in the content. For developer blogs, this means syntax-highlighted code blocks, interactive demos, custom callout boxes, and data visualizations inside your prose. Next.js provides SSG for fast static pages, and the combination gives you a content-rich, high-performance blog.

Setting Up MDX in Next.js

Install @next/mdx and the required remark/rehype plugins. Configure next.config.js to use the withMDX wrapper. Add mdx to the pageExtensions array so Next.js treats .mdx files as pages. Install rehype-highlight or rehype-pretty-code for syntax highlighting, remark-gfm for GitHub-flavored Markdown (tables, strikethrough, task lists), and rehype-slug for anchor links on headings.

Organizing Blog Post Content

Store blog posts as .mdx files in an app/blog directory or a content/blog folder. Export frontmatter data (title, date, excerpt, tags) as a JavaScript object from each file. Create a utility function that reads all MDX files, parses their frontmatter, and returns sorted post metadata for the blog listing page. Use next/mdx's compile function or the contentlayer library to handle the MDX compilation pipeline.

Custom MDX Components

Override default HTML elements with custom React components via the MDXProvider or the components prop. Replace the default code block with a syntax-highlighted version, p with a styled paragraph, img with next/image for optimization, and a with Next.js Link for client-side navigation. Add custom components like Callout, CodeSandbox, Tweet, and YouTube that can be used anywhere in your MDX content.

SEO for Your MDX Blog

Export a generateMetadata function from each blog post page that returns the title, description, OpenGraph image, and canonical URL from the post's frontmatter. Use a dynamic OG image approach with Next.js ImageResponse to auto-generate custom social sharing images for each post. Add JSON-LD structured data for Article schema to enable rich results in Google Search.

Content Management Workflow

For a solo developer blog, writing MDX files in VS Code with live preview is a smooth workflow. Use the MDX VS Code extension for syntax highlighting. For multi-author blogs or non-developer content editors, connect to a headless CMS (Contentlayer with local files, or Sanity/Contentful for a visual editor). Git-based CMS options like Decap CMS give non-developers a UI while keeping content in your repository.