f9022d7e6c
Fixes a small typo in the `@next/mdx` [readme](url). The file that needs to be created is `mdx-components.{js,jsx,ts,tsx}`, not `mdx-component.{js,jsx,ts,tsx}`.
- Original MR where change was introduced: https://github.com/vercel/next.js/pull/44651/files#diff-bdcc8e0f4068c2d8bc8f1225c9776f3ec581e79a457abe748a053148925610d1R25
- This is also confirmed by the `app-dir-mdx` example: 3b1aa1c941/examples/app-dir-mdx/mdx-components.tsx
## 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)
150 lines
3 KiB
Markdown
150 lines
3 KiB
Markdown
# 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 }) => <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.
|