Docs/sourcing from json yaml

[jonniebigodes]

First draft of the document for sourcing from json and yaml. It documents the way to achieve this using API and fetching the data directly on the client, also provided is a working example.

Addresses #11130

Description

Related Issues

[xxczaki]

@jonniebigodes You should definitely fix prettier errors, besides of that LGTM 😄

[jonniebigodes]

Closing this pull request and removing the branch, as it seems there's no intention on merging this or anything else.....If someone more capable is will to pick it up, have fun

[m-allanson]

Hey @jonniebigodes I’m sorry we missed this and your other PR! If you want to reopen them I’d be happy to review both of them in the morning.

As you know we get a constant flow of PRs, and we try to give a timely review to all of them. Unfortunately we messed up here, I can only apologise for letting these two fall through the cracks.

Finally I’d like to say thank you for all your contributions to the community, I (and the rest of the OSS team) really appreciate it.

[jonniebigodes]

@m-allanson both branches and pull requests are re-opened. Feel free to provide feedback when ready. I'm going to see if i can restore the live versions back that were hosted in netlify. Or if not possible i'll update the examples readme accordingly. Sounds good?

[m-allanson]

@jonniebigodes that sounds great, thank you! I'm working on reviews for these now.

[m-allanson]

Thanks for opening this @jonniebigodes - I started working through it and realised we possibly need some more clarification on how best to resolve issue #11130. I've left a question for @KyleAMathews over on that issue, let's wait for an answer over there before making any further changes here.

[marcysutton]

Thanks so much for this PR! I left a bunch of comments, most of them are about the written tutorial content in its current form. It looks like there are also some files from another js-search example that could go away since this one is about JSON and YAML. Limiting the example to only the files needed to run it would be good.

To @KyleAMathews' point, there wasn't a static example already so it's great that you've added one; I think that should be included in the tutorial on its own (which focuses on single workflows, rather than presenting multiple options). See our comments here: #11130 (comment)

The appendix file would work great in the recipes section with all three examples (perhaps it gets moved into docs instead of tutorial). Here would be a good place to link to it: https://www.gatsbyjs.org/docs/recipes/#using-gatsby-without-graphql
That would mean adding an item to that section with something like "Learn how to pull data into your Gatsby site with JSON or YAML", unless you can find a way to work it into the page on "Learn how to pull unstructured data into Gatsby sites in Using Gatsby without GraphQL".

Definitely let us know if you have any questions! I'd be happy to help you move stuff around if you need assistance.

[marcysutton]

I'd start this sentence with "Change directories" instead of "Navigate" just so that if someone doesn't know how to do it, they'll have more of a hint.

[marcysutton]

Typo: Contentful (a t and one l)

[marcysutton]

Can you update this to a full sentence: [js-yaml](https://github.com/nodeca/js-yaml) will parse the yaml file contents

[marcysutton]

Can you add a little folder diagram below to help illustrate the desired structure? I'm thinking something like this, but maybe there's a better syntax?

/project
    /data
        /json
        /yaml
    /static

Edit: this would change a bit for a static example pulled out on its own.

[marcysutton]

Let's change this to a more active verbiage: "This section presents a way to create..."

[marcysutton]

Suggested change

	Bellow are listed the routes generated via GATSBY API
	Below are listed the routes generated via GATSBY API

Typo: "Below"

[marcysutton]

This package.json file should be updated with info specific to this example. Here's another one for comparison: https://github.com/gatsbyjs/gatsby/blob/master/examples/client-only-paths/package.json

[marcysutton]

Change this wrapper DIV to a header element (it's a change that I also plan to make upstream in the starter):

<header
    style={{
      background: `rebeccapurple`,
      marginBottom: `1.45rem`,
    }}
>

[marcysutton]

I think these .gitignores and .prettierrcs can all go away in the example, it would be more consistent with the other examples: https://github.com/gatsbyjs/gatsby/tree/master/examples

[marcysutton]

Should these search example files be here? Seems like those are from another example.

[jonniebigodes]

@marcysutton i've read through the changes. And as their to many of them i'm going to group them into bullet points so that the draft/pull request can evolve.

• The semantical and grammar happened because the document was written with one eye open and another half opened, so there were bound to be some mistakes there. And also the reviewer, let's call her the better half, was not in her A-Game, as the "bubonic plague" (pardon the bad pun) a.k.a a really bad cold, hit hard this time. With that, they are being addressed as we speak.
• The item regarding examples/using-js-search/README.md was introduced when i linted the files for this branch which entered in conflict with docs: Add stub articles for search guides #10772 . As i'm not a person to mettle with someone else's work, i left them as is.
• The example code is changing from the default starter, to the hello world one. To keep it simple.
• Folder structure is a nice touch to the document, forgot to add it.
• The .gitignores and .prettierrcs were committed, basically due to a "mechanical" action on my part.

[jonniebigodes]

@marcysutton while reading the comments in here and to avoid intruding in @jlengstorf out of the bat i believe that a compromise can be arranged so that the documentation can move forward.
I came up with two possible solutions:

• Possible solution 1
  As the ground work is already done in here, if it's ok from your end, the document in question and the example would be expanded to incorporate yaml, based on what i've demonstrated on the document/example.
  Leaving the client side of things on how to load json/yaml data to a example folder and adding another bullet in here and the contents itself would be the bottom half of the appendix file i've created, starting from Using JSON as a content provider a page section.

• Possible solution 2
  Based on what you've mentioned, And removing the update from @jlengstorf document and example out of the equation the recipes part of the docs-links.yaml would be transformed into a array with the following contents:

- title: Documentation
  items:
    - title: Introduction
      link: /docs/
    - title: Quick Start
      link: /docs/quick-start
    - title: Recipes
      link: /docs/recipes/
      items:
        - title: Gatsby without Graphql
          link: /docs/using-gatsby-without-graphql/
        - title: YAML as a source for building a site
          link: /docs/sourcing-from-yaml/
        - title: JSON as provider for a page
          link: /docs/client-source-from-json/
        - title: YAML as a provider for a page
          link: /docs/client-source-from-yaml
        

With this it the appendix file is split into smaller more focused pieces of documentation/information.
The reader can fetch the document/information more accurately.
And if necessary the bullet points in here are adjusted to reflect the changes.

Feel free to provide feedback. Either way is fine by me, As the bulk of it is already implemented is just a matter of fine tuning

[marcysutton]

Hi @jonniebigodes, thanks for all your thoughts and patience on this!
It looks like Jason's example is the same content as what's on the existing page, which is great. I think it's worth adding this new content in addition to that in the docs.

I like your Possible Solution #2, with a few tweaks. The existing page seems like the most logical starting point, since all of these new examples are about sourcing content and data without GraphQL. To keep that page from getting too long, I think we should add two new pages under the existing one in the sidenav, using an expand toggle to hide them by default, like on the headless CMS page (if possible).

• Add a table of contents at the top of the existing page with a list of the approaches in this "non graphql" section
• Add a page for Site Sourcing with YAML.
• Add a page for client-side data fetching with YAML and JSON, combining those two examples onto one page (if possible).

Here's an IA diagram of what I'm talking about:

- title: Documentation
  items:
    - title: Introduction
      link: /docs/
    - title: Quick Start
      link: /docs/quick-start
    - title: Recipes
      link: /docs/recipes/
      items:
        - title: Gatsby without Graphql
          link: /docs/using-gatsby-without-graphql/
            - title: YAML as a source for building a site
              link: /docs/sourcing-from-yaml/
            - title: Client-side sourcing with JSON or YAML
              link: /docs/client-source-without-graphql/  
         - title: Sourcing from the Filesystem
           link: /docs/sourcing-from-the-filesystem/

I picked "Client-side sourcing with JSON or YAML" and a slug of "client-source-without-graphql" to make it easier to know what that's about. I think those examples could also live on Github with Jason's example.

Let me know what you think, and @jlengstorf or @DSchau as well!

[jonniebigodes]

@marcysutton like i said in the previous comment, either way is perfect. Looks like one vote for the second solution, all is needed is @DSchau and @jlengstorf input and i'll adjust accordingly.

[jonniebigodes]

@marcysutton going by a old wife's adage on this side of the big pond, that roughly translated means "silence means consent". As soon as my other pull request is merged, i'll adjust this one based on the evolution of the second solution mentioned and we can then proceed from here. What do you say?

[marcysutton]

@jonniebigodes that sounds fine to me.

[jlengstorf]

Whatever @marcysutton says is good with me. :)

Thanks for this, @jonniebigodes!

[jlengstorf]

Hey, @jonniebigodes — one quick note: I know you didn’t mean anything by it, but this phrasing is something we’d prefer to avoid:

going by a old wife’s adage on this side of the big pond, that roughly translated means “silence means consent”.

Communicating intention in written text is extremely hard, so we tend to err on the side of overcautious about jokes around consent. We want to make sure everyone feels welcome in the Gatsby community, so we just steer clear of it altogether. (We talk about this a bit in our Code of Conduct, too.)

Thanks again for being part of our community, and thanks in advance for keeping our community as friendly and welcoming as possible!

[wardpeet]

@jonniebigodes mind cleaning up this PR? I'm sure everyone is pretty stoked about getting this in our docs!

[jonniebigodes]

@wardpeet by the time you see this, this pull request is closed and the branch deleted. I'm cleaning up the docs and the example that goes along with it as per @marcysutton's input and also with that proceed from a "clean slate" as to avoid the file conflicts that were generated at the time, as you can see above. This piece of documentation discussed here is going to be on fresh pull request pretty soon.