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.