Skip to content

How to Set Up Gatsby with Netlify CMS

Gatsby/ (Posted on )

Netlify CMS is a dashboard made in React that lets you manage content of your website. It is free, open source and works with many static site generators, including Gatsby. It enables its users to add and edit blog posts with a simple user interface instead of Markdown files.

Setting up Netlify CMS for the first time can be a bit confusing. It can be hard to understand how all the parts work together. But don’t worry, in this post, you will go through the process step by step and learn about every detail involved.

In the end, you will have a Gatsby blog deployed on Netlify. You will have set up Netlify CMS that is accessible only to you with GitHub authentication.

You will use Gatsby Starter Blog to learn the principles, but any Gatsby site can be set up to work with Netlify CMS.

Prerequisites

Before you follow along, make sure you have done these steps first.

Step 1 — Installing Gatsby and Netlify CMS

Open your terminal application and navigate to a folder where you will keep your project. Run the following command which installs Gatsby from Gatsby Starter Blog starter.

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

You can substitute my-gatsby-blog with your own name. It is the path of the folder where the command will install your project.

Go into your project’s folder inside of terminal and install Netlify CMS package and its corresponding Gatsby plugin.

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

Add the installed plugin to gatsby-config.js in the root of your project.

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-netlify-cms'
    }
  ]
}

Step 2 — Adding Configuration

Before you start, you need to understand how Netlify CMS works. It relies on Git Gateway, which is a part of Netlify CMS that connects the dashboard to your project’s repository. Users of your dashboard can then add or delete posts from your repository without having full access to it.

No matter in which environment you use Netlify CMS, locally, staging or production, it will always push changes to your specified branch in the remote repository. Usually it is main or master. And it will always fetch posts from this branch. You will have to log in to use the dashboard and for that you can use Identity service provided by Netlify.

Create a folder called admin inside the static folder. Then make a file called config.yml inside the admin folder.

# static/admin/config.yml

backend:
  name: git-gateway
  branch: main # Change to your production branch

local_backend: true # Enables Netlify CMS locally

publish_mode: editorial_workflow # Adds more options to content management

media_folder: static/img
public_folder: /img

collections:
  - name: 'blog'
    label: 'Blog'
    folder: 'content/blog'
    create: true
    slug: 'index'
    media_folder: ''
    public_folder: ''
    path: '{{title}}/index'
    editor:
      preview: true # Displays a preview of your post while editing it
      fields: # Fields get placed in resulting Markdown file
        - { 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' }

The fields are inputs of a form for the blog post template. Filling this form is how you write the blog post, instead of directly working with Markdown files. Netlify CMS will generate the appropriate Markdown file for you.

In this case, it will look something like this.

---
title: Your Blog Post Title
date: 2021-02-26T10:21:05.209Z
description: Your Blog Post Description
---
Content of your blog post will go here.

Adding publish_mode: editorial_workflow grants you more control over the posts, like setting their status to ready or draft. Instead of adding a new post to your main branch, Netlify CMS will push it to a separate branch first and create a pull request. This way, you can hide a post instead of deleting it, by setting it to draft. When the post is ready, and you publish it, Netlify CMS merges the pull request into your main branch.

Run gatsby develop, open your site in a browser and navigate to /admin. You should see a login button, Login with Netlify Identity, appear. This is where you need to configure and deploy your site on Netlify. But before you do that, you can use a beta feature that allows you to test your configuration locally.

Using Netlify CMS Locally

You can add local_backend: true to your config to use Netlify CMS on your machine. Such setting allows you to run a local proxy server that skips authentication.

Open another instance of your terminal and run the following command from the root folder of your project while gatsby develop is still running.

npx netlify-cms-proxy-server

Open /admin in your browser again. This time you should immediately be taken to the dashboard.

Working locally will not automatically push your new posts to your repository and you will have to do it by hand. This is not the recommended workflow, but it works great while doing development.

Customizing Your Configuration

You can add validation to your title and description fields.

fields:
  - {
      label: 'Title',
      name: 'title',
      widget: 'string',
      pattern: ['^.{4,80}$', 'Title must be 4 - 80 characters long'],
    }
  - {
      label: 'Description',
      name: 'description',
      widget: 'string',
      pattern: ['^.{40,200}$', 'Description must be 40 - 200 characters long'],
    }

You can also change the format of the datetime picker.

fields:
  - {
      label: 'Publish Date',
      name: 'date',
      widget: 'datetime',
      date_format: 'YYYY-MM-DD',
      time_format: 'HH:mm',
    }

Datetime picker uses your local time, but it adds time to your blog post in UTC. You can change that the picker uses UTC by adding picker_utc: true to the configuration above.

To create a category select, you can use the select widget. You have to fill input fields by default, but you can change that with required setting.

fields:
  - {
      label: 'Category',
      name: 'category',
      widget: 'select',
      options: ['Gatsby', 'JavaScript', 'React'],
      required: false,
    }

There are a bunch of other widgets with many configuration options that you can explore in Netlify CMS documentation.

On a different note, you can change the /admin URL to something else if you want to “hide” the admin dashboard. It will still be accessible but harder to guess, depending on the name you choose.

Rename the static/admin folder, for example, to static/your-custom-path and adjust gatsby-config.js. Specify the name of your folder in publicPath property.

{
  resolve: 'gatsby-plugin-netlify-cms',
  options: {
    publicPath: 'your-custom-path'
  }
}

Now you can access your dashboard by navigating to /your-custom-path.

Step 3 — Configuring Git Gateway

Although you can work locally and push every new blog post by hand, Netlify CMS is best used on the live version of your website. That requires configuring Git Gateway, but it is well worth it.

Before you configure Git Gateway on Netlify, you need to deploy your site first. Here’s a guide from Netlify about deploying your website.

In summary, you need to push your project to your GitHub repository. After that, you create a new site on Netlify and connect it to your GitHub repository. After successfully granting Netlify permission to use your repository, your site will be deployed. Pushing new changes to your chosen production branch will automatically rebuild your site and deploy the changes.

To configure Git Gateway, visit Identity section in the top navigation and press Enable Identity.

After enabling Identity, click Settings and usage in the screen that appears or press Site Settings in the top navigation.

Find Identity section in the menu on the left, open it and click Services. Now, click Enable Git Gateway button.

That’s all you have to do to allow sign-up and login with email and password.

Now you should secure that only your selected users can sign up and access your dashboard.

Step 4 — Creating Account for Netlify CMS

Start by disabling registration in Site Settings > Identity > Registration. Under Registration preferences, click Edit Settings and select Invite only.

Next, enable GitHub login under External providers by clicking Add provider, which is located below the Registration section. Stick with the default configuration. You will be able to log in with your GitHub account instead of creating a new account using email and password.

Go to the Identity section in the top navigation and click Invite users. Invite yourself by entering your own email. This email must match the email you use on GitHub, otherwise you won’t be able to login.

Visit your email and follow the sign-up link. You should be able to log in with your GitHub account and access the live admin dashboard of your Netlify CMS.

Summary

You learned how to install and configure Netlify CMS for your Gatsby blog. Furthermore, you set up Git Gateway to enable Netlify CMS to work with your project’s repository. After that, you set up Identity service to be able to log into your dashboard. And finally, you limited the registration to invite only and allowed login with GitHub.

References