Docs: Recipe for Contentful data source

[kevee]

Fixes #14949

This is a recipe page that outlines how to setup Contentful, install the gatsby-source-contentful plugin, set it up, query data, and create a simple listing page.

[wardpeet]

@kevee thanks a lot! I believe you'll need to add this section inside https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/recipes.md and not create a separate URL for it.

[kevee]

Thanks, I moved it under the sourcing data section.

[marcysutton]

Thanks for this! I've got a build error locally, so I can't pull it up to inspect closer...but I wanted to get some feedback to you sooner than later anyway.

One thing I'm thinking of this one (since it's a bit longer) is that #16980 will help to make the page more digestible. We haven't landed on a solution yet, but I wanted to mention it here since it came to mind.

[muescha]

Some remarks

[muescha]

i miss a short README.md in the example repo with a link to the recipes section

[kevee]

Good idea @muescha, added readme.

[marcysutton]

This is super close - I left a suggestion to make the template more semantic. Otherwise I think it's ready to go! We can always make improvements later on if needed.

[wardpeet]

Thanks, @kevee I went through the recipe to get a contentful space up and running. I've added 2 questions to maybe improve it a bit.

[wardpeet]

is this a space under gatsby control? If so 👍 else we should put in our own.

[kevee]

It's not right now, but it should be!

[kevee]

Another option would be to export the example space and let users seed their own Contentful space, similar to the example Contentful Javascript app.

Actually, I think that's the best way to go...

[kevee]

So, @wardpeet & @marcysutton, here's three options:

1. Create an example space owned by Gatsby
2. Export the example space used for the recipe and include instructions in the recipe README on using the Contentful CLI to import it into your own space
3. Rewrite the example repo and recipe to use the example Contentful blog content model, and include instructions in the recipe README on how to use the contentful space seed command to create a sample space.

I like option 3 because it means less example content owned by Gatsby.

[kevee]

The steps for seeding a new space would be:

Setting up your Contentful space

1. Install the Contentful CLI
2. Login to Contentful with the CLI, it will help you create an account if you don't have one

contentful login

3. Create a new space, this command will return a new space ID.

contentful space create --name 'Gatsby example'

4. Seed the new space with example blog content using the new space ID.

contentful space seed -s '[space ID]' -t blog

5. Create a new access token for your space.

contentful space accesstoken create -s '[space ID]' --name 'Example token'

6. Edit the file gatsby-config.js and add your space ID and access token to the following section:

plugins: [
    {
      resolve: `gatsby-source-contentful`,
      options: {
        spaceId: `[space ID]`,
        accessToken: `[access token]`,
      },
    },
  ],

7. Run Gatsby.

gatsby develop

[kevee]

K, if we go with #3 (which I already started, but am fine with rolling back on) then another thing to consider is whether we should align the written recipe page with the example repo. It would add more steps, but I like the idea of them being the same.

[marcysutton]

That #3 option sounds amazing -- it would reduce some of the friction in getting set up. I didn't even know it existed!

[kevee]

Me neither!

OK so that means we can keep the recipe example repo as it is and I'll do the following tomorrow:

1. Alter the prerequisites to just be:

• A Contentful account
• The Contentful CLI installed on your local computer

2. Add under directions all the steps that are in the example README - another option would be to link to it... thoughts?

3. Change the GraphQL query and screenshot to be in line with the recipe.

[muescha]

I would not link to instructions. Just include it. It would be nice to see all instructions customized to the example.

Then the user can go step by step on one tutorial page and not need to analyze other pages which command he have to change to the needs to complete the tutorial

[kevee]

OK so I moved the instructions to the recipe, removed them from the README of the example, and linked the README over to the recipe.

Question: should the directions be split into two headings, since it's now a little long? It would be inconsistent with the recipe template, but I think either two separate headings under the Directions heading, or have "Set up Contentful" as a separate heading between Prerequisites and Directions. It would make it a bit easier to deep-link, and separate a generic Contentful setup task from a Gatsby-specific ones like installing plugins, etc.

[marcysutton]

This is great! It's way easier to do with the Contentful CLI. I went through the example and left a few suggestions, hopefully this should wrap everything up. Thanks again for working on it!

[muescha]

Add syntax highlighter

[muescha]

i done a walk through and noted all my comments. maybe they are helpful to enhance the receipt for less unknown situations for the user.

[gillkyle]

Hey @kevee, thanks a ton for working on this (and all the other PR's you've put up in the past) 🙂

It looks like this PR is really close, if we can get the last suggestions applied I feel like it's good to merge. If you can make those changes it'd be awesome, if you don't think you've got the time to take it on yourself could you enable changes to your fork from maintainers so I could hop in and try and push it to the finish line?

Appreciate all your help and patience on this!

[kevee]

Reviews applied, sorry I dropped this one for a bit.

[gillkyle]

Thanks so much @kevee, this is awesome! Really appreciate you helping out and being patient with so many suggestions, I say we get this merged!