Gatsby: [docs][guides] new reference guide on Markdown and MDX syntax

[marcysutton]

It would help to pull Markdown syntax into a doc on the Gatsby site, so people know how to write it! This is especially true now that MDX is a key workflow. It would be helpful to cover syntax things, like:

• Frontmatter: what is it, and how do you use it (including when quotes are required for values)
• Headings, with recommendations for accessible heading order
• Emphasized text: italics and bold
• Links
• Lists
• Blockquotes
• Images with and without alt text
• Code comments

Functionally, it would help to know:

• Requirements for processing Markdown and MDX in Gatsby, e.g. gatsby-source-filesystem
• Notes about file extensions (.md? .mdx?)
• An example of frontmatter and imports in the same file (frontmatter comes first)
• How to wrap Markdown with HTML code for when you need it (MDX! woo!)

This doc should include enough details inline that someone who hasn't used Markdown or MDX before can get up and running. Linking to more information out on the web under "related resources" is great, too.

My current best recommendation for sidebar placement is under "Adding Components with MDX", but we could potentially create a new section for creating content and blogging. @amberleyromo any opinions on where to put a Markdown guide?

For anyone taking this on, it's recommended to follow the reference guide template: https://www.gatsbyjs.org/contributing/docs-templates/#reference-guides

And refer to the Gatsby Style Guide for additional conventions: https://www.gatsbyjs.org/contributing/gatsby-style-guide/

[rlynn523]

@Bculp and I would like to take this if it's still available!

[marcysutton]

@rlynn523 yes, it's open! We would love to have your contribution. Thanks for offering!

[dijonmusters]

Hey @rlynn523 and @bculp. I would also be keen to help out with this, if there is a section that could easily be sectioned off/if you run out of time 🙂

[rlynn523]

@marcysutton I started doing a rough draft of the syntax page and moved on to frontmatter...but the more I look through the docs, it seems like a lot of the information you want for the markdown reference guide is in the mdx docs. For example this has a pretty comprehensive table for md syntax. I believe there is also an example that shows needing to put frontmatter before imports, etc. Do you want to have an MDX section and MD section that show very similar info, or should we have a generic MD section that has info that is applicable to both MD and MDX, and then an MDX section nested under that with very MDX-specific info? Let me know what you think!

[marcysutton]

Ah, good catch! I definitely didn't realize it was in there...and I suspect it won't be easily discoverable for people who aren't looking for it in an MDX component doc. I'd recommend creating a new, longer doc with more general context (e.g. "MDXProvider" might be intimidating for people just getting started with Markdown). We can always make updates to that MDX page later on to make it less redundant, but more information in the docs on formatting Markdown is probably fine for now. Thanks for checking!

[rlynn523]

No problem! 👍

[rlynn523]

@marcysutton can you also assign @Bculp to this issue? We've been collaborating on it.

[marcysutton]

@rlynn523 I can't seem to add @Bculp, but that shouldn't impact your workflow.

[rlynn523]

I think we covered everything. I'm planning on putting in a PR tomorrow!

[rlynn523]

@marcysutton here is the link to the PR https://github.com/gatsbyjs/gatsby/pull/15861

[marcysutton]

Closed with #15861. Thanks so much for your work on this, @Bculp and @rlynn523!