DEV Community

Cover image for How to integrate Netlify CMS with Gridsome?
Yashu Mittal
Yashu Mittal

Posted on • Updated on

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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. 😉
Enter fullscreen mode Exit fullscreen mode

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"}
Enter fullscreen mode Exit fullscreen mode

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

Reference

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

Top comments (14)

Collapse
 
spicysanta profile image
spicysanta •

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?

Collapse
 
mittalyashu profile image
Yashu Mittal •

Have tested it locally on your machine?

Collapse
 
trondulseth profile image
Trond Ulseth •

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?

Collapse
 
trondulseth profile image
Trond Ulseth •

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>
Collapse
 
mittalyashu profile image
Yashu Mittal •

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

Collapse
 
mittalyashu profile image
Yashu Mittal •

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

Collapse
 
grayanchor profile image
Andrew Gray • • 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!

Collapse
 
mittalyashu profile image
Yashu Mittal •

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

Collapse
 
suitsat profile image
Sebastian Ulbel •

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.

Collapse
 
mittalyashu profile image
Yashu Mittal • • 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.

Collapse
 
berkmann18 profile image
Maximilian Berkmann •

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

Thread Thread
 
mittalyashu profile image
Yashu Mittal •

Which site_id you are referring about?

Collapse
 
hack_nug profile image
Nestor Vera •

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

Collapse
 
suitsat profile image
Sebastian Ulbel •

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

View full discussion (14 comments)

Read next

mikeyoung44 profile image

Neural Collapse Persists Despite Low-Rank Bias: Exploring Unconstrained Feature Dynamics

Mike Young -

bleuiot profile image

Interfacing BleuIO with Node.js Using Serial Communication

Bleuio tech -

madina1575 profile image

NESTED WHILE LOOP

madina1575 -

jamesbmour profile image

Streamlit Part 6: Mastering Layouts

James -