-
Notifications
You must be signed in to change notification settings - Fork 10.3k
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
[docs] [workflows] Embedding components in Markdown with MDX #14258
Comments
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:
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. |
@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. |
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 |
@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 |
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. |
Closing and continuing in #14890 for a more focused effort on moving docs rather than updating this workflow about adding components |
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.]
Steps taken to implement
gatsby markdown with mdx
; clicked on the first resultgatsby mdx
and clicked on 4th result: "Getting Started - Adding MDX to an Existing Site;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
Recommendations
The text was updated successfully, but these errors were encountered: