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.

Sign up for GitHub

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

Jump to bottom

chore(docs): Improve v5 migration guide around MDX #37485

Merged
merged 1 commit into from
Jan 19, 2023
Merged

chore(docs): Improve v5 migration guide around MDX #37485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 2 additions & 0 deletions docs/docs/reference/release-notes/migrating-from-v4-to-v5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,8 @@ The default setting for the `output` option changed from `/sitemap` to `/`. This

You can uninstall `remark-unwrap-images` from your project if you used it inside the `mdxOptions.remarkPlugins` array.

**Please note:** If you haven't done the [migration from v3 to v4 for `gatsby-plugin-mdx`](/plugins/gatsby-plugin-mdx/#migrating-from-v3-to-v4), please be aware that you'll **need to** go through that migration process if you want to use the latest version of `gatsby-plugin-mdx` with Gatsby 5.

## Future breaking changes

This section explains deprecations that were made for Gatsby 5. These old behaviors will be removed in v6, at which point they will no longer work. For now, you can still use the old behaviors in v5, but we recommend updating to the new signatures to make future updates easier.
Expand Down
14 changes: 10 additions & 4 deletions packages/gatsby-plugin-mdx/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@

MDX is markdown for the component era. It lets you write JSX embedded inside markdown. It’s a great combination because it allows you to use markdown’s often terse syntax (such as `# heading`) for the little things and JSX for more advanced components.

## Table of contents
<details>
<summary><strong>Table of contents</strong></summary>

Table of contents

- [Installation](#installation)
- [Usage](#usage)
Expand All @@ -24,6 +27,8 @@ MDX is markdown for the component era. It lets you write JSX embedded inside mar
- [Why MDX?](#why-mdx)
- [Related](#related)

</details>

## Installation

```shell
Expand Down Expand Up @@ -554,13 +559,11 @@ Read more about injecting your own components in the [official MDX provider guid

`gatsby-plugin-mdx@^4.0.0` is a complete rewrite of the original plugin with the goal of making the plugin faster, compatible with [MDX v2](https://mdxjs.com/blog/v2/), leaner, and more maintainable. While doing this rewrite we took the opportunity to fix long-standing issues and remove some functionalities that we now think should be handled by the user, not the plugin. In doing so there will be of course breaking changes you'll have to handle – but with the help of this migration guide and the codemods you'll be on the new version in no time!

**Please Note:** Loading MDX from other sources as the file system is not yet supported in `gatsby-plugin-mdx@^4.0.0`.

### Updating dependencies

```shell
npm remove @mdx-js/mdx
npm install gatsby@latest gatsby-plugin-mdx@latest @mdx-js/react@latest
npm install gatsby-plugin-mdx@latest @mdx-js/react@latest
```

If you used any related plugins like `gatsby-remark-images`, also update them to their `@latest` version.
Expand Down Expand Up @@ -715,6 +718,8 @@ In our testing, most of the time the issue were curly brackets that needed to be
+ You can upload this to `Git{Hub,Lab}`
```

You can also use [`eslint-mdx`](https://github.com/mdx-js/eslint-mdx) to find all culprits and in some cases automatically fix them through ESLint.

### Updating MDX nodes

Since most MDX nodes are moved to userland you'll have to [extend the GraphQL MDX nodes](#extending-the-graphql-mdx-nodes) and update your queries accordingly. However, you can [alias your `fields`](https://www.gatsbyjs.com/docs/reference/graphql-data-layer/schema-customization/#aliasing-fields) to have them at the root of the GraphQL node.
Expand Down Expand Up @@ -778,6 +783,7 @@ exports.createSchemaCustomization = ({ actions }) => {
- Removed `timeToRead`, `rawBody`, `slug`, `headings`, `html`, `mdxAST`, `wordCount`, `fileAbsolutePath` from the query result. You can check [Extending the GraphQL MDX nodes](#extending-the-graphql-mdx-nodes) to learn how to re-implement some of them on your own. Also check [Updating MDX nodes](#updating-mdx-nodes) for guidance on changing your queries
- `gatsby-plugin-mdx` only applies to local files (that are sourced with `gatsby-source-filesystem`)
- Removed the ability to use `js` and `json` in frontmatter
- Loading MDX from other sources as the filesystem is not supported. If you have a need for that, please comment in the [GitHub Discussion](https://github.com/gatsbyjs/gatsby/discussions/25068)
- All [MDX v2 migration](https://mdxjs.com/migrating/v2/) notes apply

As mentioned above the `html` field was removed from the GraphQL node. We know that some of you used this for e.g. `gatsby-plugin-feed`. Unfortunately, for compatibility and performance reasons we had to remove it. We recommend using the `excerpt` field in the meantime until we find a feasible solution to provide MDX rendered as HTML. If you have any suggestions, please comment on the [GitHub Discussion](https://github.com/gatsbyjs/gatsby/discussions/25068).
Expand Down