2019-03-04 18:02:45 +01:00
# Next.js + MDX
2020-05-27 23:51:11 +02:00
Use [MDX ](https://github.com/mdx-js/mdx ) with [Next.js ](https://github.com/vercel/next.js )
2019-03-04 18:02:45 +01:00
## Installation
2023-01-26 21:31:49 +01:00
For usage with the `app` directory see the section below.
2019-03-04 18:02:45 +01:00
```
2022-09-09 21:12:36 +02:00
npm install @next/mdx @mdx -js/loader @mdx -js/react
2019-03-04 18:02:45 +01:00
```
or
```
2022-09-09 21:12:36 +02:00
yarn add @next/mdx @mdx -js/loader @mdx -js/react
2019-03-04 18:02:45 +01:00
```
## Usage
Create a `next.config.js` in your project
```js
// next.config.js
const withMDX = require('@next/mdx')()
module.exports = withMDX()
```
2020-03-28 20:20:48 +01:00
Optionally you can provide [MDX plugins ](https://mdxjs.com/advanced/plugins#plugins ):
2019-03-04 18:02:45 +01:00
```js
// next.config.js
const withMDX = require('@next/mdx')({
options: {
2020-03-28 20:20:48 +01:00
remarkPlugins: [],
rehypePlugins: [],
2019-05-29 13:57:26 +02:00
},
2019-03-04 18:02:45 +01:00
})
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
2019-05-29 13:57:26 +02:00
},
2019-03-04 18:02:45 +01:00
})
```
2023-06-14 07:53:04 +02:00
By default MDX will only match and compile MDX files with the `.mdx` extension.
However, it can also be optionally configured to handle markdown files with the `.md` extension, as shown below:
2019-03-04 18:02:45 +01:00
```js
// next.config.js
const withMDX = require('@next/mdx')({
2019-05-29 13:57:26 +02:00
extension: /\.(md|mdx)$/,
2019-03-04 18:02:45 +01:00
})
module.exports = withMDX()
```
2023-06-14 07:53:04 +02:00
In addition, MDX can be customized with compiler options, see the [mdx documentation ](https://mdxjs.com/packages/mdx/#compilefile-options ) for details on supported options.
2019-03-04 18:02:45 +01:00
## Top level .mdx pages
2021-07-13 17:29:39 +02:00
Define the `pageExtensions` option to have Next.js handle `.md` and `.mdx` files in the `pages` directory as pages:
2019-03-04 18:02:45 +01:00
```js
// next.config.js
const withMDX = require('@next/mdx')({
2019-05-29 13:57:26 +02:00
extension: /\.mdx?$/,
2019-03-04 18:02:45 +01:00
})
module.exports = withMDX({
2021-12-27 00:43:47 +01:00
pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
2019-03-04 18:02:45 +01:00
})
```
2019-06-09 21:34:42 +02:00
2021-08-05 11:02:38 +02:00
## TypeScript
2019-06-09 21:34:42 +02:00
Follow [this guide ](https://mdxjs.com/advanced/typescript ) from the MDX docs.
2023-01-26 21:31:49 +01:00
---
# App directory
## Installation
For usage with the `app` directory see below.
```
npm install @next/mdx
```
or
```
yarn add @next/mdx
```
## Usage
2023-02-14 08:18:41 +01:00
Create a `mdx-components.js` file at the root of your project with the following contents:
2023-01-26 21:31:49 +01:00
```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 }) => < h1 style = {{ fontSize: " 100px " } } > {children}< / h1 > ,
// ...components,
// }
}
```
Create a `next.config.js` in your project
```js
// next.config.js
const withMDX = require('@next/mdx')({
// Optionally provide remark and rehype plugins
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",
},
})
/** @type {import('next').NextConfig} */
const nextConfig = {
// Configure pageExtensions to include md and mdx
pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
experimental: {
appDir: true,
}
// Optionally, add any other Next.js config below
reactStrictMode: true,
}
// Merge MDX config with Next.js config
module.exports = withMDX(nextConfig)
```
## TypeScript
Follow [this guide ](https://mdxjs.com/advanced/typescript ) from the MDX docs.