Yashu Mittal

Posted on Nov 21, 2018 • Updated on Dec 8, 2018

How to integrate Netlify CMS with Gridsome?

#netlifycms #gridsome #vue #ssr

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:

admin
 ├ 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>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
</head>
<body>
  <!-- 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>
</body>
</html>

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.

Backend

We'll use Netlify for hosting and 🙈 authentication, so backend configuration is fairly straightforward.

backend:
  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

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:

collections:
  - 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 👇🏻.

Reference

Found this article interesting? Consider buying a coffee for me.

Top comments (14)

spicysanta • Feb 21 '19

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?

Yashu Mittal • Feb 22 '19

Have tested it locally on your machine?

Trond Ulseth • May 16 '19

Hi,

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?

Trond Ulseth • May 16 '19

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>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
</head>
<body>
  <!-- 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>
</body>
</html>

Yashu Mittal • May 16 '19

That's great. Glad, it worked out. 😃

Yashu Mittal • May 16 '19

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

Andrew Gray • Mar 8 '19 • Edited

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!

Yashu Mittal • Mar 13 '19

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.

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. :)

Sebastian Ulbel • Dec 6 '18

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?
Thanks.

Yashu Mittal • Dec 7 '18 • Edited

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.