March 27, 2021

Learn How to build a blog with Gatsby and Netlify CMS

In this tutorial , we will be going through JAMstack (Javascript APIs Markup) and build a blog site using Gatsby , which is a frontend framework built on top of react that allows building of fast , scallable apps with over 2000+ plugins .

Final blog that we will build can be found here https://gatsby-netlifycmsblog.netlify.app/

We will also be using Netflify CMS to host our blog content . Netlify CMS is a free , open source Headless CMS created by our friends from Netlify . Will learn more about Headless CMS later in this tutorial .

In JAMstack, your site pages are generated ahead of time and deployed as static html which can be hosted via CDN or any hosting service. This gives JAMstack sites a performance boast because we won’t wait for dynamic html generation from the server or server side code to finish executing .

Let’s start , make sure you have node and git installed . If yes , let’s start by installing Gatsby CLI tool globally , which will allow us to quickly bootstrap our gastby site .

npm install -g gatsby-cli

let’s bootstrap our gatsby app .

gatsby new gatsby-netlify-cms https://github.com/gatsbyjs/gatsby-starter-blog

In the above command , we created a new gatsby app called gatsby-netlify-cms and use a start template for a personal blog by specifiying GitHub URL that points to a code repository that holds the starter code for our template .

Go to our newly created proect file cd gatsby-netlify-cms

Then let’s run our project . Inside our proect file run below command :

gatsby develop

Now , if you open your web app normally at localhost:8000 , you should see a screen as below : -

Gatsby Started Blog Template

Now let’s add our Netflify Headless CMS . Headless CMS allows authoring of content but does not provide the frontend to display your content in which content is retrieved via APIs where one or more applications can utilize the APIs and display the content .

Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub, GitLab, or Bitbucket API.

In Netflify CMS , content is stored as images and Markdown files in a Git repository. Netflify CMS supports different backends for storing data including Github , Gitlab and Bitbucket .

Netlify also offers it’s own backend called Git Gateway which connects your site to Git provider’s API via the Netlify Identity service thus allowing working with content, branches, and pull requests on users behalf.

Now it’s time to add Netflify CMS to our Gatsby blog .

Configuration

Let’s start by installing the Gatsby plugin for Netlify CMS:

npm install --save netlify-cms-app gatsby-plugin-netlify-cms

Let’s go to our Gatsby plugins configuration file called gatsby-config.js in the site root and register our newly installed Netlify CMS plugin:

...
plugins: [`gatsby-plugin-netlify-cms`],
...

Finally ,let’s create admin folder inside our static folder of our project .

The admin folder will contains all Netlify CMS files and it will allow to access our admin backend via yoursite.com/admin route .

For starter , inside newly created admin folder , two files are required , index.html file which will be the root of our admin and config.yml file which will contain all Netlify CMS configurations .

admin
 ├ index.html
 └ config.yml

For our index.html page , gatsby-plugin-netlify-cms will automatically generate that file with a default Netlify CMS implementation.

if yo are using GitHub and GitLab repositories, you can start your Netlify CMS config.yml file with below settings . For bitbucket , read here .

backend:
   name: git-gateway
   branch: master

The above config specifies the backend protocol and publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. If you leave out the branch declaration, it will defaults to master.

Another interesting config option is called Editorial Workflow, which adds an interface for drafting, reviewing, and approving posts. By default, saving a post in the CMS interface pushes a commit directly to the publication branch specified in backend . You can allow Editorial Workflow by using below :-

publish_mode: editorial_workflow

Netlify CMS allows users to upload images directly within the editor. For this to work, the CMS needs to know where to save them. If you already have an images folder in your project, you could use its path, possibly creating an uploads sub-folder

media_folder: "images/uploads"

Last config we will add is The public_folder option which is the URL, relative to the Gatsby site’s root, that the images will be served from. When running the site locally.

public_folder: "/images/uploads"

Adding Collections

Now once this is done , we need to add a collection . Coming from a wordpress background , i would like to think of a collection similar to your post type, where you can have a Page , Post or Custom Post type where each post type has defined set of fields .

Collections define the structure for the different content types on your static site. Since every site is different, the collections settings differ greatly from one site to the next.

So , in our case since we are creating a blog and our starter-blog template already gave us a format , let’s review it .

Inside our project root , go to content folder then blog then hello-world folder and open index.md file . At the top of index.md file , we can see that we have a a yaml-formatted front matter as below : -

---
title: Hello World
date: "2015-05-01T22:12:03.284Z"
description: "Hello World"
---

Given this format above, we should be able to add a collection in our collections settings . Inside config.yml file add below :-

collections:
  - name: "blog" # Used in routes, e.g., /admin/collections/blog
    label: "Blog" # Used in the UI
    folder: "content/blog" # The path to the folder where the documents are stored
    create: true # Allow users to create new documents in this collection
    slug: "{{slug}}" # Filename template, e.g.,title.md
    fields: # The fields for each document, usually in front matter
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Publish Date", name: "date", widget: "datetime"}
      - {label: "Description", name: "description", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}

Fields listed above are shown as fields in the content editor . The widget property specifies a built-in or custom UI widget for a given field. When a content editor enters a value into a widget, that value is saved in the document front matter as the value for the name specified for that field.

At this point , were almost there . What is left is connecting our Gatsby site to Netflify CMS . To do that we need to enable Authentication .

We will be using Netlify to achieve that because has less husstle in setting things up , but if you want to play with other authentication options you can read more in Backends doc.

Netlify offers a built-in authentication service called Identity. In order to use Identity , we need to connect our repo with Netlify.

Adding project to Github

We will be using Github as our backend. Go to Github and create a new repository . Since you’re importing your existing project, you’ll want a completely empty one, so don’t initialize it with README or .gitignore files.

Now tell git where your remote repo is located

git remote add origin [GITHUB_REPOSITORY_URL]

When you created a new Gatsby project with a starter, it automatically made an initial git commit, or a set of changes. Now, you can push your changes to the new remote location:

git push -u origin master

Deploy on Netlify

To do that , go to app.netflify.com and login or signup. Once loggedin , go to sites tab and click New site from git button on the right as below

Netlify CMS add a new site from Git screen

Then , Clicking the button brings thd screen below where you connect Netlify to your Git repository. In our case , we will select Github : -

Netlify CMS connect to git provider

From there , you will presented with the screen to authorize and allow Netlify and GitHub to talk to each other. Then you will need to choose a repository you want to connect to .

Netlify CMS choose git provider screen

The last step is site settings. For this tutorial, the defaults are what you need, so click Deploy site.

Netlify CMS site settings screen

Once the site is deployed , we can do one more thing . Let’s change the site name to something easier to remember. We will do that by going to Site settings then click the General Tab and under site details -> Site Information click change site name .

Enable Identity and Git Gateway

It’s time to set Netlify’s Identity and Git Gateway services . These services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:

  1. Go to Site Settings > Identity, and select Enable Identity service.

Netlify CMS site settings Enable Identity Screen

  1. Under Registration preferences, select Open or Invite only. In most cases, you want only invited users to access your CMS, but if you’re just experimenting, you can leave it open for convenience. Netlify CMS site settings Enable Identity Screen
  2. If you’d like to allow one-click login with services like Google and GitHub, check the boxes next to the services you’d like to use, under External providers. In my case , i will allow login from google too by clicking enable provider then choose google .

    Netlify CMS site settings Enable Google  Screen

  3. Scroll down to Services > Git Gateway, and click Enable Git Gateway. This authenticates with your Git host and generates an API access token. In this case, we’re leaving the Roles field blank, which means any logged in user may access the CMS.

    Netlify CMS site settings Enable Git Gateway Screen

Add the Netlify Identity Widget

With the backend set to handle authentication, now you need a frontend interface to connect to it. The open source Netlify Identity Widget is a drop-in widget made for just this purpose.

To include the widget in your site, we will use a plugin called gatsby-plugin-netlify-identity-widget . Go on and install it .

npm install --save gatsby-plugin-netlify-identity-widget

then add below in gatsby-config.js under plugins:-

plugins: [
	'gatsby-plugin-netlify-identity-widget',
]

Your site CMS is now fully configured and ready for login!

If you set your registration preference to “Invite only,” invite yourself (and anyone else you choose) as a site user.

To do this, select the Identity tab from your site dashboard, and then select the Invite users button. Invited users receive an email invitation with a confirmation link. Clicking the link will take you to your site with a login prompt.

If you left your site registration open, or for return visits after confirming an email invitation, access your site’s CMS at yoursite.com/admin/. You should see a login screen as below

Let’s blog

Go ahead , commit and push your changes so as the automatic build could happen .

Once all the changes have Now , go to your new blog admin url , in my case , https://gatsby-netlifycmsblog.netlify.app/admin/#/ .

Netlify Blog Login Screen

Go ahead , and click login with netlify identity . You should see a screen as below :-

Netlify Blog Login Screen

Go ahead and proceed , in my case i use gmail as an option . Once you are succesfully logged in , you should see a dashboard as below :-

Netlify Blog Admin Home Screen

Go ahead, and create a new blog post . Once done , click save . Change status to ready and then click piblish dropdown on top right then click Publish now.

Netlify Blog Create Blog Screen

Now one last thing to do is deleting sample posts , go to content folder then blog and delete one after another , commit then push your changes. Now sample articles should be gone and you can start managing your content with Netlify CMS .

That’s it folks ! Time to get to work , expand on where we left off , add featured images in our blog collection and more . see you in the next post, keep coding :-)


Robert Rutenge
Front-end Developer | ReactJS enthusiast | Problem Solver . Find me on twitter and Github