Jekyll

Introduction

This section will help you integrate Netlify CMS with a new or existing Jekyll project.

Jekyll is a blog-aware static site generator built with Ruby. Github Pages are powered by Jekyll, making it a popular choice for developer blogs and project pages.

If you’re starting a new project, the fastest route to publishing on a Jekyll website with Netlify CMS is to deploy a template on Netlify.

Setup

This guide will use the blog you get if you follow the really excellent official Jekyll step by step tutorial as a starting point. If you’re new to Jekyll - I recommended you start by following the tutorial so you know your way around your new blog. Otherwise you can clone this repo and checkout the without-cms branch.

Jekyll tutorial blog screenshot

Add Netlify CMS

Add admin/index.html

Create a file admin/index.html in the root of your repo - it should look like this:

<!-- admin/index.html -->
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Content Manager</title>
    <!-- Include the identity widget -->
    <script src="https://identity.netlify.com/v1/netlify-identity-widget.js" type="text/javascript"></script>
  </head>
  <body>
    <!-- Include the script that builds the page and powers Netlify CMS -->
    <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
  </body>
</html>

Add admin/config.yml

Create a file admin/config.yml in the root of your repo - it should look like this:

# config.yml

backend:
  name: git-gateway
  branch: main # Branch to update (optional; defaults to master)
media_folder: 'assets/uploads'
collections:
  - name: 'blog'
    label: 'Blog'
    folder: '_posts/'
    fields:
      - { name: Title }

Enable authentication for CMS users

Netlify CMS stores content in your online Git repository. Therefore, to make content changes, users need to authenticate with the corresponding Git provider to prove that they have read and write access to that content.

Follow the directions in the Introduction section to enable Netlify Identity and Git Gateway services for the backend, then add the Identity widget to render a login portal on the frontend.

CMS Configuration

Blog Collection

We’ll start by updating the blog collection. Blogging is baked into Jekyll, and the _posts/ directory uses some special conventions we’ll need to keep in mind as we configure Netlify CMS. Copy and paste the following into your config.yml.

collections:
  - name: 'blog'
    label: 'Blog'
    folder: '_posts/'
    create: true
    slug: '---'
    editor:
      preview: false
    fields:
      - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'post' }
      - { label: 'Title', name: 'title', widget: 'string' }
      - { label: 'Publish Date', name: 'date', widget: 'datetime' }
      - { label: 'Body', name: 'body', widget: 'markdown' }

A few things to note.

We set the slug to '---' because Jekyll requires this format for blog posts. year, month, and day will be extracted from the date field, and slug will be generated from the title field.
We added editor configuration with a field preview: false. This will eliminate the preview pane. Because Jekyll uses Liquid templates, there currently isn’t a good way to provide a preview of pages as you update the content.
The layout field default is set to post so Jekyll knows to use _layouts/post.html when it renders a post. This field is hidden because we want all posts to use the same layout.
The date and title field will be used by the slug - as noted above, Jekyll relies on the filename to determine a post’s publish date, but Netlify CMS does not pull date information from the filename and requires a frontmatter date field. Note Changing the date or title fields in Netlify CMS will not update the filename. This has a few implications:
- If you change the date or title fields in Netlify CMS, Jekyll won’t notice
- You don’t necessarily need to change the date and title fields for existing posts, but if you don’t the filenames and frontmatter will disagree in a way that might be confusing
- If you want to avoid these issues, use a regular Jekyll collection instead of the special _posts directory

Author Collection

In addition to _posts, the Jekyll tutorial blog includes a collection of authors in the _authors directory. Before we can configure Netlify CMS to work with the authors collection, we’ll need to make a couple tweaks to our Jekyll blog. Here’s the front matter for one of the authors.

short_name: jill
name: Jill Smith
position: Chief Editor

name has special meaning as a unique identifier in Netlify CMS, but as set up now our Jekyll blog is using short_name as the unique identifier for authors. For each author, update the frontmatter like so.

name: jill
display_name: Jill Smith
position: Chief Editor

then update _layouts/author.html, _layouts/post.html and staff.html accordingly.

<!-- _layouts/author.html -->
--- layout: default ---

<h1></h1>
<h2></h2>

<p>Netlify CMS is an open source content management system for your Git workflow that enables you to provide editors with a friendly UI and intuitive workflows. You can use it with any static site generator to create faster, more flexible web projects. Content is stored in your Git repository alongside your code for easier versioning, multi-channel publishing, and the option to handle content updates directly in Git.</p>

<p>At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub, GitLab, or Bitbucket API. This provides many advantages, including:</p>

<ul>
  <li><strong>Fast, web-based UI:</strong> With rich-text editing, real-time preview, and drag-and-drop media uploads.</li>
  <li><strong>Platform agnostic:</strong> Works with most static site generators.</li>
  <li><strong>Easy installation:</strong> Add two files to your site and hook up the backend by including those files in your build process or linking to our Content Delivery Network (CDN).</li>
  <li><strong>Modern authentication:</strong> Using GitHub, GitLab, or Bitbucket and JSON web tokens.</li>
  <li><strong>Flexible content types:</strong> Specify an unlimited number of content types with custom fields.</li>
  <li><strong>Fully extensible:</strong> Create custom-styled previews, UI widgets, and editor plugins.</li>
</ul>

<h2 id="netlify-cms-vs-netlify">Netlify CMS vs. Netlify</h2>

<p><a href="https://www.netlify.com/">Netlify.com</a> is a platform you can use to automatically build, deploy, serve, and manage your frontend sites and web apps. It also provides a variety of other features like form processing, serverless functions, and split testing. Not all Netlify sites use Netlify CMS, and not all sites using Netlify CMS are on Netlify.</p>

<p>The folks at Netlify created Netlify CMS to fill a gap in the static site generation pipeline. There were some great proprietary headless CMS options, but no real contenders that were open source and extensible—that could turn into a community-built ecosystem like WordPress or Drupal. For that reason, Netlify CMS is <em>made</em> to be community-driven, and has never been locked to the Netlify platform (despite the name).</p>

<p>With this in mind, you can:</p>

<ul>
  <li>Use Netlify CMS without Netlify and deploy your site where you always have, hooking up your own CI, site hosting, CDN, etc.</li>
  <li>Use Netlify without Netlify CMS and edit your static site in your code editor.</li>
  <li>Or, use them together and have a fully-working CMS-enabled site with <a href="../start-with-a-template/">one click</a>!</li>
</ul>

<p>If you hook up Netlify CMS to your website, you’re basically adding a tool for content editors to make commits to your site repository without touching code or learning Git.</p>

<h3 id="find-out-more">Find out more</h3>

<ul>
  <li>Get a feel for the UI in the <a href="https://cms-demo.netlify.com">demo site</a>. (No login required. Click the login button to go straight to the CMS editor UI.)</li>
  <li><a href="../start-with-a-template/">Start with a template</a> to make a Netlify CMS-enabled site of your own.</li>
  <li>Configure your existing site by following a <a href="../add-to-your-site/">tutorial</a> or checking <a href="../configuration-options">configuration options</a>.</li>
  <li>Ask questions and share ideas in the Netlify CMS <a href="https://netlifycms.org/chat">community chat</a>.</li>
  <li>Get involved in new developments and become a <a href="../contributor-guide/">contributor</a>.</li>
</ul>


<h2>Posts</h2>
<ul>
   
</ul>

<!-- _layouts/post.html -->
--- layout: default ---

<h1>Jekyll</h1>

<p>
    
</p>

<p>Netlify CMS is an open source content management system for your Git workflow that enables you to provide editors with a friendly UI and intuitive workflows. You can use it with any static site generator to create faster, more flexible web projects. Content is stored in your Git repository alongside your code for easier versioning, multi-channel publishing, and the option to handle content updates directly in Git.</p>

<p>At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub, GitLab, or Bitbucket API. This provides many advantages, including:</p>

<ul>
  <li><strong>Fast, web-based UI:</strong> With rich-text editing, real-time preview, and drag-and-drop media uploads.</li>
  <li><strong>Platform agnostic:</strong> Works with most static site generators.</li>
  <li><strong>Easy installation:</strong> Add two files to your site and hook up the backend by including those files in your build process or linking to our Content Delivery Network (CDN).</li>
  <li><strong>Modern authentication:</strong> Using GitHub, GitLab, or Bitbucket and JSON web tokens.</li>
  <li><strong>Flexible content types:</strong> Specify an unlimited number of content types with custom fields.</li>
  <li><strong>Fully extensible:</strong> Create custom-styled previews, UI widgets, and editor plugins.</li>
</ul>

<h2 id="netlify-cms-vs-netlify">Netlify CMS vs. Netlify</h2>

<p><a href="https://www.netlify.com/">Netlify.com</a> is a platform you can use to automatically build, deploy, serve, and manage your frontend sites and web apps. It also provides a variety of other features like form processing, serverless functions, and split testing. Not all Netlify sites use Netlify CMS, and not all sites using Netlify CMS are on Netlify.</p>

<p>The folks at Netlify created Netlify CMS to fill a gap in the static site generation pipeline. There were some great proprietary headless CMS options, but no real contenders that were open source and extensible—that could turn into a community-built ecosystem like WordPress or Drupal. For that reason, Netlify CMS is <em>made</em> to be community-driven, and has never been locked to the Netlify platform (despite the name).</p>

<p>With this in mind, you can:</p>

<ul>
  <li>Use Netlify CMS without Netlify and deploy your site where you always have, hooking up your own CI, site hosting, CDN, etc.</li>
  <li>Use Netlify without Netlify CMS and edit your static site in your code editor.</li>
  <li>Or, use them together and have a fully-working CMS-enabled site with <a href="../start-with-a-template/">one click</a>!</li>
</ul>

<p>If you hook up Netlify CMS to your website, you’re basically adding a tool for content editors to make commits to your site repository without touching code or learning Git.</p>

<h3 id="find-out-more">Find out more</h3>

<ul>
  <li>Get a feel for the UI in the <a href="https://cms-demo.netlify.com">demo site</a>. (No login required. Click the login button to go straight to the CMS editor UI.)</li>
  <li><a href="../start-with-a-template/">Start with a template</a> to make a Netlify CMS-enabled site of your own.</li>
  <li>Configure your existing site by following a <a href="../add-to-your-site/">tutorial</a> or checking <a href="../configuration-options">configuration options</a>.</li>
  <li>Ask questions and share ideas in the Netlify CMS <a href="https://netlifycms.org/chat">community chat</a>.</li>
  <li>Get involved in new developments and become a <a href="../contributor-guide/">contributor</a>.</li>
</ul>

<!-- staff.html -->
--- layout: default ---

<h1>Staff</h1>

<ul>
  
</ul>

Next, copy and paste the following into the collections array in config.yml below the blog collection.

- name: 'authors'
  label: 'Authors'
  folder: '_authors/'
  create: true
  editor:
    preview: false
  fields:
    - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'author' }
    - { label: 'Short Name', name: 'name', widget: 'string' }
    - { label: 'Display Name', name: 'display_name', widget: 'string' }
    - { label: 'Position', name: 'position', widget: 'string' }
    - { label: 'Body', name: 'body', widget: 'markdown' }

Now that we have the authors collection configured, we can add an author field to the blog collection. We’ll use the relation widget to define the relationship between blog posts and authors.

# updated fields in blog collection configuration
fields:
  - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'post' }
  - { label: 'Title', name: 'title', widget: 'string' }
  - { label: 'Publish Date', name: 'date', widget: 'datetime' }
  - {
      label: 'Author',
      name: 'author',
      widget: 'relation',
      collection: 'authors',
      display_fields: [display_name],
      search_fields: [display_name],
      value_field: 'name',
    }
  - { label: 'Body', name: 'body', widget: 'markdown' }

With that configuration added, you should be able to select the author for a post from a dropdown.

About Page

Our Jekyll blog includes an About page. It would nice to be able to edit that page just like we can edit our blog and author pages. Netlify CMS provides file collections to solve this problem.

Copy and paste the following into the collections array in config.yml

- name: 'pages'
  label: 'Pages'
  editor:
    preview: false
  files:
    - label: 'About Page'
      name: 'about'
      file: 'about.md'
      fields:
        - { label: 'Title', name: 'title', widget: 'hidden', default: 'about' }
        - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'about' }
        - { label: 'Body', name: 'body', widget: 'markdown' }

The last aspect of our Jekyll blog we might want to bring under the control of Netlify CMS is our Navigation menu. Our Jekyll tutorial blog has a file _data/navigation.yml that defines the links rendered by _includes/navigation.html. It looks like this.

# _data/navigation.yml
- name: Home
  link: /
- name: About
  link: /about.html
- name: Blog
  link: /blog.html
- name: Staff
  link: /staff.html

To make this file editable with Netlify CMS, we’ll need to make one minor tweak. The issue is this file contains a yaml array at the top level, but Netlify CMS is designed to work with yaml objects. Update _data/navigation.yml so it looks like so.

# _data/navigation.yml
items:
  - name: Home
    link: /
  - name: About
    link: /about.html
  - name: Blog
    link: /blog.html
  - name: Staff
    link: /staff.html

<nav>
  
</nav>

Finally, add the following to the collections array in config.yml

- name: 'config'
  label: 'Config'
  editor:
    preview: false
  files:
    - label: 'Navigation'
      name: 'navigation'
      file: '_data/navigation.yml'
      fields:
        - label: 'Navigation Items'
          name: 'items'
          widget: 'list'
          fields:
            - { label: Name, name: name, widget: string }
            - { label: Link, name: link, widget: string }

Now you can add, rename, and rearrange the navigation items on your blog.