In this tutorial, I will walk you through adding the Netlify CMS to your existing Hugo site. The Netlify CMS is an open source content management system that will allow authorized editors to add or edit content on your site using an easy to use user interface. In this tutorial, we will be adding the Netlify CMS to a Hugo site, but you can add it to any site that you would like as long as it was built by a static site generator.
This tutorial also assumes that your site is deployed on Netlify. The steps will be different if your site is not deployed on Netlify. Refer to my tutorial on deploying to Netlify if you don’t know how to do that.
File Structure
First, you will need to create a directory in the static directory called admin
. In this folder, you will create two files: index.html
and config.yml
. Your file structure should look something like this:
.(project root directory)
├── archetypes
├── content
├── data
├── layouts
├── public
├── resources
├── static
│ └── admin
│ └── index.html
│ └── config.yml
└── config.yaml
admin/index.html
is the entry point for the Netlify CMS, so users will navigate to your_url.com/admin
to access the CMS. In the index.html
file, copy and paste the following:
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Content Manager</title>
</head>
<body>
<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
</body>
</html>
Configuration
Now, let’s edit the config.yml
file. If your repository is on Github or Gitlab, add the following code to the config.yml
file.
backend:
name: git-gateway
branch: main # name of your branch (mine defaults to main but yours might be master)
If you’re using Bitbucket, please refer to the Bitbucket backend instructions.
Note: If you leave out the branch declaration, it defaults to master. As of October 2020, Github changed the default branch name to main instead of master, so be sure to check to see what your default branch is called.
Here’s a starter config.yml
file to get you going.
backend:
name: git-gateway
branch: main
collections:
- name: "post"
label: "Post"
folder: "content/posts"
create: true
fields:
- { label: "Title", name: "title", widget: "string" }
- { label: "Date", name: "date", widget: "datetime" }
- { label: "Body", name: "body", widget: "markdown" }
- { label: "Tags", name: "tags", widget: "list" }
- { label: "Categories", name: "categories", widget: "list" }
- { label: "Description", name: "description", widget: "string"}
Now, let’s talk about what all of that collection stuff means.
For example, let’s say that you have posts stored in content/posts/
and you have a some blog post saved as my_blog_post.md
in the posts
folder. Each post begins with settings in yaml-formatted front matter. It will look something like this:
---
title: Sample Post
date: 2022-07-21T22:42:02.326Z
tags: ["Tutorial"]
description: A description of your blog post
---
Content goes here...
The corresponding config.yml
file would look like this:
collections:
- name: "post"
label: "Post"
folder: "content/posts"
create: true
fields:
- { label: "Title", name: "title", widget: "string" }
- { label: "Date", name: "date", widget: "datetime" }
- { label: "Tags", name: "tags", widget: "list" }
- { label: "Description", name: "description", widget: "string"}
- { label: "Body", name: "body", widget: "markdown" }
These fields described in the config.yml
file correspond to the front matter in the posts themselves, so you will need to define all of the fields in your configuration that you would like to include in the front matter of your posts.
You can read more about what you can include in the Netlify collection documentation.
Netlify Identity
Assuming your site is already deployed on Netlify, navigate to your sites dashboard and preform the following steps:
- Go to Site Settings > Identity
- Click on Enable Identity Service
- Scroll to Registration Preferences and select Invite Only. This will only allow users access to your Netlify CMS if they are invited. If you would like, you can keep this open, but anyone will be able to register for access.
- Scroll to Services > Git Gateway and select Enable Git Gateway
Now, you must add the Netlify Identity widget to your site. In the previous step, we set up the backend to handle authentication and in this step we will set up the frontend for the user to use.
You will need to add the following script to two places.
<script src=“https://identity.netlify.com/v1/netlify-identity-widget.js”></script>
- Add to the
<head>
of yourindex.html
file in theadmin
folder. - Add to the
<head>
of your site’s mainindex.html
file. This may require you to overwrite a partial depending on what theme you are using.
You will also need to add the following code to your site’s main index.html
file before the closing body
tag. This may also require you to overwrite a partial depending on your theme.
<script>
if (window.netlifyIdentity) {
window.netlifyIdentity.on("init", user => {
if (!user) {
window.netlifyIdentity.on("login", () => {
document.location.href = "/admin/";
});
}
});
}
</script>
Access Netlify CMS
If you set your registration preferences to Invite Only, from the site dashboard, click on the Identity tab, and then click Invite Users. Here you will be able to invite a user by inputting their email address. They will get an email invitation with a confirmation link.
If you left your site open, navigate to your_url.com/admin
to register.
That’s it! You can now access the CMS by navigating to your_url.com/admin
.