Netlify CMS for Jekyll Site
Overview of set-up and configuration
Easy Integration
The Netlify CMS is a great option for creating a customizable template for editing content on your Jekyll site. It is an open-source React application that offers the capability to edit and add text and/or media to your site with a real-time preview. There’s a wide range of customization options available via UI widgets and plugins.
Once your Netlify site is connected to the GitHub repo for your project, you’ll also have access to previews of pull requests and the CMS editor page.
Configuration
The quickest way to get started is to use a template. However, if you already have an existing site, you’ll want to follow this tutorial to get familiar with the process. In this article, we’ll expand on the concepts and steps included there.
Before diving in, make sure that your Netlify site is connected to your project’s repo. You can do this by logging into your Netlify account, selecting the current site you’re working on, click on the Build & Deploy tab on the left and add the GitHub repo URL to the Repository field in Build settings.
While you’re there, go ahead and add ‘jekyll build’ to the build command field and ‘_site/’ to the publish directory. Because the content for a static site is generated right before each time it is served, we want to run the jekyll build command when a user navigates to your site. The publish directory tells Netlify which folder to read the site content from. The _site folder is an automatically generated folder that contains all the source code needed to process Jekyll Liquid and display our site content.
In order to give other users access to the CMS editor, we need to adjust some settings in the Identity section. By default, you can have a maximum of 1,000 active users during a current billing period. Under registration preferences, you can choose to leave the registration open meaning that anyone can create an account with an email and log in to make changes to the site. A more secure option is to make the registration invite-only which will allow you to send an invitation via email to a select group of people. You can read more details on adding identity users here.
Source Code Format
At this point, we need to make some changes to the source code. The first thing you’ll want to do is make sure that your project is utilizing the standard Jekyll site file structure. You can read more about from the Jekyll docs here. You can also check out my previous blog, Create a Static Site using Jekyll for more details.
Next, you’ll need an admin folder at the root directory that contains an index.html and config.yml file. Inside of the index.html, you’ll want to add some code that looks like the following to create a UI for your CMS editor.
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Site Content Manager</title>
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</head><body>
<!-- Include the script that builds page and powers Netlify CMS -->
<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
</body>
</html>
The config.yml is where we’ll house some backend configuration as well as details on content you’d like to be able to edit. The beginning of this file typically looks something like this:
backend:
name: git-gateway
branch: master
identity_url: "https://yoursite.com/.netlify/identity"
gateway_url: "https://yoursite.com/.netlify/git"
squash_merges: true
publish_mode: editorial_workflow
media_folder: "assets/img/uploads"
site_url: https://yoursite.com
logo_url: https://yoursite.com/assets/img/logo.svgIt’s important to note that YAML is very strict about indentations. If you don’t indent properly, you’ll definitely get some syntax errors and won’t be able to access the editor.
The top section describing the backend, links the Netlify git-gateway which holds your projects repo, defines the deployment branch, identity and gateway url.
Setting the publish mode to editorial workflow allows us to save drafts as a pull request in GitHub before committing those changes to the live site.
The media folder defines be where images and other assets can be viewed, deleted and added within the CMS. Make sure that it’s pointing to the folder were your assets are being stored in the source code.
Authorized users will be able to reach the CMS editor by adding /admin to the site’s homepage url. Since the default behavior after a user logs in to the CMS is to navigate back the site’s homepage, we’ll want to add a script to the index.html at the root of the project that pushes the browser window to the editor when an authorized user is logged in.
<script>
if (window.netlifyIdentity) {
window.netlifyIdentity.on("init", user => {
if (!user) {
window.netlifyIdentity.on("login", () => {
document.location.href = "/admin/";
});
}
});
}
</script>Map Editable Content
Now you should be able to log in and view the CMS editor page. However, you’ll probably notice that there’s no fields to edit and no preview showing. That’s because we haven’t done the crucial work of mapping editable content within our config.yml file.
Hopefully, you followed the Jekyll docs regarding file structure and are at least a little familiar with the concept of posts, pages, and collections. We’ll use the labels for existing posts, pages and collections to edit content in the front matter as well as add new data.
Here’s an example of how to set up editable content for a blog post in in the config.yml file under the previously written configuration settings.
collections:
- name: "blog"
label: "Blog"
folder: "_posts/"
create: true # Allow users to create new documents
slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
editor:
preview: false
fields: # The fields for each document, usually in front matter
- { 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",
displayFields: [display_name],
searchFields: [display_name],
valueField: "name", }
- { label: "Body", name: "body", widget: "markdown" }Widgets define the kind of content that we expect in a field. For example, if you use an image widget, a box will appear in that field with a button for the user to upload an image. The relation widget pulls in information from another collection. You can find a full list of available widgets here.
Additional Resources
Netlify offers quite a bit of documentation on setting up their CMS. They even offer guides for integration with an existing Jekyll site here. As always, I encourage you to dive more into the documentation and do some tutorials to get your hands in the source code examples. The best way to learn is by doing! Here’s some more references for you to explore.
