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 -
- Why you should use Netlify CMS
- Getting Started-How to setup Netlify CMS on Localhost as well on Netlify.com
- Accessing Netlify CMS- How to access Netlify CMS via /admin url
- Backend and Authentication
- 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.
- 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.
- 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.
- 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
- 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.
- 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 -
- config.yml
- 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 -
Static site Generator | \admin directory location |
---|---|
Jekyll, GitBook | / (project root) |
Hugo, Gatsby, Nuxt 2, Gridsome, Zola, Sapper | /static |
Next, Nuxt 3 | /public |
Hexo, Middleman, Jigsaw | /source |
Spike | /views |
Wyam | /input |
Pelican | /content |
VuePress | /.vuepress/public |
Elmstatic | /_site |
11ty | /_site |
preact-cli | /src/static |
Docusaurus | /static |
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 -
- Authentication (GitHub, GitLab, BitBucket)
- Directory setting for storing images and media
- 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 -
- Name- What is the name of your collections which you want to put. In my case, I have assigned the name blog
- Label - It is the label name that will be visible inside your admin page of Netlify CMS after login.
Netlify labels configuration - folder - The directory inside your GitHub repo where the blog post will be saved in the form of .md file.
- true - It allows users to create new documents
- 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
Netlify CMS clus for file naming format - 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 -