A Step-by-Step Guide: Jekyll Netlify CMS

Welcome to Netlify CMS, the first static site CMS system that can easily be integrated with almost any static site generator!

I know—it sounds too good to be true, but the age where static sites were defined by a lack of dynamic content, user interactivity, and a CMS system is finally over!

In this guide, we’ll show you how to install and configure your own copy of our jekyll-netlify-cms template.

This guide assumes that you have Ruby and bundler installed

Netlify CMS Environments

Before we start, let’s discuss Netlify CMS and environments. It’s possible to run a netlify-git-api server locally or set the environment variable to production and use GitHub’s API when your site goes live. We will describe both methods; first setting up locally, followed by deploying to Netlify.

Setup your GitHub Repository

We’ll start by getting our own copy of the template and configure a local version before letting Netlify build it.

1. Get your own copy

Fork your own copy of the jekyll-netlify-cms template and give it a new name. If you are new to this, visit GitHub’s help desk to learn how to fork a repository.

2. Local Work Space

Create a local directory, open the terminal, and navigate to your local directory (cd my-local-repo-directory). This will be the location of your local site. Keep the terminal window open throughout this guide.

3. Get Repository URL

From the repo created above, clone a copy to your local directory. Copy the remote GitHub URL (it will look like https://github.com/AccountName/RepoName.git). Then, in the terminal window at your local repo directory, run:

git clone my-repo-url

Netlify CMS: Local Environment

To set up the Netlify CMS, first set up the web configuration in the config.yml of the admin folder of the site:

/my-site-location/admin/config.yml

Open the file and check which repo and branch the backend points to, you can also set the local URL. Here’s an example of the config.yml:

development:
  backend:
    name: netlify-api
    url: http://localhost:8080
production:
  backend:
    name: github-api
    repo: owner/repo # Path to your GitHub repository
    branch: master # Branch to update (master by default)

1. The Netlify Git API

Set this up on your local computer as well as online. Start by downloading the netlify-git-api that corresponds to your OS here. Decompress the netlify-cms-api file and add it to your path.

On Linux, use the following commands:

cd 'downloads'
unzip linux.zip
cd linux
sudo mv netlify-git-api '/usr/local/bin'

2. Setup your Gemfile

Open the Gemfile and change/add the following:

gem 'jekyll', '~> 3.0.0'
gem 'jekyll-sitemap'

3. Bundle Install

Install the jekyll gem specified in the Gemfile with:

bundle install

4. Create Netlify CMS Users

From the terminal window in your local repo directory, run the following command for each user you wish to add:

netlify-git-api users add

Alternatively, you can add a user in one line:

netlify-git-api users add --name='User Name' --email=my@email.com --password=mypassword

5. Start Netlify CMS Server

Start the Netlify CMS server locally with:

netlify-git-api serve

Keep the Terminal Window open to keep the server running!

6. Build and Watch

Open a second terminal window to build your site using bundle:

bundle exec jekyll server --watch

7. Test the System

Open a browser to the following address, log in, and create a new post: https://localhost:4000/admin

Online Environment

Once your local version is ready, it’s time to try Netlify CMS with Jekyll in an online environment.

Navigate to the root folder of your site and check where the project is pushed to:

git remote -v

If happy with the result, add the new files:

git add .

Commit the files in your local repository:

git commit -m 'First commit'

Finally, push the project to GitHub:

git push -u origin master

Connect to Netlify and Deploy to Production Environment

Step 1: Add Your New Site

Creating a new site on Netlify is simple. Once you have created an account and logged in, visit https://app.netlify.com/sites and click the “New Site” button to get started.

Step 2: Link to Your GitHub

Click “Link to GitHub” to connect Netlify and GitHub.

Step 3: Authorize Netlify

Provide your GitHub login details. Review the permissions and authorize the application.

Step 4: Choose Your Repo

Once connected to GitHub, select the “jekyll-netlify-cms-demo” repo you previously pushed.

Step 5: Configure Your Settings

Set an environment variable under the environment tab:

JEKYLL_ENV = production

Step 6: Build Your Site

Click save, and Netlify will manage the build process for you.

Step 7: Register new Application.

Open the GitHub developer application screen and register a new application with the exact URL for the Authorization callback:

https://api.netlify.com/auth/done

Step 8: Setup GitHub API Access

In Netlify, select the Access panel and enter the Client ID and Client Secret from your registered app.

Step 9: Trying Out Netlify CMS

To test the CMS online, modify the address to https://mysite.netlify.com/admin and log in with GitHub credentials.