© Joe Attardi 2020
J. AttardiUsing Gatsby and Netlify CMShttps://doi.org/10.1007/978-1-4842-6297-9_4

4. Setting Up Netlify CMS

Joe Attardi1 
(1)
Billerica, MA, USA
 

Let’s dive right in and start building the coffee shop site. The first step is to install and configure Netlify CMS and integrate it with Gatsby.

Install dependencies

We first need to install a few packages from npm:

  • netlify-cms-app: The Netlify CMS application itself

  • gatsby-plugin-netlify-cms: The Netlify CMS Gatsby plugin

Open a terminal, go to the project directory, and type the command to install these packages. Note that we are installing specific versions. This is because by default, npm installs the latest version of a package, and there may be later breaking changes that do not work with the example project in this book. To prevent this, it is best to install specific versions:
npm install [email protected]
            [email protected]

Configuration

Netlify CMS is configured with a YAML file named config.yml.

YAML primer

YAML, short for YAML Ain’t Markup Language (a recursive acronym!), is a commonly used configuration file format. The Netlify CMS configuration file is a set of key/value pairs, also known as a dictionary. The value can be a scalar value (string, number, boolean, and so on), another dictionary, or an array.

Keys and values in a dictionary are separated by a colon, as shown in Listing 4-1.
name: Joe
email: [email protected]
Listing 4-1

A simple YAML dictionary

Dictionaries can also be specified on a single line with curly braces, as shown in Listing 4-2.
{ name: 'Joe', email: '[email protected]' }
Listing 4-2

A single-line YAML dictionary

An array is a sequence of values. Each item of an array begins with a dash character on its own line, followed by the value (which may take up multiple lines). Listing 4-3 is an example of an array.
- name: Joe Attardi
  email: [email protected]
- name: John Doe
  email: [email protected]
- name: Jane Doe
  email: [email protected]
Listing 4-3

A YAML array

In more complex structures, there can be arrays of dictionaries, dictionaries of arrays, or a combination of both, as shown in Listing 4-4.
name: John Doe
contact:
  - type: email,
    value: [email protected]
  - type: phone,
    value: 617-555-1234
skills:
  - javascript
  - html
Listing 4-4

A more complex YAML structure

Creating the initial configuration

Inside the static directory, create a new directory called admin. Inside that directory, create the configuration file, config.yml. Finally, inside the configuration file, add the initial configuration, shown in Listing 4-5.
backend:
  name: git-gateway
  branch: master
media_folder: static/img
public_folder: /img
Listing 4-5

The initial CMS configuration

Let’s go over this configuration. First, we configure the Netlify CMS backend. There are several supported backends, but we are using the Git Gateway backend. This is a generic backend that uses our Git repository as the data store and Netlify Identity for authentication to the CMS application.

The media_folder option is the path on disk that static media resources will be kept. When a user uploads new images via the CMS, they will be saved to this directory. When the image cat.gif is uploaded, it will be stored as static/img/cat.gif in the repository.

The public_folder option is the URL, relative to the Gatsby site’s root, that the images will be served from. When running the site locally, for example, cat.gif will be served from http://localhost:8000/img/cat.gif.

Now we need some content for our CMS to manage. The site will have a blog, so let’s look at collections and set up a blog collection.

Collections

All pieces of content managed by Netlify CMS are members of a collection. Collections are configured in the config.yml file. There are a few different types of collections.

Folder collections

A folder collection represents content items in a common format, stored under a common folder. New items can be added to a folder collection via the UI. All files under the given folder will be part of the folder collection and are expected to have a consistent structure.

A folder collection is configured by setting a folder property in the collection configuration. We will use a folder collection for the blog posts.

Filtered folder collections

It is possible to have varied files under the same folder by using filtered folder collections. Like folder collections, the content files are all located under one folder, but you can specify filter criteria to only select certain files in that folder.

Like folder collections, a filtered folder collection needs to have a folder property that specifies the common containing folder. Additionally, there is a filter property that specifies criteria. Only files matching the criteria will be included in the filtered folder collection. An example filter criteria is { field: "language", value: "en" }. This collection will only include files with a language of en.

File collections

While folder collections are general-purpose collections that can contain arbitrary files, a file collection explicitly defines specific files that should be part of that collection. Only those files will be included in the collection. To set up a file collection, the collection configuration should have a files property that is an array of files.

A file collection would be used for defining pages of a site that can have dynamically managed content, for example, a Home or About page.

Configuring the blog collection

Let’s add our first collection. In config.yml, create a collections section and fill it in as shown in Listing 4-6.
collections:
  - name: "blog"
    label: "Blog"
    folder: "src/blog"
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - label: "Title"
        name: "title"
        widget: "string"
      - label: "Publish Date"
        name: "date"
        widget: "datetime"
      - label: "Body"
        name: "body"
        widget: "markdown"
Listing 4-6

Configuration for the blog collection

First, we give the collection a name. This is the name that the collection will be referred to by internally. The label property specifies the display name in the UI for this collection.

The folder property sets the root folder where the blog posts will reside, relative to the project root.

The create property determines whether or not new items can be created in this collection using the CMS application.

Next is the slug property, which defines the pattern to use for constructing the slugs of blog posts. A slug is a URL-friendly, human-readable version of a string. Each blog post’s URL will contain this configured slug. An example slug for a blog post might look like this: 2020-06-20-hello-world. Blog post titles will be turned into slugs when creating pages for the posts. For example, the blog post title “Here’s Blog Post #2!” might have a slug of heres-blog-post-2.

Lastly, we configure the fields for this collection. We will keep it simple here. Each blog post has a title, publish date, and a body. Each field has a widget type specified. This determines the UI control that is used for editing that value in the CMS application.

More about fields

By default, fields are required. Netlify CMS will not allow an entry to be published unless all required fields have a value. A field can be marked as optional by specifying a required: false option in the collection’s configuration.

Fields also support basic validation. You can specify a pattern property. The value of this property should be an array. The first element of the array is a regular expression string, and the second element is the error message to display if the input doesn’t match the regular expression.

Blog posts will be stored as Markdown files. Each field is set as a property in the front matter, except for the body field. When Netlify CMS sees a body field with a widget type of markdown, it stores that field as the main body of the Markdown file rather than inside the front matter.

Listing 4-7 shows what an example blog post in this collection might look like.
---
title: Hello World!
date: "2020-03-05T22:40:32.169Z"
---
Hello World! This is my first blog post.
Listing 4-7

An example blog post

Add the Gatsby plugin

The last step is to configure the Gatsby plugin. Open the gatsby-config.js file in the root of the project. Add a plugins section with a single plugin, gatsby-plugin-netlify-cms, as shown in Listing 4-8.
module.exports = {
  siteMetadata: {
    title: 'The Coffee Blog'
  },
  plugins: [
    'gatsby-plugin-netlify-cms'
  ]
};
Listing 4-8

Updated Gatsby configuration

Commit and deploy

Before we can use the Netlify CMS application to add a blog post, we need to deploy a new version of the site which contains the config.yml file and the Netlify CMS application itself. Let’s pause here, make a commit, and push to GitHub.
git add .
git commit -m "Add initial configuration"
git push origin master

After a moment, Netlify will see that you pushed to the master branch and will build and deploy the new version of the site.

Configure Netlify Identity and Git Gateway

The last thing to do before we can add a new blog post is to configure Netlify Identity and Git Gateway. Netlify Identity is a built-in basic identity provider that administrators of your site can use to log in and use the CMS to add and manage content.

To do this, you’ll need to log in to your Netlify account. Once you’ve done this, click your site to go to the site dashboard. Then, click “Site settings.” This will load your site settings screen. On the left side of the screen, click the “Identity” link. Netlify Identity is not currently enabled, so you should see a button labeled “Enable Identity.” Click that button to begin.
../images/502348_1_En_4_Chapter/502348_1_En_4_Fig1_HTML.jpg
Figure 4-1

The Identity tab

Once you click the button, Identity will be enabled immediately, and you’ll be presented with the Identity settings screen. Click the “Registration” link. For now, we’ll use open registration for convenience.
../images/502348_1_En_4_Chapter/502348_1_En_4_Fig2_HTML.jpg
Figure 4-2

Open registration enabled

Next, we’ll enable Git Gateway for the site. Click the “Services” link on the left under “Identity,” and click the “Enable Git Gateway” button.
../images/502348_1_En_4_Chapter/502348_1_En_4_Fig3_HTML.jpg
Figure 4-3

Enabling Git Gateway

After clicking the button, a new window will pop up prompting you to grant additional permissions to Netlify Auth. Click the “Authorize netlify” button.
../images/502348_1_En_4_Chapter/502348_1_En_4_Fig4_HTML.jpg
Figure 4-4

Granting additional permissions

After you grant these permissions, you will be redirected back to the Netlify settings page, where you will see that Git Gateway has been enabled.
../images/502348_1_En_4_Chapter/502348_1_En_4_Fig5_HTML.jpg
Figure 4-5

Git Gateway enabled

Git Gateway adds several endpoints under /.netlify/git/github that act as a proxy to GitHub’s API from our site. These endpoints will be called by the CMS when content is added, modified, or removed.

More about Netlify Identity

We are using Identity Level 0, which is the free tier of Netlify Identity. With that, you get up to 1,000 active users and 5 invite-only users. If this does not meet your needs, there are also paid levels of Identity with higher user limits and more features such as custom branded log-in pages, audit logs, and single sign on via SAML.

Invite-only registration

We configured open registration, so a user can sign up at the log-in screen of the CMS. You can also set registration to invite-only. In this configuration, you can invite users via the Netlify Identity settings UI, and users will not be able to sign themselves up.

To enable invite-only registration, from the Settings page, go to “Identity”: “Registration,” and click “Edit”. A form will be displayed where you can change the registration to be invite-only.
../images/502348_1_En_4_Chapter/502348_1_En_4_Fig6_HTML.jpg
Figure 4-6

Editing registration preferences for Netlify Identity

Summary

In this chapter, we

  • Installed Netlify CMS and the Netlify CMS Gatsby plugin

  • Configured the blog collection

  • Enabled Netlify Identity and Git Gateway

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.137.162.105