How to Use Markdown (MDX) with Next.js App Router

Feb 17, 2025

Next.js is a React-based framework that makes it easy to implement server-side rendering and static site generation. Recently, the App Router was introduced, making routing management more flexible. This article explains how to use Markdown (MDX) with Next.js App Router.

What is MDX?

MDX is a file format that combines Markdown and JSX. While maintaining the simplicity of Markdown, it allows you to embed React components, making it easy to create documents with dynamic content.

Setting up Next.js

First, create a Next.js project. Run the following command:

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

Next, install the necessary packages to use MDX:

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

Configuring MDX

Now, update the Next.js configuration file, either next.config.js or next.config.ts. Add the following code:

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
})

module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
})

This configuration allows you to treat MDX files as pages.

Creating an MDX file

Next, create a new folder called posts inside the pages folder, and create a file named example.mdx inside it. Here’s a sample content for example.mdx:

# MDX Sample

This is an example of an MDX file. Below is an example of a React component.

<MyComponent />

## Section

This section explains how to use MDX.

Creating a Component

Next, create a components folder and create a file named MyComponent.jsx or MyComponent.tsx. Here’s a sample content for MyComponent.jsx:

const MyComponent = () => {
  return <div>This is an embedded component.</div>
}

export default MyComponent;

Creating a Page

Finally, create a file named pages/posts/example.jsx or pages/posts/example.tsx and add the following code:

import Example from '../../posts/example.mdx'

const ExamplePage = () => {
  return <Example />
}

export default ExamplePage;

Starting the App

Once all the settings are complete, start the app:

npm run dev

Access http://localhost:3000/posts/example in your browser to confirm that the MDX file is displayed correctly.

Conclusion

This article introduced how to use Markdown (MDX) with Next.js App Router. By using MDX, you can combine the convenience of Markdown with the flexibility of React components to create richer content. Try incorporating it into your own projects!