diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx
index 35681f2de..1d3b9afdb 100644
--- a/docs/docs/getting-started.server.mdx
+++ b/docs/docs/getting-started.server.mdx
@@ -549,7 +549,7 @@ the loader to the webpack config, by rewiring `react-scripts` using
**Note**: warnings about CRACO having `incorrect peer dependency
- "react-scripts@^4.0.0"` can be ignored for the above to work.
+ "react-scripts@^4.0.0"` can be ignored for the above to work.
See also [¶ Webpack][webpack], which is used in CRA, and see [¶ React][react],
@@ -573,40 +573,67 @@ on how to use MDX with Gatsby.
Expand example
```js path="next.config.js"
- module.exports = {
- // Prefer loading of ES Modules over CommonJS
- experimental: {esmExternals: true},
+ import nextMDX from '@next/mdx'
+
+ const withMDX = nextMDX({
+ // By default only the .mdx extension is supported.
+ extension: /\.mdx?$/,
+ options: {/* providerImportSource: …, otherOptions… */}
+ })
+
+ export default withMDX({
// Support MDX files as pages:
pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
- // Support loading `.md`, `.mdx`:
- webpack(config, options) {
- config.module.rules.push({
- test: /\.mdx?$/,
- use: [
- // The default `babel-loader` used by Next:
- options.defaultLoaders.babel,
- {
- loader: '@mdx-js/loader',
- /** @type {import('@mdx-js/loader').Options} */
- options: {/* jsxImportSource: …, otherOptions… */}
- }
- ]
- })
-
- return config
- }
- }
+ })
```
-[Next](https://nextjs.org) supports webpack loaders by overwriting the webpack
-config in `next.config.js`.
+[Next.js](https://nextjs.org) has its own package to support MDX.
-Install and configure the webpack loader [`@mdx-js/loader`][webpack].
+Install and configure [`@next/mdx`][@next/mdx].
There is no need to configure your JSX runtime as React is already set up.
-See also [¶ Webpack][webpack] and [¶ React][react], which you’re using, for
-more on those tools.
+The MDX provider can be configured in [`pages/_app.js`][next-app].
+In order to use it, you need to configure the `providerImportSource` as
+well.
+
+
+ Expand example
+
+ ```js path="next.config.js"
+ import nextMDX from '@next/mdx'
+
+ const withMDX = nextMDX({
+ // By default only the .mdx extension is supported.
+ extension: /\.mdx?$/,
+ options: {providerImportSource: '@mdx-js/react', /* otherOptions… */}
+ })
+
+ export default withMDX({
+ // Support MDX files as pages:
+ pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
+ })
+ ```
+
+ ```jsx path="pages/_app.js"
+ import {MDXProvider} from '@mdx-js/react'
+ import {Header} from '../components/Header.js'
+
+ const components = {
+ h1: Header
+ }
+
+ export default function App({Component, pageProps}) {
+ return (
+
+
+
+ )
+ }
+ ```
+
+
+See [Using MDX with Next.js][next-mdx] for more details.
#### Parcel
@@ -842,6 +869,8 @@ See their readmes on how to configure them.
* If you’re getting errors integrating MDX, see
[§ Troubleshooting MDX][trouble] or [§ Support][support]
+[@next/mdx]: https://github.com/vercel/next.js/tree/canary/packages/next-mdx
+
[svelte-jsx]: https://github.com/kenoxa/svelte-jsx
[jsx]: #jsx
@@ -874,6 +903,10 @@ See their readmes on how to configure them.
[mdx-vue]: /packages/vue/
+[next-app]: https://nextjs.org/docs/advanced-features/custom-app
+
+[next-mdx]: https://nextjs.org/docs/advanced-features/using-mdx
+
[evaluate]: /packages/mdx/#evaluatefile-options
[options-jsximportsource]: /packages/mdx/#optionsjsximportsource