[docs] [workflows] Embedding components in Markdown with MDX

[gillkyle]

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

User story

As a new Gatsby user, I want to embed my React components into Markdown with MDX.

Evaluation

[Change emoji below based on your evaluation.]

Search	Discover	Complete	Linked	Tone	Style	Overall
😐	😄	😐	😐	😄	😄	😄

Steps taken to implement

1. Searchability
   1. Searched gatsby markdown with mdx; clicked on the first result
2. Discoverability
   1. Searched gatsby mdx and clicked on 4th result: "Getting Started - Adding MDX to an Existing Site;
   2. Clickpath on .org (3 clicks):
      • clicked on Docs in Navbar
      • scrolled in Sidebar
      • clicked on Adding Components to Content with MDX
      • clicked on Getting Started guide
3. Completeness (WIP) Followed steps in guide:
   • thorough and brief getting started
   • the 2nd page linked to after getting started gets a lot more complicated
   • [rec] convert information about Gatsby rendering and internals into a note that is less emphasized, update headings to give a more definite explanation of what is happening in each section, explain keywords like frontmatter and what its purpose is
   • had issues with sections on exporting data and using queries, this section might be out of date [rec] fix example for exporting data and including it in the page
   • [rec] clarify the Defining a Layout section to explain that it will override the default layout applied by the gatsby-config, as well as update the query example to be copy/paste-able
4. Linkedness
   • the initial pages have plenty of links to other guides and docs, the more advanced pages could maybe include more links but it makes sense that as things get more advanced there are less references and they're likely outside the scope of this workflow
5. Tone 👍
6. Style 👍

Recommendations

• [x] convert information about Gatsby rendering and internals into a note that is less emphasized
• [x] update headings to give a more definite explanation of what is happening in each section, explain keywords like frontmatter and what its purpose is
• [x] fix example for exporting data and including it in the page
• [x] clarify the Defining a Layout section to explain that it will override the default layout applied by the gatsby-config
• [x] update the query example to be copy/paste-able
• [x] fix broken links for querying data on Writing Pages and "You can also use .md as a file extension if you want." on Programmatically Creating Pages

[marcysutton]

Great stuff! These improvements should really help.

I also searched on Google for "gatsby mdx" in incognito and regular mode, and these are the first 5 results:

• https://github.com/ChristopherBiscardi/gatsby-mdx
• https://mdxjs.com/getting-started/gatsby
• https://www.gatsbyjs.org/packages/gatsby-plugin-mdx/
• https://gatsby-mdx.netlify.com/
• https://www.npmjs.com/package/gatsby-mdx

The fact that there are docs spread across multiple sites makes it pretty confusing. This is a bigger conversation to have with @ChristopherBiscardi and @jxnblk, but I'm wondering if there's anything we could do to help these docs pages rank higher. They aren't even listed on the first page.

[gillkyle]

@marcysutton that's a really good point. It seems like things were developed outside and brought in as they were made stable, but where the docs for each should live seems like an important thing to evaluate.

[jxnblk]

As far as the search results go, should we go ahead and update the official MDX docs to point to the Gatsby docs? I suspect that would be a good place to start

[gillkyle]

@jxnblk that sounds like a good idea. I can change that.

It looks like some of the guides on gatsby-mdx.netlify.com (like Writing Pages) are also on .org, could the rest of those guides be consolidated on .org you think? @ChristopherBiscardi

[johno]

It looks like some of the guides on gatsby-mdx.netlify.com (like Writing Pages) are also on .org, could the rest of those guides be consolidated on .org you think? @ChristopherBiscardi

Yeah, the plan is to set up redirects on all relevant pages of gatsby-mdx.netlify.com to point to .org since that will house the official docs. That's probably something we should do sooner than later.

[gillkyle]

Closing and continuing in #14890 for a more focused effort on moving docs rather than updating this workflow about adding components