Deploying A Hugo Site & Netlify CMS

I’m learning a bit more about Hugo. Today I tried to deploy the test site to Netlify so that I can install the CMS. There were several problems…this is what I learned in the process.

Hugo Themes

One thing that’s not great is how specific a site will be to its theme…or rather how specific themes are: it makes changing themes not so simple because you have to edit so many settings and files to move from one theme to the other.

Themes As Submodules

So what I did last time was totally wrong: if you make and commit changes to the theme (which is a git submodule), it breaks the deploy process. This is because adding a submodule through git from a remote repository actually adds a specific commit, and Netlify looks for that commit’s SHA during deployment. But since it was looking to match the latest commit (the local one I made) with the origin repo (remote), it doesn’t find a match and breaks.

To solve this I did git reset --hard <remote SHA> and deleted the changes I made to the theme. There is a way to customize themes which I will have to look into more deeply once I get through this test deployment.

Deploying to Netlify

One thing that’s important for Netlify to deploy correctly is having all of the basic structure folders in the GitHub repo it’s deploying from. But in a demo project, at least initially, some folders will be empty initially. Problem: Github doesn’t accept empty folders being pushed to the remote repository! In my case I had to add dummy files to make sure these folders remain in place, for the benefit of Netlify (thanks to this post for explaining):

$ cd main/project/folder
$ touch layouts/.gitkeep
$ touch data/.gitkeep

Another strange thing was that Netlify, by default, runs a really old version of Hugo during the build process. That resulted in a failed deployment:

ERROR: 2018/03/13 00:51:25 hugo.go:421: Current theme does not support Hugo version 0.17.
Minimum version required is 0.25

To fix this I found the Hugo version I’m running locally:

$ hugo version
Hugo Static Site Generator v0.37.1 darwin/amd64 BuildDate:

Then tell Netlify to use this version too:

From the Project Overview, open Site Settings
Open Build & deploy
Scroll down to Build environment variables and click Edit variables/New variable
Create a new variable with the key HUGO_VERSION and value 0.37
Save

Next time around everything went to plan and the site deployed. Woop woop!

Adding Netlify CMS

THIS IS AN AWESOME TOOL!! Not much to say about setup…the docs were thorough and I didn’t run into any issues. It works by having you add an admin page to the static site with their JavaScript embedded. As the site owner I can grant access to anyone to be able to make edits to the content, and they authenticate using email, Google auth, or GitHub, Bitbucket, etc. Once logged in, there’s a WYSIWYG editor, or you can just write Markdown. Then when you publish, it adds the new content as a commit to the repo, which automatically triggers a new deploy in Netlify. GENIUS!

Oh and it’s free!

Other Stuff

I watched a few videos in the React section of the course I was doing but I’m going to tap the breaks on learning React for now. I’ve got this other project to work on, and I think I need to spend some more time in vanilla JS before jumping in. So will get back to that later.

Up Next

Play around with the publish mode in the CMS…it allows you to draft/edit/publish posts instead of automatically publishing as step 1. Then once I’ve got a handle on all of this, will start building out the client site.