[Guide]: Adding Netlify CMS to Gatsby

[krismorf]

Summary
Adding Netlify CMS to Gatsby Guide decaporg/decap-website#6

[netlify]

Preview proposed changes to the CMS demo site in the link below:

Built with commit 669a55f

https://deploy-preview-2117--cms-demo.netlify.com

[erquhart]

@krismorf here's an issue from someone that walked through the guide: #2120

[krismorf]

@erquhart it was solved in a7ea13d

[erquhart]

Awesome!

[erquhart]

@verythorough have time to give this a review?

[netlify]

Preview proposed changes to netlifycms.org in the link below:

Built with commit 669a55f

https://deploy-preview-2117--netlify-cms-www.netlify.com

[verythorough]

The writing for this is fantastic! Thank you, @krismorf!

I made a few minor comments on the content, plus one logistical change required in the line 1 comment.

Awesome work!

[verythorough]

Thanks for the changes! I caught one more tiny one I missed the first time.

Also waiting to hear if @tomrutgers or @erquhart have an opinion on menu placement.

Thanks for your patience!

[tomrutgers]

@verythorough @erquhart Right, menu placement! We currently have all the customization in the 'Guides' section (and a 'Contributor Guide' in the Contributing section to make it a bit more confusing), leaving little room for the actual guides.. Would it make sense to reorganize the navigation and have a structure like described below? I'm aware that this is out of the scope of this PR, but it might be worth including it in the original issue. decaporg/decap-website#6

Guides

• Gatsby
• Hugo
• Middleman
• ...

Customization

• Custom Widgets
• Custom Previews
• Custom Editor components

Contributing

• How to contribute
• Architecture

[verythorough]

@tomrutgers that menu org sounds perfect. Also agree that it's out of scope here!

For this PR, @krismorf, if you can add the front matter I described, I think we can merge this one.

Then, maybe you'd like to make the PR for the menu re-grouping? I'm happy to go over what that would entail, if you're interested.

[krismorf]

@verythorough the guide has been adjusted 🚀 I will open a new PR for the menu org.

[verythorough]

Woot! Now with the front matter, we can see it in preview:
https://deploy-preview-2117--netlify-cms-www.netlify.com/docs/using-netlify-cms-with-gatsby/

LGTM 🎉

[verythorough]

Added an issue for the menu re-ordering: #2149

[tomrutgers]

I don't know Gatsby all that much, but this looks really easy to follow! I'll try it out tomorrow.

@verythorough It's been a while since I've seen a deploy preview posted by your account 😂

[Benaiah]

Just ran through the instructions in the guide - thanks so much for the contribution! It looks like the Gatsby template this uses has blog posts as subfolders, so the default Gatsby blog posts do not show up in the admin when following this template, and the newly created blog posts are not created as folder-style posts like the sample posts. (Posts created by the CMS are still picked up and displayed by Gatsby, however, so the CMS set up by this guide is still functional). This should either be fixed, or the guide should not imply that the sample blog posts will be visible in the CMS.

(There is also a 404-derived error visible in the console due to the image folder not existing in GitHub yet, but this doesn't actually affect the functionality of the CMS since the folder is created as soon as you add an image. This superfluous error should be addressed by another PR, but it doesn't block this one in any way.)

[tomrutgers]

Tried it out today, very easy to follow! Nice.
I agree with @Benaiah. I think we should point out that we do not follow the content/blog-post/index.md structure early on.

[krismorf]

@tomrutgers @Benaiah thanks for the feedback. I will mention that Netlify CMS does not follow the default folder structure.

The guide works because in gatsby-config.js he have this:

{
  resolve: `gatsby-source-filesystem`,
  options: {
    path: `${__dirname}/content/blog`,
    name: `blog`,
  },
}

and in config.yml we point to that directory:

collections:
    folder: "content/blog"

Should we mention this as well? @verythorough can you please help with the wording?

[talves]

Maybe just a quick section on how to start the development locally?

yarn start

Propose advanced section for later date

We should include a section in the future to show an example of adding the cms through modulePath and be able to add custom previews for the collections.

[erquhart]

@krismorf wording:

**Note:** each existing blog post in `gatsby-starter-blog` is stored in its own directory. Netlify CMS doesn't work with files that are stored this way ([feature request here] (https://github.com/netlify/netlify-cms/issues/1472)), so you won't be able to see or edit the starter's included sample blog posts in Netlify CMS, but you will be able to create and edit new posts.

Any further additions can happen after this is merged. Thanks so much for digging into this Kris!

_{Sent with GitHawk}

[tomrutgers]

🚀

[tomrutgers]

@Benaiah Can we get this merged?

Requested should still be made after merge, but the issue isn't worth blocking the PR

[talves]

@krismorf thanks for working on this and your patience. We hope things can move quicker on something so easy to review!

[erquhart]

I think @tomrutgers just realized he's a maintainer lol

_{Sent with GitHawk}