How to set up Netlify CMS for static website?

Netlify CMS is one of the most requested features by all the authors who own static websites. I'm personally running my blog from last 3 years on Hugo static site framework and I am really happy with my website performance but when I read some posts on the Netlify forum about Netlify CMS, it made me curious as well as surprised because how come a the static website is managed via CMS when it does not have any kind of database layer to store the information.

I started digging more and did some google around the topic Netlify CMS and was very much surprised that Netlifycms. org exist. Well, now I got one more interesting project to work on.

Why I was so interested and excited about Netlify CMS?- Because I have been writing my blog post using MarkDown for really long time, although I do not complain about Markdown with NetlifyCMS I can write my blog from my iPad and save my changes to my GitHub repository.

In this blog post, I will be documenting all the steps which are required for setting up the Netlify CMS for managing your static website.(Note- If this is the first time you are using Netlify then I would recommend first getting yourself familiar with Netlify).

Here is the step wise breakdown of the Netlify CMS setup -

1. Why you should use Netlify CMS
2. Getting Started-How to setup Netlify CMS on Localhost as well on Netlify.com
3. Accessing Netlify CMS- How to access Netlify CMS via /admin url
4. Backend and Authentication
5. Conclusion

1. Why you should use Netlify CMS

First and foremost Netlify CMS is open source and free to use. There is no hidden cost involved. If you are managing your static site sometimes then you must be familiar with Git, Gitlab, and Bitbucket code repository in which you can store your static site.

Netlify CMS can be integrated with Git workflow, and it has perfect integration with all popular code repositories.

1. Easy Setup- There are only two files(index.html, config.yml) that you need for putting up your own NetlifyCMS. Although content inside the index.html is fetched from CDN, so all the code of NetlifyCMS is being loaded at browser runtime.
2. Fast- Because of the very light setup the performance of the NetlifyCMS is outstanding and you will never feel it is slow in response. Although while using WordPress I had some occasions where the javascript of WordPress CMS hang and I need to kill the browser to reload everything.
3. Works with all static site generators- The Netlify CMS works with all the static site generators which makes it more generic and platform-independent. You can choose any of the static site generators out of - Jekyll, GitBook, Hugo, Gatsby, Nuxt 2, Gridsome, Zola, Sapper Next, Nuxt 3 Hexo, Middleman, Jigsaw, Spike, Wyam, Pelican, VuePress, Elmstatic, 11ty, preact-cli, Docusaurus
4. Authentication and Authorization- If you have CMS for managing the content on your website then you must secure the CMS login and the good thing about Netlify CMS is you can integrate the authentication with GitHub, GitLab, BitBucket.
5. Custom Plugins- Apart from the default features if you feel there is a need for a custom feature then you can develop custom plugins for your need.

Here is the screenshot of the Netlify CMS dashboard -

2. How to setup Netlify CMS on Localhost as well on Netlify.com

Netlify CMS can be installed on the local machine as well as you can set it up on your website hosted on Netlify.com. But let's start by setting up Netlify CMS on localhost -

2.1 Netlify CMS installation on Localhost

(*Note - I am using Hugo static site generator for my website but the following steps should be applicable for other static site generators also)

Before you start setting up Netlify CMS on localhost you must have your static website up and running with any of the static site generators. Here is a guide on how to set up your static website with Hugo.

1. Files needed for Netlify CMS setup-

The Netlify CMS setup is very simple, and you only need two files for the complete setup -

1. config.yml
2. index.html

You have to place both the files inside admin directory but admin directory has to be placed correctly. Refer to the following table for placing the admin directory -

Here are my index.html, config.toml files present inside the admin directory -

2. Setting up index.html -

index.html - This is an entry point for accessing the Netlify CMS. You can access the admin interface with URL https://yourwebsite.com/admin.

In the index.html you will find the Javascript code maintained by Netlify Open-source community and this javascript code will be responsible for generating the UI on your website.

Here is the HTML code of index.html -

 1 <!doctype html>
 2<html>
 3<head>
 4   <meta charset="utf-8" />
 5   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 6   <title>Content Manager</title>
 7</head>
 8<body>
 9<!-- Include the script that builds the page and powers Netlify CMS -->
10<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
11</body>
12</html>

The Netlify javascript is delivered via CDN(Content Delivery Network) known as unpkg, so you do not need to store the complete javascript locally onto your hosting server.

(Note - I preferred to use the manual way of adding the HTML code inside index.html rather than using npm package manager)

npm package manager

If you use npm then you can import the complete Netlify CMS javascript using the following npm install command -

1npm install netlify-cms-app --save 

Then import the same inside your project -

1import CMS from 'netlify-cms-app'
2// Initialize the CMS object
3CMS.init()
4// Now the registry is available via the CMS object.
5CMS.registerPreviewTemplate('my-template', MyTemplate) 

3. Setting up configuration inside config.toml -

config.toml will contain the configuration for managing -

1. Authentication (GitHub, GitLab, BitBucket)
2. Directory setting for storing images and media
3. Collections for setting the template for writing a blog post

1. Authentication - The first important configuration you need to put inside the config.toml is for authentication because you can not allow a random person to access your Netlify CMS.

In my setup, I used GitHub as my preferred way of authentication. You need to follow lines for GitHub authentication -

1backend:
2  name: github
3  repo: rahulwagh/jhooq # Path to your GitHub repository

Make sure you have your Static site code repository present on your GitHub account otherwise the authentication will not work.

Here is a screenshot of my Netlify Authentication page -

2. Directory setting for storing images and media- The second configuration you need is for storing the media, and images. You have let Netlify CMS know at which location your will be uploading the images or any other media.

Here are the settings for my setup -

1media_folder: "static/images/uploads" # Media files will be stored in the repo under static/images/uploads
2public_folder: "/images/uploads" # The src attribute for uploaded media will begin with /images/uploads

Since I am using Hugo static site generator, so I have to upload all the media under static directory that is why i have chosen the directory path to be static/images/uploads

3. Collections- Collections configuration allows you to set up different layouts for your blog post .i.e. - title, date, thumbnail, rating, location of blog post inside your git repo, etc.

Here is my configuration for collections -

 1collections:
 2  - name: "blog" # Used in routes, e.g., /admin/collections/blog
 3    label: "Blog" # Used in the UI
 4    folder: "_posts" # The path to the folder where the documents are stored
 5    create: true # Allow users to create new documents in this collection
 6    slug: "{{year}}-{{month}}-{{day}}-{{slug}}" # Filename template, e.g., YYYY-MM-DD-title.md
 7    fields: # The fields for each document, usually in front matter
 8      - {label: "Layout", name: "layout", widget: "hidden", default: "blog"}
 9      - {label: "Title", name: "title", widget: "string"}
10      - {label: "Publish Date", name: "date", widget: "datetime"}
11      - {label: "Featured Image", name: "thumbnail", widget: "image"}
12      - {label: "Body", name: "body", widget: "markdown"} 

Here is the breakdown of each configuration line under collections -

1. Name- What is the name of your collections which you want to put. In my case, I have assigned the name blog
2. Label - It is the label name that will be visible inside your admin page of Netlify CMS after login.

   

3. folder - The directory inside your GitHub repo where the blog post will be saved in the form of .md file.
4. true - It allows users to create new documents
5. slug - This is a file name format of your markdown file. I generally write markdown file in the format .i.e. - 2022-06-16-netlify-cms.md

   

6. fields - Fields are usually the front matter which needed for composing the blog post. Front matter generally contains titles, date, layout, excerpt, featured image, tags, category etc.

If you have configured the index.html, configuration.toml with the above settings then you should be able to access your Netlify CMS locally without Netlify.

2.2 Netlify CMS setup on Netlify

In the previous step, we have seen how to configure Netlify CMS without Netlify for your local development. But if you are already hosting your website on Netlify then it is always recommended to use Netlify documentation for setting up Netlify CMS.

Here are detailed instructions by Netlify starting from choosing the template.

3. Accessing Netlify CMS - How to access Netlify CMS via /admin url

If you have used any CMS before then you will find Netlify CMS to be very easy to use with a very simplistic UI(user interface).

Here is how my default dashboard of Netlify CMS looks like /admin

3.1 Collections - Left Navigation panel

After the login on Netlify CMS on the left-hand side, you will notice a collections panels which store the templates which you have created for writing the blog post.

3.2 New Blog - How to write a new Blog post?

On the admin panel, you will notice New Blog button after clicking on it, you will be redirected to a new page where you can start writing your blog post.

Here is the Blog Post writing area where you can compose the post. All the options on this page is coming from the Collections configuration which you have defined

After composing your blog post you can click on either Publish now, Publish and Create new, Publish and duplicate

All the newly created blogs will appear on the default admin dashboard of the page -

4. Backend and Authentication

In the previous steps, we have seen how to set up your Netlify CMS with GitHub backend authentication for local Netlify CMS setup. But apart from GitHub Netlify CMS offers various authentication integrations with the various platform such as - Azure, Bitbucket, GitLab

Here are some of the configurations which you can modify as per your repository settings -

4.1 Azure

Make sure the user has write permission for the repository

1backend:
2   name: azure
3   repo: organization/project/repo # replace with actual path
4   tenant_id: tenantId # replace with your tenantId
5   app_id: appId # replace with your appId

4.2 BitBucket

Make sure the user has write permission for the repository

1backend:
2   name: bitbucket
3   repo: owner-name/repo-name # Path to your Bitbucket repository

4.3 GitLab

Make sure the user has write permission for the repository

1backend:
2  name: gitlab
3  repo: owner-name/repo-name # Path to your GitLab repository

5. Conclusion

Summing up the post - With Netlify CMS putting up content on the website becomes really easy because you have the CMS in place. Also, you do not have to remember the Markdown syntax if you are not a very big fan of writing the blog post in the Markdown format.

Although this blog post is all about setting up the Netlify CMS with Hugo static site generator the same steps can be followed for any static site generator framework. I hope this article helps you to set up your Netlify CMS to make your workflow a bit easy.

Read More -

1. Why I dumped Wordpress and switched to Hugo static site generator
2. My experience of hosting static website hosting on Siteground
3. Hosting a website on Netlify
4. How to set up Netlify CMS for static website?
5. Fixing the Hugo Theme on Netlify Hosting?
6. /netlify-deploy-site-with-ftp-manually?