Skip to content
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

Added guide for setting up Next.js with MDX #30869

Merged
merged 16 commits into from
Nov 22, 2021
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions docs/advanced-features/using-mdx.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ The following steps outline how to setup `@next/mdx` in your Next.js project:

1. Install the required packages:

```terminal
```bash
npm install @next/mdx @mdx-js/loader
```

Expand Down Expand Up @@ -63,15 +63,11 @@ The following steps outline how to setup `@next/mdx` in your Next.js project:

## Using Components, Layouts and Custom Elements

You can now import a React component directly inside your MDX page. Note that `@next/mdx` does **not** support frontmatter (frontmatter is a YAML like key/value pairing that can be used to store data about a page), instead, you can export data from within the `.mdx` file:
You can now import a React component directly inside your MDX page:

```md
import { MyComponent } from 'my-components'

export const meta = {
author: 'Rich Haines'
}

# My MDX page

This is a list in markdown:
Expand All @@ -85,6 +81,20 @@ Checkout my React component:
<MyComponent/>
```

### 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).

To access page metadata with `@next/mdx`, you can export a meta object from within the `.mdx` file:

```md
export const meta = {
author: 'Rich Haines'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like we didn't get this spacing adjusted - maybe it needs to be js instead of md?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, that could be it! Rather odd. We should adjust the config for that, as I pulled this out so js makes sense, but it was in the context of an md file, so should format.

}

# My MDX page
```

### 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:
Expand Down Expand Up @@ -180,4 +190,3 @@ export default function Post(props) {
- [`@next/mdx`](https://www.npmjs.com/package/@next/mdx)
- [remark](https://github.com/remarkjs/remark)
- [rehype](https://github.com/rehypejs/rehype)
- [gray-matter: Adding frontmatter to your MDX file](https://github.com/jonschlinkert/gray-matter)