# Next.js + MDX Use [MDX](https://github.com/mdx-js/mdx) with [Next.js](https://github.com/vercel/next.js) ## Installation For usage with the `app` directory see the section below. ``` npm install @next/mdx @mdx-js/loader @mdx-js/react ``` or ``` yarn add @next/mdx @mdx-js/loader @mdx-js/react ``` ## Usage Create a `next.config.js` in your project ```js // next.config.js const withMDX = require('@next/mdx')() module.exports = withMDX() ``` Optionally you can provide [MDX plugins](https://mdxjs.com/advanced/plugins#plugins): ```js // next.config.js const withMDX = require('@next/mdx')({ options: { remarkPlugins: [], rehypePlugins: [], }, }) module.exports = withMDX() ``` Optionally you can add your custom Next.js configuration as parameter ```js // next.config.js const withMDX = require('@next/mdx')() module.exports = withMDX({ webpack(config, options) { return config }, }) ``` Optionally you can match other file extensions for MDX compilation, by default only `.mdx` is supported ```js // next.config.js const withMDX = require('@next/mdx')({ extension: /\.(md|mdx)$/, }) module.exports = withMDX() ``` ## Top level .mdx pages Define the `pageExtensions` option to have Next.js handle `.md` and `.mdx` files in the `pages` directory as pages: ```js // next.config.js const withMDX = require('@next/mdx')({ extension: /\.mdx?$/, }) module.exports = withMDX({ pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'], }) ``` ## TypeScript Follow [this guide](https://mdxjs.com/advanced/typescript) from the MDX docs. --- # App directory ## Installation For usage with the `app` directory see below. ``` npm install @next/mdx ``` or ``` yarn add @next/mdx ``` ## Usage Create a `mdx-components.js` file at the root of your project with the following contents: ```js // This file is required to use @next/mdx in the `app` directory. export function useMDXComponents(components) { return components // Allows customizing built-in components, e.g. to add styling. // return { // h1: ({ children }) =>