I’ve moved this blog from Gatsby.js to Hugo. My build times have gone down from more than 7 minutes to a few seconds!

The slow build times with Gatsby have been an ongoing concern for me. I’ve slowly been creeping towards Netlify’s free 300-minutes-build-time cap.

Hugo runs a magnitude faster, and it integrates well with Netlify.

Hugo is a static site generator built with Golang. The project’s selling points are incredible speed, ease of use, and the ability to configure tons of settings.

You don’t need to know Golang to make it work.

Here’s a practical guide on creating a website with Hugo and deploying it to Netlify.

How To Move To Hugo

Create Hugo Site

Install Hugo

Prerequisites: Git

The Installation Guide offers a good overview.

I’ll provide some examples, but if you don’t find your operating system here, you should check out the official instructions.

MacOS
brew install hugo
Linux
Debian/Ubuntu
sudo apt-get install hugo
Arch Linux
sudo pacman -Syu hugo

Create Hugo Project

hugo new site <project-name>

The command will create a new Hugo site. Navigate inside that directory.

Example:

hugo new site netlify-blog
cd netlify-blog

Add A Theme

Go to themes.gohugo.io and choose a theme.

You should add the theme to your site with a Git Submodule. This approach works best with Netlify.

Let’s say your project is called netlify-blog, and you want to install the Kiera theme:

cd netlify-blog

## initialize Git
git init
## add theme via submodule
git submodule add https://github.com/funkydan2/hugo-kiera.git themes/kiera

Configure Theme

Most themes offer an example configuration. Check their documentation. The configuration file is called config.toml.

Here’s an example for the Kiera theme:

pygmentsCodeFences = true

disqusShortname = "" #Disqus shortname
googleAnalytics = "" #Google Analytics ID

theme = "kiera"

[author]
    name = ""       #Author name
    github = ""     #Github username
    gitlab = ""     #Gitlab username
    linkedin = ""   #LinkedIn username
    facebook = ""   #Facebook username
    twitter = ""    #Twitter username
    instagram = ""  #Instagram username

[params]
    tagline = "the tagline for this website"
    customCSS = []  #Optional Customised CSS
    contentTypeName = "posts"

Customizations

Customize Theme

There’s one trick you can use to add some minimal customization to your theme, but still be able to update the theme via git submodules.

Create a new folder in the themes directory - for example, kiera-customized.

Let’s say you want to edit the way the theme processes your post front-matter. Each theme has a folder called archetypes, which contains a template. (See Archetypes for a detailed explanation.)

Here’s how Kiera’s template for posts looks like (themes/kiera/archetypes/posts.md):

+++
title = "{{ replace .TranslationBaseName "-" " " | title }}"
date = {{ .Date }}
draft = true
tags = []
categories = []
+++

My front-matter for Gatsby looked like this:

---
title: "Modern JavaScript"
date: "2019-11-17"
categories:
  - JavaScript
  - tutorial
---

Let’s copy that format to our customized theme folder.

cd themes/kiera-customized
touch posts.md

Edit that file:

---
title: ""
date: ""
tags:
  - ""
  - ""
---

Add the customized theme to the config.toml:

theme = ["kiera-customized", "kiera"]

Now all your previous blog posts, which use a different format for the front-matter, will still work.

URL Management

If you want to adjust how Hugo serves your URLs, you can set a permalink configuration to netlify.toml:

[permalinks]
  posts = "/:year/:month/:title/"

Check the docs for more options.

Add Content

Add Markdown posts to the content folder.

You can use the hugo command for that:

hugo new posts/my-example-post.md

The command will create a Markdown file with meta-data.

Or you can manually add a file and provide the front-matter.

Development Server

Run the development server with hugo server -D.

Netlify Configuration

You should check the guide on hosting on Netlify.

But for now, let’s create a netlify.toml file:

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

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

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

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

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

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

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

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

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

Source Control And Automatic Deploys With Git

Git

Netlify works with several Git providers like GitHub, GitLab and Bitbucket.

Choose your favorite provider and create a repository.

Here’s a guide for GitHub: Create a repo.

Commit your Hugo project and push it to the remote repository.

Example .gitignore:

resources
public
node_modules

Netlify Dashboard

Follow the steps on Host on Netlify to connect your Git repository to Netlify.

We’ve already configured the Hugo version for Netlify in the previous step.

If you’ve already setup a previous project with Netlify that you would like to replace, you can do that in your Netlify Dashboard. Go to your project, “Deploys” > “Continous Deployment”. You can change the Git repository, build command and publish directory.

The build command is hugo --gc --minify. The default build directory is public.

Netlify Pitfalls

You’ll most likely need the extended version of Hugo. That’s the version that comes with most installations. And it’s also the version that works with SASS.

Go to your Netlify dashboard and open your project. Go to “Deploy Settings” > “Build image selection”.

Make sure you choose Ubuntu Xenial 16.04 if it isn’t already selected.

Further Reading