---
description: Learn how to use @next/mdx in your Next.js project.
---
# Using MDX with Next.js
MDX is a superset of markdown that lets you write JSX directly in your markdown files. It is a powerful way to add dynamic interactivity, and embed components within your content, helping you to bring your pages to life.
Next.js supports MDX through a number of different means, this page will outline some of the ways you can begin integrating MDX into your Next.js project.
## Why use MDX?
Authoring in markdown is an intuitive way to write content, its terse syntax, once adopted, can enable you to write content that is both readable and maintainable. Because you can use `HTML` elements in your markdown, you can also get creative when styling your markdown pages.
However, because markdown is essentially static content, you can't create _dynamic_ content based on user interactivity. Where MDX shines is in its ability to let you create and use your React components directly in the markup. This opens up a wide range of possibilities when composing your sites pages with interactivity in mind.
## MDX Plugins
Internally MDX uses remark and rehype. Remark is a markdown processor powered by a plugins ecosystem. This plugin ecosystem lets you parse code, transform `HTML` elements, change syntax, extract frontmatter, and more. Using [remark-gfm to enable GitHub flavored markdown (GFM)](https://mdxjs.com/guides/gfm/) is a popular option.
Rehype is an `HTML` processor, also powered by a plugin ecosystem. Similar to remark, these plugins let you manipulate, sanitize, compile and configure all types of data, elements and content.
To use a plugin from either remark or rehype, you will need to add it to the MDX packages config.
## `@next/mdx`
The `@next/mdx` package is configured in the `next.config.js` file at your projects root. **It sources data from local files**, allowing you to create pages with a `.mdx` extension, directly in your `/pages` directory.
### Setup `@next/mdx` in Next.js
The following steps outline how to setup `@next/mdx` in your Next.js project:
1. Install the required packages:
```bash
npm install @next/mdx @mdx-js/loader @mdx-js/react
```
2. Require the package and configure to support top level `.mdx` pages. The following adds the `options` object key allowing you to pass in any plugins:
```js
// next.config.js
const withMDX = require('@next/mdx')({
extension: /\.mdx?$/,
options: {
// If you use remark-gfm, you'll need to use next.config.mjs
// as the package is ESM only
// https://github.com/remarkjs/remark-gfm#install
remarkPlugins: [],
rehypePlugins: [],
// If you use `MDXProvider`, uncomment the following line.
// providerImportSource: "@mdx-js/react",
},
})
module.exports = withMDX({
// Append the default value with md extensions
pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
})
```
3. Create a new MDX page within the `/pages` directory:
```bash
- /pages
- my-mdx-page.mdx
- package.json
```
## Using Components, Layouts and Custom Elements
You can now import a React component directly inside your MDX page:
```md
import { MyComponent } from 'my-components'
# My MDX page
This is a list in markdown:
- One
- Two
- Three
Checkout my React component:
This is a list in markdown: