docs: Improve MDX section

[ghost]

Summary

Kindly update the following old blog post: https://www.gatsbyjs.org/blog/2017-07-19-creating-a-blog-with-gatsby/ so users may reference it but realize they may be wasting their time given MDX is a thing.

Some recommended topics to cover:

• Programmatically creating pages with MDX.
• How to convert an existing site to MDX.

Motivation

I was looking to programmatically create pages with MDX and, being new to Gatsby, didn't realize I didn't need to do much of anything mentioned in the old blog post to programmatically create pages. That said I found Dustin's post useful as a gentle introduction to creating pages programmatically. Only at the end I started hitting errors because I was already using MDX on my site.

Steps to resolve this issue

Add a notice at the top of the referenced blog post letting users know the information is slightly out of date and making them aware of MDX. Users will still find value in Dustin's content they just might feel miffed if they finish it and figure out it's time to migrate to MDX before they're even finished.

Draft the doc

Only if you share some of that investor capital with me.

Open a pull request

See Draft the doc sectoin for my thoughts on this.

---

Here are some errors users might hit if they already have MDX installed and they're still not a notice on Dustin's page which, to his credit, has great page rank and is likely to reel in more saps like me.

Expected type MarkdownRemarkFieldsEnum, found frontmatter___date
Unknown argument "frontmatter" on field "markdownRemark" of type "Query".

[ghost]

I had a bitch of a time getting the blog portion of an existing site set-up correctly. Seems this should be a solved problem with Gatsby but I did not find the experience as straightforward as I would expect for a 5 year-old platform. In the end I found all sorts of bad examples and documentation both in official Gatsby plug-ins and in the docs (like the MDX doc). What helped me in the end was this: https://github.com/DSchau/gatsby-theme-blog/blob/master/src/templates/blog-post.js

Without the above I found myself with a half-assed blog. The docs should cover things like the draft filter Dustin created as well as the fact users programmatically generating pages DO NOT NEED an entry for gatsby-plugin-page-creator in their gatsby-config when building out a site with MDX in pages and from pages created in gatsby-node. In fact, if the page creator is there, as is specified in the MDX docs, it'll cause issues and slow down builds.

[lannonbr]

Kindly update the following old blog post: https://www.gatsbyjs.org/blog/2017-07-19-creating-a-blog-with-gatsby/ so users may reference it but realize they may be wasting their time given MDX is a thing.

I don't think people are wasting their time not using MDX. It gives some benefits but just using Remark is completely fine.

you're commenting on "bad examples and docs" but not really listing what in particular is bad or messy. It would be much more helpful to point out specific thing so the core team could know exactly if there is content that needs to be refined.

if the page creator is there, as is specified in the MDX docs, it'll cause issues and slow down builds

What do you exactly mean by "it causes issues"?

[ghost]

@lannonbr I put specific links in the OP and gave general feedback in my second post. The point is getting a blog set-up isn't a simple ordeal for newcomers who want something that wasn't copy-pasted from a snippet in the docs. Please feel free to browse all of the docs and add more links here.

[ghost]

Following-up, here's another useful resource in addition to Dustin's repo I needed to even get a blog started. None of this was covered in the docs...

https://codereview.stackexchange.com/questions/238765/is-this-a-good-approach-for-creating-pages-for-multiple-content-typs-with-gatsby/238766

This answer is the one many people will want when adding a blog to an existing site with MDX content in src/pages to avoid duplication of content and unexpected routes generation. This should be covered in the MDX doc and a Gatsby "Best Practices" document of some kind created to prevent dev churn on this seemingly innocuous task.

Last thing I noticed in the docs which should be addressed is how to correctly create slugs. I keep seeing docs and people using path fragments as if they were slugs (they're not). This is confusing. The docs need to never use a / in a slug identifier yet they are anyway which I find baffling.

[LekoArts]

Only if you share some of that investor capital with me. I had a bitch of a time half-assed blog

Please watch your language and adhere to our Code of Conduct as we want to feel everyone welcomed and your (sarcastic) language is helping no one.

---

I disagree that the blog post you mentioned in the first issue needs to be updated. It's an old blog post and as @lannonbr said remark isn't dead and as viable as always compared to MDX.

I'll let the docs team review the rest of your comments.

[ghost]

Thanks for taking a look. I'm confident users would benefit for a walkthru like Dustin's only using gatsby-plugin-mdx and updated to remove things like query BlogPostByPath and replace it with BlogPostBySlug which is used in other places in the docs.

Here's another spot in the docs where slug is used when it's actually a path being passed: https://www.gatsbyjs.org/docs/creating-slugs-for-pages/#create-slugs-in-gatsby-nodejs

Instead of this-is-my-slug for slug users end up with /this-is-my-slug/ which isn't a slug, which tempts users to rename to path but cannot because path is reserved. Having a clean way to produce actual slugs and override them from MDX/Remark markdown documents seems like a basic enough building block it should be covered in the docs.

I want to emphasis just once more the pattern provided by Jeremy Albright I linked ealrier. Without that pattern it's not intuitive how to prevent the creation of duplicitive routes using MDX (and I presume Remark) when MDX files are stored in both src/pages and somewhere else. That's a clear area for improvement and not something I feel most users should need to handle manually so it's possible there's an enhancement opportunity there.

[AishaBlake]

Hi, @balibebas. I can see that you're frustrated but I'm closing this issue for a couple of reasons. First, we don't generally do major rewrites to old blog posts like this. As @lannonbr and @LekoArts have said, I think the post is still useful. Please feel free to open additional issues if you notice anything other specific problems that need to be addressed.

In the future, it would be helpful to whoever picks up the issue (which potentially includes other contributors) if you would fill out the entire issue template. The sections you left out are largely meant to guide newer contributors who may, for example, not realize they have to add new pages to our doc-links.yaml file. They're not meant to suggest that any one person also closes the issue they're raising. I will continue to close any incomplete docs issues (or issues which don't adhere to our Code of Conduct) that I see.