The Best Headless CMS for Gatsby

When I had the idea of starting a blog, I thought of using gatsby. I started by creating a simple portfolio website. Designed a UI using Figma and developed the application using Gatsby. Back then I created a wordpress site to write blogs. But soon I felt a need to create my own custom blog site.

The Search for a CMS

My first attempt was to add markdown files to the github repository and fetch content from it using graphql. Writing in markdown files is really flexible and easy, but was really hard to manage. Since my first attempt was not satisfactory, I searched for other ways of managing posts. I went with the most popular CMS for gatsby called contentful.


Contentful is a headless CMS. It allows users to add posts and fetch the data using an api. It is free and easy to use. It has a really good user interface and gives its users maximum power to manage their content. It has a rich-text editor which makes it easy to write articles. I felt it was really cool!

I started by adding posts to it and fetching the data from contentful api using graphql. Using the data to create blog posts in gatsby. I went with this approach for some time.

Problems with Contenful

Since their last update, contentful has been really hard to set up. Contentful supports markdown in their text field with limited text size. Also, the json support for rich-text content has been removed since the update. Due to a lack of proper documentation, figuring out the way to fix issues was hard for me. Adding assets to articles requires additional configuration. One biggest missing feature that made me change from contentful was the missing code blocks in the rich-text editor. Most of my articles are technical and without a code block or markdown, it is hard for me to write things down.

Need for a New CMS

I needed a different approach which includes creating and managing markdown files. This would also allow me to integrate mathjax to write mathematical equations in my blogs. After a lot of research, I found Netlify CMS. yaay!!

Netlify CMS allows us to write markdown files along with a rich-text editor. Publishing an article would create a markdown file in the github repo and trigger a build in Netlify. It also has a feature called editorial workflow which allows us to save our files to continue later. The preview option adds to one of the best features of the CMS.

Integrating Netlify CMS

Adding Netlify CMS to your project can be tricky. Without a proper understanding of the workflow, it can get easily confused. But it will be easy if you follow the steps right.

  1. Start by cloning the gatsby starter blog.

    gatsby new blog
  2. Install the necessary dependencies

    npm install --save netlify-cms-app gatsby-plugin-netlify-cms
  3. Create a file at static/admin/ directory and add the configuration

     name: git-gateway
     branch: master
    media_folder: static/img
    public_folder: /img
     - name: 'blog'
       label: 'Blog'
       folder: 'content/blog'
       create: true
       slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
       preview_path: 'blog/{{slug}}'
         - { label: 'Title', name: 'title', widget: 'string' }
         - { label: 'Publish Date', name: 'date', widget: 'datetime' }
         - { label: 'Description', name: 'description', widget: 'string' }
         - { label: 'Tags', name: 'tags', widget: 'list'}
         - { label: 'Body', name: 'body', widget: 'markdown' }
  4. Add the plugin to gatsby-config.js

    plugins: [`gatsby-plugin-netlify-cms`]
  5. Push your code to a github repository and deploy it in netlify.
  6. Configuring the application on netlify to use netlify CMS.

    • Go to site Settings > Identity and Enable Identity service
    • In the Registration preferences check Invite Only option. Then navigate to Identity section in the navbar and add a new user.
    • Back in the settings, scroll down to Service Section and enable Git Gateway
  7. Start publishing articles

    • Head over to <deployed_site_domain>/admin and login with your credentials.
    • Create a new post by clicking New Blog. Add a title, date, description and tags (not necessary) and publish the article. This will add a new commit and create a markdown file to the github repository. It will also trigger a build on netlify and the changes will be published.

Profile picture

Written by Roshan R who lives in India, building useful things. You should follow them on Twitter