Netlify CMS

Netlify CMS is a single-page React app that allows user to create and add markdown content directly to a GitHub repository. Thus, it is commonly used with static site generators such as GatsbyJS.

Usage in GatsbyJS

gatsby-plugin-netlify-cms

The best way to add Netlify CMS to a Gatsby site is to use a plugin called Gatsby-plugin-netlify-cms. Follow the following steps to add it:

yarn add netlify-cms-app gatsby-plugin-netlify-cms

After the node modules have been installed, update the configuration of Gatsby in the gatsby-config.js so that Gatsby recognize the plugin:

plugins: [`gatsby-plugin-netlify-cms`]

Finally, add a Netlify CMS configuration file in static/admin/config.yml. I use the following config for my sites:

backend:
  name: github
  repo: nguyentran0212/alisa-commonplace
site_url: https://alisa.nk-tran.com
media_folder: "static/assets"
public_folder: "/assets"
collections:
  - name: "communication"
    label: "Communication"
    folder: "content/communication"
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}
  - name: "conflict-resolution"
    label: "Conflict Resolution"
    folder: "content/conflict-resolution"
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}
  - name: "music-lesson"
    label: "Music Lesson"
    folder: "content/music-lesson"
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}
  - name: "top-level"
    label: "Top Level Content"
    folder: "content"
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Body", name: "body", widget: "markdown"}

The editor interface will be available at /admin/

Add OAuth for GitHub backend

The editor requires authorisation to work. I can use GitHub OAuth for this purpose. To make it happen, I need to

1. Add an OAuth application to my GitHub account
2. Add client ID and secret to the OAuth provider running on Netlify

Here are the instructions provided by Netlify url:

1. In GitHub, go to your account Settings, and click Oauth Applicationsunder Developer Settings (or use this shortcut).
2. Select Register a new application.
3. For the Authorization callback URL, enter https://api.netlify.com/auth/done. The other fields can contain anything you want.

When you complete the registration, you'll be given a Client ID and a Client Secret for the app. You'll need to add these to your Netlify site:

1. From your site dashboard, go to Settings > Access control > OAuth.
2. Under Authentication Providers, click Install Provider.
3. Select GitHub and enter the Client ID and Client Secret, then save.

If a user does not have access right to the repository, the netlify CMS would reject the logging.