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

initial
gatsbyjs · Jan 19, 2023 · e4f841f · e4f841f
1 parent 48d4069
commit e4f841f
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 4 deletions.
diff --git a/docs/docs/reference/release-notes/migrating-from-v4-to-v5.md b/docs/docs/reference/release-notes/migrating-from-v4-to-v5.md
@@ -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.

diff --git a/packages/gatsby-plugin-mdx/README.md b/packages/gatsby-plugin-mdx/README.md
@@ -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)
@@ -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
@@ -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.
@@ -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.
@@ -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).