A beginners guide to setting up Netlify CMS

Illustration by Katerina Limpitsouni undraw.co/illustrations

Recently I started migrating an older Drupal based blog to a combination of Gatsby and Netlify CMS (source), both of which I had no prior experience with. In this blog series I'll talk you through the experiences, hurdles and solutions. In part 2 I'll give some pointers how to set up Netlify CMS to your needs.

How it works

Netlify CMS is a headless Content Management System. Think Wordpress, but only the admin portal. Another key difference is that it does not use any database.

Wait... what?! Yes, you read it right. Netlify CMS is part of the Git-based headless CMS group. It works by committing markdown files to your repo. Alternatively you could also store your content as JSON, yml or toml.

Using Git as your content database comes with some downsides and you might think that content editing is reserved to persons with access to the Git repo, but fortunately, Netlify CMS provides a good way to manage your content for non-devs which I will discuss in the next section.

An impression of the admin interface of Netlify CMS

To create some content you can login to the admin interface (defaults to /admin) and start editing in the User Interface. When you click on Publish, Netlify CMS will create a commit on the master branch of your repo, adding or modifying the Markdown file.

The commit on master is picked up by Netlify (the platform, not the CMS) which is registered as a Github App. Netlify schedules a new production build and as soon as that is finished, your app will be updated with new content!

❗ This means that before you start working on your site, you have to remember to pull the latest data from master.

If you are confused what the difference between Netlify and Netlify CMS is, I recommend reading this link.

Authentication

The first thing I wanted to know when considering Netlify CMS was the authentication part. For my use case the content editors should not have to create a Github account.

Fortunately, with Identity you can invite editors to the admin interface. They can sign up using an email/password combination or by linking an external OAuth provider (currently Google, Github, Bitbucket and GitLab).

Customizing fields

If you first open up the admin interface you'll be met with some basic options for creating and editing different content types. You can manage for individual pages (such as the home page or the about page) and for sets of pages such as blogs.

You'll find that individual pages will have different fields in the CMS. A home page might have a field with highlighted blogs. That field will be missing on the about page. In other words, the fields of these pages are not uniform.

Blogs on the other hand have the same set of fields, although some may be optional. This distinction is the difference between Collection types. Individual pages belong to the file content type, whereas sets of similar content belong to the folder content type.

You can have multiple of either collection types. You could have a file for the home page and another for the contact page. On the other hand you can have seperate folder content types for blogs and authors.

The configuration for these content types can be found in the static/admin/config.yml file. In basic form the content types would look like this:

# other CMS configuration

collections:
  - name: "blog"
    label: "Blog"
    folder: "src/pages/blog"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}
  - name: "author"
    label: "Authors"
    folder: "src/authors"
    fields:
      - {label: "Name", name: "name", widget: string}
      - {label: "Profile picture", name: "profile_picture", widget: image, allow_multiple: false}
  - name: "pages"
    label: "Pages"
    files:
      - file: "src/pages/index.md"
        label: "Home"
        name: "index"
        fields:
          - {label: "Home title", name: title, widget: string}
      - file: "src/pages/contact/index.md"
        label: "Contact"
        name: "contact"
        fields:
          - {label: "Contact title", name: "title", widget: "string"}

Adding new fields is rather easy. You just add a new line with the proper configuration, commit and push the changes and it will show up in the admin panel.

There are many field types to choose from. In Netlify CMS field types are defined by the widget property. You got various options including textareas, file uploads and select fields. All available widgets can be viewed here. If the widget you would like is not present, there's even the possibility to create a custom widget.

You can now set up your CMS as you see fit. Don't worry if you need or want to iterate on it. You can add fields later on as well. If you decide to rename them, you'll have to edit the markdown files to update the fields there as well.

When inspecting the Markdown file you might encounter some syntax that you have not seen before. It looks like the Markdown is enhanced with some metadata:

---
title: "An awesome blog"
---
**The body of the blog post**

Typing `Markdown` as you *know it*

This metadata format is known as frontmatter. Essentially, it is yaml syntax. All fields are saved as frontmatter data, except the body field if the body field uses the markdown widget.

Previewing your content in the admin interface

Even though you added some new fields to your content types and you filled them in, they will not show up immediately in the preview pane. To get that working you must register a previewTemplate. If you use any of the Netlify CMS starters the template is already created for you. All you need to do is retrieve the new data and update your rendered component(s) with this new data.

A local CMS

One last tip: if you are developing locally you might want to test with some mocked data (looking at you Foo Blog 🙄) or you might be working on the preview templates mentioned in the previous section.

Either way, it is possible to run a local version of the CMS using a beta feature that sets up a proxy. This will make sure that any content you create is not pushed to the repo.

My final configuration

You can find the CMS configuration I ended up with in my Github repo.

You might notice that I created a relationship between the Blog content type and the Author content type. The how and why of that relationship is the subject of the next blog!

This blog is part of a series on how I migrated away from a self-hosted Drupal blog to a modern JAM stack with Gatsby and Netlify CMS.