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.

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:

    1.   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:

    1. // next.config.js
    3. const withMDX = require('@next/mdx')({
    4.   extension: /\.mdx?$/,
    5.   options: {
    6.     remarkPlugins: [],
    7.     rehypePlugins: [],
    8.     // If you use `MDXProvider`, uncomment the following line.
    9.     // providerImportSource: "@mdx-js/react",
    10.   },
    11. })
    12. module.exports = withMDX({
    13.   // Append the default value with md extensions
    14.   pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
    15. })

  3. Create a new MDX page within the /pages directory:

    1.   - /pages
    2.     - my-mdx-page.mdx
    3.   - package.json

Using Components, Layouts and Custom Elements

You can now import a React component directly inside your MDX page:

  1. import { MyComponent } from 'my-components'
  3. # My MDX page
  5. This is a list in markdown:
  7. - One
  8. - Two
  9. - Three
  11. Checkout my React component:
  13. <MyComponent/>

Frontmatter

Frontmatter is a YAML like key/value pairing that can be used to store data about a page. @next/mdx does not support frontmatter by default, though there are many solutions for adding frontmatter to your MDX content, such as gray-matter.

To access page metadata with @next/mdx, you can export a meta object from within the .mdx file:

  1. export const meta = {
  2. author: 'Rich Haines'
  3. }
  5. # My MDX page

Layouts

To add a layout to your MDX page, create a new component and import it into the MDX page. Then you can wrap the MDX page with your layout component:

  1. import { MyComponent, MyLayoutComponent } from 'my-components'
  3. export const meta = {
  4. author: 'Rich Haines'
  5. }
  7. # My MDX Page with a Layout
  9. This is a list in markdown:
  11. - One
  12. - Two
  13. - Three
  15. Checkout my React component:
  17. <MyComponent/>
  19. export default ({ children }) => <MyLayoutComponent meta={meta}>{children}</MyLayoutComponent>

Custom Elements

One of the pleasant aspects of using markdown, is that it maps to native HTML elements, making writing fast, and intuitive:

  1. # H1 heading
  3. ## H2 heading
  5. This is a list in markdown:
  7. - One
  8. - Two
  9. - Three

The above generates the following HTML:

  1. <h1>H1 heading</h1>
  3. <h2>H2 heading</h2>
  5. <p>This is a list in markdown:</p>
  7. <ul>
  8.   <li>One</li>
  9.   <li>Two</li>
  10.   <li>Three</li>
  11. </ul>

When you want to style your own elements to give a custom feel to your website or application, you can pass in shortcodes. These are your own custom components that map to HTML elements. To do this you use the MDXProvider and pass a components object as a prop. Each object key in the components object maps to a HTML element name.

To enable you need to specify providerImportSource: "@mdx-js/react" in next.config.js.

  1. // next.config.js
  3. const withMDX = require('@next/mdx')({
  4.   // ...
  5.   options: {
  6.     providerImportSource: '@mdx-js/react',
  7.   },
  8. })

Then setup the provider in your page

  1. // pages/index.js
  3. import { MDXProvider } from '@mdx-js/react'
  4. import Image from 'next/image'
  5. import { Heading, InlineCode, Pre, Table, Text } from 'my-components'
  7. const ResponsiveImage = (props) => (
  8.   <Image alt={props.alt} layout="responsive" {...props} />
  9. )
  11. const components = {
  12.   img: ResponsiveImage,
  13.   h1: Heading.H1,
  14.   h2: Heading.H2,
  15.   p: Text,
  16.   pre: Pre,
  17.   code: InlineCode,
  18. }
  20. export default function Post(props) {
  21.   return (
  22.     <MDXProvider components={components}>
  23.       <main {...props} />
  24.     </MDXProvider>
  25.   )
  26. }

If you use it across the site you may want to add the provider to _app.js so all MDX pages pick up the custom element config.