Cover image for How to integrate Netlify CMS with Gridsome?

How to integrate Netlify CMS with Gridsome?

mittalyashu profile image Yashu Mittal Updated on ・4 min read

Gridsome is awesome 🀘🏻 and the possibility to integrate with other tools are endless...

Let's get down the road and learn how to integrate Netlify CMS with Gridsome.

It's fine, if you don't want to follow along, you can start using this Gridsome Starter NetlifyCMS Kit, easy peasy. Right? 😲

Netlify CMS works with wide range of file format markdown, JSON, YAML, or TOML stored in git repository on GitHub, GitLab or BitBucket. A static admin folder containing two files, inside the /static directory of your repo runs Netlify CMS.

Inside the admin directory, all the 🌟 magic happens, where you'll create two files:

 β”œ index.html
 β”” config.yml

The first file, admin/index.html, is the πŸšͺ entry point for the Netlify CMS admin interface. This means that you can navigate to yoursite.com/admin/ to access it. On the code side, it's a basic HTML starter page that loads the Netlify CMS JavaScript file.

<!doctype html>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
  <!-- Include the script that builds the page and powers Netlify CMS -->
  <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>

The second file, admin/config.yml, is the core of the Netlify CMS, and a bit more complex. Add all the code snippets in this section, goes to your admin/config.yml file.


We'll use Netlify for hosting and πŸ™ˆ authentication, so backend configuration is fairly straightforward.

  name: github
  branch: master # Branch to update (optional; defaults to master)

Media and Public Folders

Netlify CMS allows you 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 static directory, you could use its path, possibly creating an uploads sub-folder, for example:

# This line should *not* be indented
media_folder: "images/uploads" # Media files will be stored in the repo under images/uploads

If you're creating a new folder for uploaded media, you'll need to know where your Gridsome expects static files. You can put your media folder in the same location where you put the admin folder.

Note that the media_folder file path is relative to the project root.

# These lines should *not* be indented
media_folder: "static/images/uploads" # Media files will be stored in the repo under static/images/uploads
public_folder: "/images/uploads" # The src attribute for uploaded media will begin with /images/uploads

The configuration above adds a new setting, public_folder. While media_folder specifies where uploaded files are saved in the repo, public_folder indicates where they are found in the published site. Image src attributes use this path, which is relative to the file where it's called. For this reason, the path usually start at the site root, using the opening /.

If public_folder is not set, Netlify CMS defaults to the same value as media_folder, adding an opening / if one is not included.


Collections πŸ’­ define the structure for the different content types on your static site.

Let's say your site has a blog, with the posts stored in blog directory, and files saved in a date-title format, like 2018-11-20-goosebumps.md. Each post begins with settings in yaml-formatted front matter, like so:

layout: blog
title: "Goosebumps"
date: 2018-11-20 23:42:14 -0700
thumbnail: "/images/ghost.jpg"

This is the body content, where I write anything as long as I want, but it has to be in the markdown format, that's the only condition. πŸ˜‰

Given this example, our collections settings would look like this in your Netlify CMS config.yml file:

  - name: "blog" # Used in routes, e.g., /admin/collections/blog
    label: "Blog" # Used in the UI
    folder: "blog" # The path to the folder where the documents are stored
    create: true # Allow users to create new documents in this collection
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}" # Filename template, e.g., YYYY-MM-DD-title.md
    fields: # The fields for each document, usually in front matter
      - {label: "Layout", name: "layout", widget: "hidden", default: "blog"}
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Publish Date", name: "date", widget: "datetime"}
      - {label: "Featured Image", name: "thumbnail", widget: "image"}
      - {label: "Body", name: "body", widget: "markdown"}

There are lot more things offered by Netlify CMS like Filters, Authentication, Git-Gateway and lot more 🀯.

This is sneak peek of how integration works with Gridsome and Netlify CMS, to learn more in depth, consider read the Netlify CMS docs.

I have build a simple starter kit for you Gridsome Starter NetlifyCMS, it's easy to get started with πŸ‘‡πŸ».

Gridsome Starter NetlifyCMS Screenshot


Found this article interesting? Consider buying a coffee for me.
Buy Me A Coffee Button

Posted on Nov 21 '18 by:

mittalyashu profile

Yashu Mittal


I <3 to be a developer and designer.


markdown guide

Awesome guide, although when you try to deploy it to netlify using your git repository, netlify returns a

"failed during stage 'building site': Build script returned non-zero exit code: 1".
Any help?


Have tested it locally on your machine?


Thank you for the article! I'm new to static site generators and the Jamstack, so these articles are very helpful as I do my research. My goal is to find an alternative to traditional CMS's using static site generators and headless CMS's.

Is it possible to run this in the cloud and automatically build and deploy when content changes in Netlify CMS? So far in my research I have only seen examples of running Gridsome locally and manually running the build process. If I could run it in the cloud and automatically build on content changes that would be closer to what I'm looking for. Thanks!


Really appreciate those kind words.

I am also very obsessed with static site generator that I literally started a podcast for it, it's called Static Site

There are many static site generator out there and as I am aware of NetlifyCMS does work with bunch of them.

Yeah, sure you can deploy your site anywhere you want, checkout the screenshot below.

How gridsome works

As you can see Gridsome just output static files like: HTML, CSS, JS and then you can host those static files anywhere you want.

With Netlify you get few additional feature where you don't have to deploy manually, if you want to host your site on cloud you have add pass it thought some CI for auto-deployment.

Hope, this clears your question. :)



I have a fork of the starter kit, and was able to get it running at: upbeat-torvalds-ac1965.netlify.com

However going to upbeat-torvalds-ac1965.netlify.com... hoping to see the NetlifyCMS login I only get a "GitHub Auth Demo" page

Any advice on how to move on?


I solved it. Had to replace the content of static/admin/index.html with this (from netlifycms.org/docs/add-to-your-si...

<!doctype html>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
  <!-- Include the script that builds the page and powers Netlify CMS -->
  <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>

That's great. Glad, it worked out. πŸ˜ƒ


Could you share the screenshot of the problem you are facing?


Hi. Nice work. But how can I access the netlifyCMS backend? Normally its available via /admin - but this doesnt work for me. Can you provide more details?


Glad you liked it.

You can access the netlify cms backend by http://localhost:8080/admin, make sure that the admin directory is at the root and inside static directory.

Let me know if you found any other difficulty, while setting up NetlifyCMS integration with Gridsome.


It seems that your starter pack's config.yml doesn't include the required site_id field.

Which site_id you are referring about?


Did you change repo on config.yml to point to your own repo?


Yeah, didn't help though. But nevermind, moved on. Thanks!