Illustration by Katerina Limpitsouniundraw.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 theGit-based headless CMS group. It works by committingmarkdown files to your repo. Alternatively you could also store your content asJSON, yml or toml.

Using Git as your content databasecomes 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 readingthis 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, withIdentity 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 betweenCollection types. Individual pages belong to thefile content type, whereas sets of similar content belong to thefolder content type.

You can have multiple of eithercollection types. You could have afile for the home page and another for the contact page. On the other hand you can have seperatefolder content types for blogs and authors.

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

# other CMS configurationcollections:-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:"Profilepicture",name:"profile_picture",widget:image,allow_multiple:false}-name:"pages"label:"Pages"files:-file:"src/pages/index.md"label:"Home"name:"index"fields:-{label:"Hometitle",name:title,widget:string}-file:"src/pages/contact/index.md"label:"Contact"name:"contact"fields:-{label:"Contacttitle",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 thewidget property. You got various options including textareas, file uploads and select fields. All available widgets can be viewedhere. If the widget you would like is not present, there's even the possibilityto 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:"Anawesomeblog"---**The body of the blog post**Typing`Markdown` as you*know it*

This metadata format is known asfrontmatter. Essentially, it isyaml syntax. All fields are saved as frontmatter data, except thebody field if the bodyfield 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 apreviewTemplate. 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 abeta 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 myGithub 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.