Hugo is a fantastic static site generator and if you’re looking to move away from Jekyll, Hugo is an excelent choice. I’d say that the initial setup is much easier than Jekyll’s and I’m nicely surprised how quick I was able to put this site together plus Hugo’s blazing fast thanks to the fact it’s built in in Go.

I tried Gatsby as well and maybe I chose the wrong theme to start with but both Jekyll and Gatbsy came short when it came to Hugo. I was not fan of all dependencies I needed for Jekyll and the plugin system in Gatsby.

The theme on this blog is hugo-paper and I will show you how I set this up and host on Netlify.

Install hugo and create new project

Installing Hugo is as simple as this (for MacOS users, otherwise look up Hugo website for more instructions)

brew install hugo

After installing Hugo, simply run an another command which creates a new folder and adds project biolerplate.

hugo new site <siteName>

Install a theme

The next step is to initialize git and install the theme you want to use. There is an extensive list of themes for you to use. As mentioned above I am using hugo-paper (github repo) which you can install like this:

cd <siteName>
git init
cd themes
git submodule add https://github.com/nanxiaobei/hugo-paper.git 

All that’s left now is to add the theme name to config.toml file and create new content which you can do by adding .md files to content/posts folder and run hugo serve from root directory to serve it locally.

Deploy with netlify

I am a huge fan of Netlify (this very site is hosted there) so I will recommend you to deploy your newly made website there. They offer continuous delivery with Github so every time you push your changes to Github, the website is rebuild and deployed and you don’t need to do anything.

Easiest way to set up the commands is with netlify.toml file, simply create the file at the root.

[build]
publish = "public"
command = "hugo --minify"

[context.production.environment]
HUGO_VERSION = "0.47"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"

[context.split1]
command = "hugo --enableGitInfo"

[context.split1.environment]
HUGO_VERSION = "0.47"
HUGO_ENV = "production"

[context.deploy-preview]
command = "hugo --buildFuture -b $DEPLOY_PRIME_URL"

[context.deploy-preview.environment]
HUGO_VERSION = "0.47"

[context.branch-deploy]
command = "hugo -b $DEPLOY_PRIME_URL"

[context.branch-deploy.environment]
HUGO_VERSION = "0.47"

[context.next.environment]
HUGO_ENABLEGITINFO = "true"

On Netlify website, choose option to create New site from Git , choose your project and deploy. In theory, it should be as easy as that πŸ™Œ

Possible roadblocks

Submodules error during the build

Ehm, if you didn’t followed this tutorial or tutorial on offical Hugo website and you used git clone for your theme instead of git submodule add you might encounter a failed deploy. This is an easy fix, add your theme to your project with submodules, not cloning (check the process above).

Editing theme

I have seen few articles about Hugo saying you can’t edit the theme you added. It’s because of the way submodules work, you reference the original theme from the original repo. I’ve seen suggestions that you fork the theme, edit it and then reference it, however, there are some disadvantages to this approach. I would say the biggest one is that you won’t get a newer versions of the theme, which, in theory is not that big of a deal but still. There might be some useful updates that you will miss out if you fork the repo.

There is a neater way, I believe, as Hugo can support several themes at once. You can edit them in config.toml file,

theme = ["hugo-paper-edited", "hugo-paper"]

There is a theme inheritance algorithm that looks at the array above and create a new theme with theme on the left being loaded first and being the most important and merging the themes on the right into it. Hence, I copied the files I wanted to amend into a new folder called hugo-paper-amended and made all the changes to the theme there. The rest of the theme is then loaded from hugo-paper theme.

Styles didn’t load

You might get an error in the console saying that website wasn’t served though secure https. That might be to a possible wrong baseURL value set in config.toml. If deployed already, Netlify supports https, so add your URL to the config and that will solve the problem!

further reading