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

[gehtmaguad]

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/site that pulls content and images from WordPress and allows me to query it.

Evaluation

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

Steps taken to implement

1. Searchability

   1. Searched gatsby wordpress on Google; clicked first result.

2. Discoverability

   1. Searchbar:
      1. Searched gatsby wordpress in search bar; only blog articles show up.
      2. Searched wordpress; Sourcing from WordPress pops up.
         [rec] searching for gatsby wordpress should bring up Sourcing from WordPress as well
      3. Blog Articles that pop up in the search do not link to Sourcing from WordPress at all.
   2. Clickpath on .org:
      1. Clicked Docs.
      2. Clicked Recipes > Creating pages. Nothing there.
      3. Back to Docs.
      4. Clicked Tutorial > 5. Source plugins and rendering queried data. Nothing there.
      5. Back to Docs.
      6. Clicked Guides > Sourcing Content and Data > Sourcing from (Headless) CMSs > Sourcing from WordPress.
      7. Discoverable

3. Completeness

   1. Followed steps in Sourcing from WordPress.
   2. Clicked on Link Quick Start guide which actually links to Gatsby.js Documentation. [rec] Either link to Quick Start or update link text.
   3. Clicked on Quick Start.
   4. Followed steps in Quick Start.
   5. Jumped back to Sourcing from WordPress.
   6. Followed steps in Configuring the plugin.
   7. Followed steps in Using WordPress data.
      1. Copied example code for gatsby-node.js.
      2. Suddenly a bit lost.The template referenced in the example code is not outlined in the Guide.
         1. Continued reading.
         2. Wrapping up section links to the example repo.
         3. Explored the example repo to find the template used in the Guide.
         4. gatsby-node.js in the example repo differs from that outlined in the Guide.
         5. Again a bit lost.
         6. Cloned the gatsby repo; cd into the using-wordpress example; configured the plugin, run npm install followed by npm run develop to get it running.
         7. Success!
            [rec] Outline template used in gatsby-node.js for completeness.
            [rec] Mention to run npm run develop to see the result in the browser or add a short description / a link on next steps.

4. Linkedness

   1. Links used in the guide are very useful.
   2. Links to get a deeper understanding are very helpful, such as
      1. GraphQL at build time
      2. automatically infer a GraphQL schema
   3. The following links reference wrong lines in source code on Github
      1. iterates through each post node
      2. based on whatever template you define
         [rec] Point to documentation instead of source code.

5. Tone

   1. Overall easy to read. Section after the gatsby-node.js config example goes into more details on the createPage action creator and is propably better located above the example or should have a heading. Also for beginners the term createPage bound action creator is probably not known and difficult to grasp. [rec] Refactoring of section

6. Style

   1. [rec] Only minor issues

7. General notes

   1. [rec] Unified layout for Sourcing from (Headless) CMSs articles could be considered (e.g. same structure of documentation between Sourcing from Wordpress, Sourcing from Drupal, ...).

Recommendations

• searching for gatsby wordpress should bring up Sourcing from WordPress
• Link Quick Start guide actually links to Gatsby.js Documentation. Either link to Quick Start or update link text.
• Outline template used in gatsby-node.js config example for completeness. Create a page template for the markdown data can be used as a reference.
• Mention to run npm run develop at the end of the guide to see the result in the browser or add a short description / a link on next steps.
• Fix broken links: Point to documentation instead of source code for
  1. iterates through each post node
  2. based on whatever template you define
• Refactoring of section The docs define a Gatsby page as “a site page with a pathname, a template component, and optional graphql query and layout component.” See the docs on the createPage bound action creator and guide on creating and modifying pages for more detail.

[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! 💪💜

[gatsbot]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

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/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community!

[gillkyle]

Hi @Haezl! Thanks for the evaluation, looks great. It looks like the bot closed this issue though I'm not aware anything ever got merged in to resolve the recommendations you made so I'll open the issue back up in case other folks want to help out too.

Have you been able to work on any more of those changes at all?

[gehtmaguad]

@gillkyle thx for having an eye on that. Haven't been able, but changes are good I can do some work in the next few days. I'm not aware on how to tackle the searchability issue through the Searchbar though, any references for this?

[gillkyle]

@Haezl no worries! If you have the bandwidth to make what changes you can that'd be great. It looks like the searchability issues like this are something that has been tracked elsewhere (#12503) and has been an issue in other places as well, it seems to be some sort of an issue with how Algolia indexes things.

If that's blocking you I'd just start on the other changes. It's possible other upstream fixes could resolve searchability things on gatsbyjs.org and the other recommendations would be valuable to get merged in at least 🙂

[gatsbot]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

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/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community!

[marcysutton]

Oops! This issue should still be open, as we still have this workflow in our queue. Thanks for your patience!

[gillkyle]

The PR I just linked to this issue should resolve the recommendations made in the original post 👍

[gehtmaguad]

@gillkyle awesome!

[jackbravo]

@gillkyle about point #1 in the description: searching for gatsby wordpress should bring up Sourcing from WordPress. I see that searching only for Wordpress does bring up that page from the documentation on the search results, but buried after blog posts. If you search for gatsby wordpress then you get only results from blog posts. Seems to me like documentation results should have a higher priority than blog post results, don't you think? Specially because documentation pages should be more up to date than blog posts that don't get updated after they are written. Maybe that should be a new issue?

[gillkyle]

I see that Marcy responded to you on the other issue referenced above (#16367), I agree, we've been tracking some other Algolia related search issues in other places too like #12503. Any contributions to help improve things would be very appreciated!