Next.js MDX Explained — Content with Markdown and JSX

In this tutorial, you will learn about Next.js MDX Explained. We cover key concepts, practical examples, and best practices to help you master this topic.

Next.js MDX lets you write content using Markdown with embedded JSX components, combining the simplicity of Markdown with the power of React components for content-rich pages.

What You'll Learn

• @next/mdx setup
• MDX pages in App and Pages Router
• Custom MDX components
• Frontmatter for metadata
• Remark and rehype plugins

Why It Matters

MDX is ideal for blogs, documentation, and marketing pages. It allows non-developers to write Markdown while developers enhance content with interactive React components.

// next.config.js
const withMDX = require("@next/mdx")({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
});

/** @type {import("next").NextConfig} */
const nextConfig = {
  pageExtensions: ["js", "jsx", "ts", "tsx", "md", "mdx"],
};

module.exports = withMDX(nextConfig);

---
title: Getting Started with MDX
description: Learn how to use MDX in Next.js
date: 2026-06-28
---

import Callout from "@/components/Callout";
import CodeSandbox from "@/components/CodeSandbox";

# Getting Started with MDX

MDX combines the simplicity of Markdown with the power of JSX.

<Callout type="tip">
  You can use React components directly in your MDX content.
</Callout>

## Interactive Example

<CodeSandbox id="example" height={400} />

## Code Block

```jsx
function Hello() {
  return <h1>Hello from MDX!</h1>;
}

Expected output: MDX pages render with custom React components, frontmatter metadata, and syntax-highlighted code blocks.