[docs] [workflows] Improve docs for setting up a blog that pulls content from Markdown

[prestonso]

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 create a blog that pulls content and images from Markdown and allows me to query it.

Evaluation

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

Steps taken to implement

1. Searchability
   1. Searched gatsby markdown blog on Google; clicked first result.
2. Discoverability
   1. Searched gatsby markdown blog in search bar; all listed results take user to Adding Markdown pages.
   2. Clickpath on .org:
      1. Clicked Docs.
      2. Clicked Recipes > Creating pages. Nothing there.
      3. Back to Docs.
      4. Clicked Tutorial > 4. Querying for data in a blog. Nothing there.
      5. Back to Docs.
      6. Clicked Guides. Nothing there about blogs or Markdown.
      7. Back to Docs.
      8. Searched again due to frustration. Found page hidden under breadcrumb: Guides > Querying Your Data with GraphQL > Adding Markdown Pages.
      9. Result: Not discoverable under current IA.
3. Completeness
   1. Followed steps in Install gatsby-source-filesystem. [rec] Configuring but no suggested path to mkdir at (e.g. /blog/). More explicit guidance on this page would be helpful.
   2. Configured gatsby-source-filesystem with /articles path and markdown-articles name.
   3. Followed steps in Install gatsby-transformer-remark.
   4. Followed steps in "Note on creating Markdown files". [rec] This is not very helpful in terms of where to place the Markdown files (in /articles?). No guidance on YYYY-MM-DD-lorem-ipsum-dolor-sit-amet/index.md file naming.
   5. Followed steps in Create a page template for the Markdown data.
   6. Followed steps in Create static pages using Gatsby's Node API.
   7. Success!
4. Linkedness
   1. Useful apart from external GraphQL resource link
   2. Node API specification link is very helpful
5. Tone
   1. Sometimes heavy on technical terminology; perhaps not completely understandable to a web development beginner.
   2. [rec] Sideline some of the extraneous information that we don’t need as a note, e.g. "Gatsby calls the createPages API (if present)"
6. Style
   1. [rec] Only minor issues (punctuation is inconsistent; periods at ends of headings and hyphens instead of em-dashes)
7. General notes
   1. [rec] Much more visibility of "how to create a blog" or some such title instead of "Querying your data with GraphQL" required.

Recommendations

• Install gatsby-source-filesystem: Configuring but no suggested path to mkdir at (e.g. /blog/). Add more explicit guidance on this page.
• Note on creating Markdown files: This is not very helpful in terms of where to place the Markdown files (in /articles?). Add more explicit guidance on YYYY-MM-DD-lorem-ipsum-dolor-sit-amet/index.md file naming.
• Tone: Sideline some of the extraneous information that we don’t need as a note, e.g. "Gatsby calls the createPages API (if present)".
• Style: Correct minor issues (punctuation is inconsistent; periods at ends of headings and hyphens instead of em-dashes).
• General: Add visibility by retitling to "how to create a blog" or some such title instead of "Querying your data with GraphQL". (will be addressed in a future PR)

[paschalidi]

@prestonso hey, wow thats a nice process here. Looks very clear thanks!
Discoverability is on the third level and I would like to help move it up to the first level! 🥇

If I get this right from the Recommendations PR's need to be created and therefore the issue should be addressed this way.
I am thinking, is that the way to go or do you have a better idea in mind? 🤔

Thanks a lot for taking good care of this! 🙏

[gillkyle]

@paschalidi a PR will need to be created to address the checklist items in the Recommendations above, yes 🙂 this is just 1 of the 25 workflows that are being improved as addressed in #13708

That would mean improving the docs according to those points made by @prestonso

Would you like to help take that on @paschalidi?

[paschalidi]

✨✨Yeah I would love to help with that! Thanks a lot for making this possible!
Some of the points are a little bit generic, for me at least. Would be super awesome if we can maybe define actionables so that I can open PR's that correspond better to the what @prestonso vision of this is!

Given each point I will try to raise questions that might pop up or express what I would do, so that we can be better aligned and sure all of us are in the same page.
Hope that you find this somehow helpful.

Install gatsby-source-filesystem: Configuring but no suggested path to mkdir at (e.g. /blog/). Add more explicit guidance on this page.

Hmm can we please discuss a little bit further what we would like to have as result here. 🙇 Thanks

Note on creating Markdown files: This is not very helpful in terms of where to place the Markdown files (in /articles?). Add more explicit guidance on YYYY-MM-DD-lorem-ipsum-dolor-sit-amet/index.md file naming.

What I would do here is add some extra documentation on where and how to name the md files.

Tone: Sideline some of the extraneous information that we don’t need as a note, e.g. "Gatsby calls the createPages API (if present)".

Would be nice if we can be a little bit more specific here. I could have this "Gatsby calls the createPages API (if present)" as a note instead since this is obvious but I have the feeling @prestonso would like to have more changes here. Hmm can we please discuss this a little bit further?

Style: Correct minor issues (punctuation is inconsistent; periods at ends of headings and hyphens instead of em-dashes).

Straightforward. 👍 🥇

General: Add visibility by retitling to "how to create a blog" or some such title instead of "Querying your data with GraphQL".

Straightforward. 🥇

Thanks for taking the time to make those great notes @prestonso and thanks @gillkyle for helping out with this!

[gillkyle]

Great! Thanks for being willing to pitch in @paschalidi!

---

In reference to this first point:

Install gatsby-source-filesystem: Configuring but no suggested path to mkdir at (e.g. /blog/). Add more explicit guidance on this page.

Hmm can we please discuss a little bit further what we would like to have as result here. 🙇 Thanks

I think the note from @prestonso is saying that this link (https://www.gatsbyjs.org/docs/adding-markdown-pages/#read-files-into-gatsby-from-the-filesystem---gatsby-source-filesystem) discusses how to configure the plugin with gatsby-config, but it could be more exact in specifying where that it will look for the path defined in the options passed in. Maybe say that the /path/to/markdown/files could be located in the /src/blog directory to eliminate any confusion. Being really specific is super helpful in these guides.

---

Tone: Sideline some of the extraneous information that we don’t need as a note, e.g. "Gatsby calls the createPages API (if present)".

Would be nice if we can be a little bit more specific here. I could have this "Gatsby calls the createPages API (if present)" as a note instead since this is obvious but I have the feeling @prestonso would like to have more changes here. Hmm can we please discuss this a little bit further?

This sounds like removing some of the wording that isn't as relevant or feels too complicated. The phrase about "Gatsby calls the createPages API..." could be taken out of that paragraph and put into a NOTE: sort of like what is done in this example. Those notes are a good place to link to more advanced documentation and guides.

Appreciate your help! 👍

[paschalidi]

@gillkyle amazing! thanks for the quick response!

[prestonso]

Thanks for your help on this @paschalidi. I'll unassign and let you take this on!

[paschalidi]

@prestonso you are very welcome! thanks for the amazing initial work and report!

[gatsbot]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contributefor more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[gillkyle]

Have you been able to make some progress on this @paschalidi? 🙂

[paschalidi]

heya @gillkyle have a look here #13851

[gillkyle]

@paschalidi Awesome! Sorry I missed the PR getting merged in the issue activity further up the page 😅 I'll close this issue and check it off as done on the meta issue. It'll be great to figure out the searchability stuff with Algolia as I think that could benefit several of the other workflows that have encountered similar issues.

[paschalidi]

heya @gillkyle no need to apologise! 👍 keep it up!