Unverified Commit 5bf7265c authored by Markos-Th09's avatar Markos-Th09 Committed by GitHub

Improvements to the MDX Docs and replaced a leftover reference to babel (#35332)

* Added next.config.mjs for @next/mdx

* Replaced leftover reference to babel

* Fixed formatting problem

* Added next-mdx-remote and @mdx-js/mdx as options
parent f6de29f9
...@@ -56,6 +56,27 @@ The following steps outline how to setup `@next/mdx` in your Next.js project: ...@@ -56,6 +56,27 @@ The following steps outline how to setup `@next/mdx` in your Next.js project:
}) })
``` ```
> Using MDX plugins will require using next.config.mjs because all the plugins are [ECMAScript modules](https://nodejs.org/api/esm.html)
```js
// next.config.mjs
import createMDX from '@next/mdx'
const withMDX = createMDX({
extension: /\.mdx?$/,
options: {
remarkPlugins: [],
rehypePlugins: [],
// If you use `MDXProvider`, uncomment the following line.
// providerImportSource: "@mdx-js/react",
},
})
module.exports = withMDX({
// Append the default value with md extensions
pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
})
```
3. Create a new MDX page within the `/pages` directory: 3. Create a new MDX page within the `/pages` directory:
```bash ```bash
...@@ -64,6 +85,14 @@ The following steps outline how to setup `@next/mdx` in your Next.js project: ...@@ -64,6 +85,14 @@ The following steps outline how to setup `@next/mdx` in your Next.js project:
- package.json - package.json
``` ```
## next-mdx-remote
On a remote database, use next-mdx-remote https://github.com/hashicorp/next-mdx-remote
## @mdx-js/mdx
Handle mdx strings client side, probably @mdx-js/mdx see official docs https://mdxjs.com/docs/getting-started/
## Using Components, Layouts and Custom Elements ## Using Components, Layouts and Custom Elements
You can now import a React component directly inside your MDX page: You can now import a React component directly inside your MDX page:
...@@ -86,7 +115,7 @@ Checkout my React component: ...@@ -86,7 +115,7 @@ Checkout my React component:
### Frontmatter ### Frontmatter
Frontmatter is a YAML like key/value pairing that can be used to store data about a page. `@next/mdx` does **not** support frontmatter by default, though there are many solutions for adding frontmatter to your MDX content, such as [gray-matter](https://github.com/jonschlinkert/gray-matter). Frontmatter is a YAML like key/value pairing that can be used to store data about a page. `@next/mdx` does **not** support frontmatter by default, though there are many solutions for adding frontmatter to your MDX content, such as [gray-matter](https://github.com/jonschlinkert/gray-matter) using [remark-frontmatter](https://github.com/remarkjs/remark-frontmatter).
To access page metadata with `@next/mdx`, you can export a meta object from within the `.mdx` file: To access page metadata with `@next/mdx`, you can export a meta object from within the `.mdx` file:
...@@ -98,6 +127,26 @@ author: 'Rich Haines' ...@@ -98,6 +127,26 @@ author: 'Rich Haines'
# My MDX page # My MDX page
``` ```
```js
// next.config.mjs
import createMDX from '@next/mdx'
import remarkFrontmatter from 'remark-frontmatter'
const withMDX = createMDX({
extension: /\.mdx?$/,
options: {
remarkPlugins: [remarkFrontmatter],
rehypePlugins: [],
// If you use `MDXProvider`, uncomment the following line.
// providerImportSource: "@mdx-js/react",
},
})
module.exports = withMDX({
// Append the default value with md extensions
pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
})
```
### Layouts ### Layouts
To add a layout to your MDX page, create a new component and import it into the MDX page. Then you can wrap the MDX page with your layout component: To add a layout to your MDX page, create a new component and import it into the MDX page. Then you can wrap the MDX page with your layout component:
...@@ -208,5 +257,8 @@ If you use it across the site you may want to add the provider to `_app.js` so a ...@@ -208,5 +257,8 @@ If you use it across the site you may want to add the provider to `_app.js` so a
- [MDX](https://mdxjs.com) - [MDX](https://mdxjs.com)
- [`@next/mdx`](https://www.npmjs.com/package/@next/mdx) - [`@next/mdx`](https://www.npmjs.com/package/@next/mdx)
- [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote)
- [next-mdx-remote example](https://github.com/vercel/next.js/tree/canary/examples/with-mdx-remote)
- [remark](https://github.com/remarkjs/remark) - [remark](https://github.com/remarkjs/remark)
- [rehype](https://github.com/rehypejs/rehype) - [rehype](https://github.com/rehypejs/rehype)
- [ECMAScript modules](https://nodejs.org/api/esm.html)
...@@ -84,4 +84,4 @@ The commented lines are the place where you can put the configs allowed by `next ...@@ -84,4 +84,4 @@ The commented lines are the place where you can put the configs allowed by `next
However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do. However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.
> Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack, Babel or TypeScript. > Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack, the compiler or TypeScript.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment