---
group: Guides
title: Jekyll
weight: 30
---
## Introduction
This section will help you integrate Static CMS with a new or existing Jekyll project.
[Jekyll](https://jekyllrb.com/) is a blog-aware static site generator built with Ruby. [Github Pages](https://pages.github.com/) 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 Static CMS is to [deploy a template on Netlify](https://templates.netlify.com/).
## Setup
This guide will use the blog you get if you follow the [really excellent official Jekyll step by step tutorial](https://jekyllrb.com/docs/step-by-step/01-setup/) 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](https://github.com/adamwatters/jekyll-tutorial-with-netlify-cms/tree/without-cms) and checkout the `without-cms` branch.
## Add Static CMS
### Add admin/index.html
Create a file `admin/index.html` in the root of your repo - it should look like this:
```html
Content Manager
```
### Add admin/config.yml
Create a file `admin/config.yml` in the root of your repo - it should look like this:
```yml
# config.yml
backend:
title: git-gateway
branch: main # Branch to update (optional; defaults to main)
media_folder: 'assets/uploads'
collections:
- title: 'blog'
label: 'Blog'
folder: '_posts/'
fields:
- { title: Title }
```
### Enable authentication for CMS users
Static 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](/docs/add-to-your-site/#enable-identity-and-git-gateway) for the backend, then [add the Identity widget](/docs/add-to-your-site/#add-the-netlify-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](https://jekyllrb.com/docs/posts/) we'll need to keep in mind as we configure Static CMS. Copy and paste the following into your `config.yml`.
```yaml
collections:
- title: 'blog'
label: 'Blog'
folder: '_posts/'
create: true
slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
editor:
preview: false
fields:
- { label: 'Layout', title: 'layout', widget: 'hidden', default: 'post' }
- { label: 'Title', title: 'title', widget: 'string' }
- { label: 'Publish Date', title: 'date', widget: 'datetime' }
- { label: 'Body', title: '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](https://jekyllrb.com/docs/posts/#creating-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 Static CMS does not pull date information from the filename and requires a frontmatter `date` field. **Note** Changing the `date` or `title` fields in Static CMS will not update the filename. This has a few implications:
* If you change the `date` or `title` fields in Static 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 Static 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.
```yaml
short_title: jill
title: Jill Smith
position: Chief Editor
```
`name` has special meaning as a unique identifier in Static 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.
```yaml
title: jill
display_title: Jill Smith
position: Chief Editor
```
then update `_layouts/author.html`, `_layouts/post.html` and `staff.html` accordingly.
```html
--- layout: default ---
{{ page.display_name }}
{{ page.position }}
{{ content }}
Posts
{% assign filtered_posts = site.posts | where: 'author', page.name %} {% for post in
filtered_posts %}
```
Next, copy and paste the following into the collections array in `config.yml` below the `blog` collection.
```yaml
- title: 'authors'
label: 'Authors'
folder: '_authors/'
create: true
editor:
preview: false
fields:
- { label: 'Layout', title: 'layout', widget: 'hidden', default: 'author' }
- { label: 'Short Name', title: 'name', widget: 'string' }
- { label: 'Display Name', title: 'display_name', widget: 'string' }
- { label: 'Position', title: 'position', widget: 'string' }
- { label: 'Body', title: '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](/docs/widgets/#relation) to define the relationship between blog posts and authors.
```yaml
# updated fields in blog collection configuration
fields:
- { label: 'Layout', title: 'layout', widget: 'hidden', default: 'post' }
- { label: 'Title', title: 'title', widget: 'string' }
- { label: 'Publish Date', title: 'date', widget: 'datetime' }
- {
label: 'Author',
title: 'author',
widget: 'relation',
collection: 'authors',
display_fields: [display_name],
search_fields: [display_name],
value_field: 'name',
}
- { label: 'Body', title: '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. Static CMS provides [file collections](/docs/collection-types/#file-collections) to solve this problem.
Copy and paste the following into the collections array in `config.yml`
```yaml
- title: 'pages'
label: 'Pages'
editor:
preview: false
files:
- label: 'About Page'
title: 'about'
file: 'about.md'
fields:
- { label: 'Title', title: 'title', widget: 'hidden', default: 'about' }
- { label: 'Layout', title: 'layout', widget: 'hidden', default: 'about' }
- { label: 'Body', title: 'body', widget: 'markdown' }
```
### Navigation
The last aspect of our Jekyll blog we might want to bring under the control of Static 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.
```yaml
# _data/navigation.yml
- title: Home
link: /
- title: About
link: /about.html
- title: Blog
link: /blog.html
- title: Staff
link: /staff.html
```
To make this file editable with Static CMS, we'll need to make one minor tweak. The issue is this file contains a yaml array at the top level, but Static CMS is designed to work with yaml objects. Update `_data/navigation.yml` so it looks like so.
```yaml
# _data/navigation.yml
items:
- title: Home
link: /
- title: About
link: /about.html
- title: Blog
link: /blog.html
- title: 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.
```html
```
Finally, add the following to the collections array in `config.yml`
```yaml
- title: 'config'
label: 'Config'
editor:
preview: false
files:
- label: 'Navigation'
title: 'navigation'
file: '_data/navigation.yml'
fields:
- label: 'Navigation Items'
title: 'items'
widget: 'list'
fields:
- { label: Name, title: name, widget: string }
- { label: Link, title: link, widget: string }
```
Now you can add, rename, and rearrange the navigation items on your blog.