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
|
|
|
})
|
|
|
|
```
|
|
|
|
|
|
|
|
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')({
|
2019-05-29 13:57:26 +02:00
|
|
|
extension: /\.(md|mdx)$/,
|
2019-03-04 18:02:45 +01:00
|
|
|
})
|
|
|
|
module.exports = withMDX()
|
|
|
|
```
|
|
|
|
|
|
|
|
## 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.
|