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.
Add Netlify CMS
Add admin/index.html
Create a file admin/index.html in the root of your repo – it should look like this:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Content Manager</title>
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js" type="text/javascript"></script>
</head>
<body>
<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:
backend:
name: git-gateway
branch: main
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: '{{year}}-{{month}}-{{day}}-{{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 '{{year}}-{{month}}-{{day}}-{{slug}}' 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.
--- layout: default ---
<h1>{{ page.display_name }}</h1>
<h2>{{ page.position }}</h2>
{{ content }}
<h2>Posts</h2>
<ul>
{% assign filtered_posts = site.posts | where: 'author', page.name %} {% for post in
filtered_posts %}
<li>
<a href="{{ site.baseurl }}{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
--- layout: default ---
<h1>{{ page.title }}</h1>
<p>
{{ page.date | date_to_string }} {% assign author = site.authors | where: 'name', page.author |
first %} {% if author %} - <a href="{{ author.url }}">{{ author.display_name }}</a>
{% endif %}
</p>
{{ content }}
--- layout: default ---
<h1>Staff</h1>
<ul>
{% for author in site.authors %}
<li>
<h2>
<a href="{{ site.baseurl }}{{ author.url }}">{{ author.display_name }}</a>
</h2>
<h3>{{ author.position }}</h3>
<p>{{ author.content | markdownify }}</p>
</li>
{% endfor %}
</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.
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' }
Navigation
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.
- 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.
items:
- name: Home
link: /
- name: About
link: /about.html
- name: Blog
link: /blog.html
- name: Staff
link: /staff.html
You’ll need to update _includes/navigation.html accordingly. {% for item in site.data.navigation %} should be changed to {% for item in site.data.navigation.items %}. When you’re done, the nav html should look like this.
<nav>
{% for item in site.data.navigation.items %}
<a href="{{ site.baseurl }}{{ item.link }}" {% if page.url == item.link %}style="color: red;"{% endif %}>
{{ item.name }}
</a>
{% endfor %}
</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.
