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.

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

Closed
6 tasks done
gillkyle opened this issue May 22, 2019 · 6 comments
Closed
6 tasks done

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

gillkyle opened this issue May 22, 2019 · 6 comments
Assignees
Labels
type: documentation An issue or pull request for improving or updating Gatsby's documentation

Comments

@gillkyle
Copy link
Contributor

gillkyle commented May 22, 2019

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

  • 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
  • fix example for exporting data and including it in the page
  • clarify the Defining a Layout section to explain that it will override the default layout applied by the gatsby-config
  • update the query example to be copy/paste-able
  • 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
Copy link
Contributor

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.

@gillkyle
Copy link
Contributor Author

gillkyle commented Jun 5, 2019

@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
Copy link
Contributor

jxnblk commented Jun 6, 2019

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
Copy link
Contributor Author

gillkyle commented Jun 6, 2019

@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
Copy link
Contributor

johno commented Jun 17, 2019

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
Copy link
Contributor Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: documentation An issue or pull request for improving or updating Gatsby's documentation
Projects
None yet
Development

No branches or pull requests

4 participants