-
Notifications
You must be signed in to change notification settings - Fork 26.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improvements to the MDX Docs and replaced a leftover reference to babel #35332
Changes from all commits
04a7a5f
1a10005
64cb746
8d2f117
3647515
11d045a
4553c06
961927d
f883cff
569d56f
f07ad0a
40455ec
f448f81
d26fac1
cfd286f
4b4c46a
d926a03
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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: | ||
|
||
```bash | ||
|
@@ -64,6 +85,14 @@ The following steps outline how to setup `@next/mdx` in your Next.js project: | |
- 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/ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can we revert this or fix forward? This is not a complete sentence or using a correct link. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah I think we should revert based on my other comment. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah it needs to be fixed |
||
|
||
## Using Components, Layouts and Custom Elements | ||
|
||
You can now import a React component directly inside your MDX page: | ||
|
@@ -86,7 +115,7 @@ Checkout my React component: | |
|
||
### 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: | ||
|
||
|
@@ -98,6 +127,26 @@ author: 'Rich Haines' | |
# 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 | ||
|
||
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 | |
|
||
- [MDX](https://mdxjs.com) | ||
- [`@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) | ||
- [rehype](https://github.com/rehypejs/rehype) | ||
- [ECMAScript modules](https://nodejs.org/api/esm.html) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think this is accurate. Could someone confirm?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
e.g. works fine here https://github.com/leerob/leerob.io/blob/main/next.config.js
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Most plugins are esm modules. Even remark and rehype themselves are.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cc @timneutkens, who told me it was correct.