4911a27eae
Explains how to use the recent changes that allow for rendering MDX as server components. <!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change that you're making: --> ## Bug - [ ] Related issues linked using `fixes #number` - [ ] Integration tests added - [ ] Errors have a helpful link attached, see [`contributing.md`](https://github.com/vercel/next.js/blob/canary/contributing.md) ## Feature - [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [ ] Related issues linked using `fixes #number` - [ ] [e2e](https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) tests added - [ ] Documentation added - [ ] Telemetry added. In case of a feature if it's used or not. - [ ] Errors have a helpful link attached, see [`contributing.md`](https://github.com/vercel/next.js/blob/canary/contributing.md) ## Documentation / Examples - [ ] Make sure the linting passes by running `pnpm build && pnpm lint` - [ ] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md) Co-authored-by: Lee Robinson <me@leerob.io>
3.1 KiB
3.1 KiB
Next.js + MDX
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
// next.config.js
const withMDX = require('@next/mdx')()
module.exports = withMDX()
Optionally you can provide MDX plugins:
// 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
// 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
// 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:
// next.config.js
const withMDX = require('@next/mdx')({
extension: /\.mdx?$/,
})
module.exports = withMDX({
pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
})
TypeScript
Follow this guide 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-component.js
file at the root of your project with the following contents:
// 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
// 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,
mdxRs: 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 from the MDX docs.