Add @next/mdx to Next.js getting started guide

Closes GH-2040. Reviewed-by: Titus Wormer <tituswormer@gmail.com>

Author: remcohaszing

docs/docs/getting-started.server.mdx

@@ -549,7 +549,7 @@ the loader to the webpack config, by rewiring `react-scripts` using
 
 <Note type="info">
  **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.
 </Note>
 
 See also [¶ Webpack][webpack], which is used in CRA, and see [¶ React][react],
@@ -573,40 +573,67 @@ on how to use MDX with Gatsby.
  <summary>Expand example</summary>
 
  ```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
- }
- }
+ })
  ```
 </details>
 
-[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.
+
+<details>
+ <summary>Expand example</summary>
+
+ ```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 (
+ <MDXProvider components={components}>
+ <Component {...pageProps} />
+ </MDXProvider>
+ )
+ }
+ ```
+</details>
+
+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