[docs][workflows] Centralizing MDX docs on Gatsbyjs.org

[gillkyle]

Part of the Top 25 Learning Workflows initiative. See #13708 for the meta issue that this issue falls under.

Description:

In an effort to centralize docs for MDX under the Gatsbyjs.org docs, all guides should be moved from the gatsby-mdx docs to .org. We should add createRedirects on the gatsby-mdx page as well to point users to Gatsby's docs where documentation will continue for what is now gatsby-plugin-mdx.

The name of the reference guides on MDX has been a question, should "Adding Components to Content with MDX" be changed to something that instead mentions adding JavaScript?

• add new page in Gatsby API section of the docs sidebar for MDX
• move docs from gatsby-mdx.netlify.com to .org
• create redirects from gatsby-mdx.netlify.com to corresponding pages on .org
• update references to https://gatsby-mdx.netlify.com/ to new docs on .org
• update references to gatsby-mdx to official plugin gatsby-plugin-mdx
• clarify docs on using frontmatter and imports in the same file

Related:

#14258

[marcysutton]

Here's a relevant comment from the feedback widget on gatsbyjs.org:

I had a problem using MDXProvider with MDXRenderer. The issue was, the gatsby-mdx docs say to import MDXRenderer from '@mdx-js/tag', which silently fails. This doc imports '@mdx-js/react', which works as expected.

[gillkyle]

Thanks, this is actually something I noticed too and have updated the example from the referred guide 👍

[robinmetral]

Quick aside: it took me a while to understand there were two ways of doing custom components, MDX and Rehype. Since we're trying to encourage MDX, shouldn't we recommend it over Rehype in gatsby-example-using-remark?

[gillkyle]

Yeah that's a good point @robinmetral, I know MDX uses rehype and remark internally (see here) so trying to push people towards MDX seems like a good idea there, though I think it's great to have that documentation still the same.

[gatsbot]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contributefor more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[lannonbr]

As gatsby-mdx.netlify.com now tells people to use gatsby-plugin-mdx instead, is there any remaining tasks for this issue?

[marcysutton]

There may be–we want to make sure the APIs are fully documented. @amberleyromo is taking that on

[jackbravo]

Seems like this effort is now finished, right? There is this new section: https://www.gatsbyjs.org/docs/mdx/ Should this issue be closed?

[marcysutton]

I checked in with Amberley and Kyle Gill, and it sounds like this one is indeed done now. Any remaining improvements can be handled in new issues and PRs. Thanks so much!