Getting started with Hugo, GitHub and Netlify

Why use Hugo? #

In this post I want to explain how I setted up my static website using Hugo, GitHub and Netlify. I decided to use these tools because:

1. Easy to use. To write contents you will use Markdown;
2. Keep focus on writing. All your website contents will be built in Hugo;
3. Fast build times. By connecting Netlify with your GitHub repo you have a continuous deployment, which makes automatic the content publishing.

Let’s get started. As a host operating system, I will be using Mint 20.03.

Step 0: Install Hugo ¹ #

From the official Hugo realeases page download a .deb package of the latest version and install it with dpkg command:

$ sudo dpkg -i hugo_<latest_version>_Linux-64bit.deb

Step 1: Start with Hugo #

Create a new website #

Use the hugo new site command:

$ hugo new site test-site

In this way the new site has a structure, but it has no content.

Add a theme #

From official Hugo Themes choose a theme and then add the theme repository as a Git submodule as follows:

$ git submodule add -b stable https://github.com/jpanther/congo.git themes/congo

Then modify config.toml by specifying the theme to use:

1
2
3
4

baseURL = "/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "congo"

Pay attention to this step, otherwise there could be some problems. ²

To check our site we can start the built-in server to build and serve the site.
Run the hugo server command from the site’s root directory:

$ hugo server

and go to http://localhost:1313/ in your browser.

Write a post #

Run the hugo new command:

$ hugo new post/new-post.md

In this way Hugo creates a new file new-post.md into content/post. It should looks like:

---
title: "New Post"
date: 2022-05-02T00:05:45+02:00
draft: true
---

as the default.md in /archetypes folder.
The new file has automatically setted the flag draft: true. With this flag you can control the visibility of the file.

Running locally hugo server we consider only the visible contents (i.e. the posts with draft: false flag), while hugo server -D allows us to consider all the contents (also the ones with draft: true flag).

Generate static output for publishing #

One way to publish our website is:

$ hugo -D

In this way Hugo generates your static HTML pages into the ./public. Then we can copy the content of the folder to some server by yourself.

Anyway it’s more convenient to use Netlify for this step. Before to pass to Netlify we want to setup a new repository on Github.

Step 2: Taking track with Git #

Create a local repo #

To create a local repository:

$ git init
$ git add .
$ git commit -m 'start my website'

Then we have to setup a remote repository on GitHub.

Sync your changes to a remote GitHub repository #

Since it’s not necessary to track also the generated HTML in /public, so we specify it in .gitignore.

$ git remote add origin https://github.com/<username>/<GitHub_repository_name>.git
$ echo 'public/' >> .gitignore
$ git branch -M main
$ git add .
$ git commit -m 'after the first post'
$ git push -u origin main

Now we pass to set up Netlify.

Step 3: Setting up Netlify #

First sign up to Netlify. Click on New site from Git button and then it will open a page titled “Create a new site”.

The procedure is divided in three steps:

1. “Connect to Git provider”:
   Click on GitHub button to authorize Netlify to access your repositories, where your site’s source code is hosted.

2. “Pick a repository”:
   Choose the repository where you store your website content (i.e the one you have created in the previous step.)

3. “Build options, and deploy!”.
   Some deployment configurations as:

   • Owner (the owner of the website)
   • Branch deploy (which branch of the GitHub repo to deploy)
   • build command (which command to use to build the site)
   • publish directory (the directory to deploy from, public is where Hugo generates the output by default).

Then click on the Deploy site and it will be presented the site overview.

In the Change site name pop-up window, set the new site name and save it.

Troubleshooting #

The first deploy may fail. Possible reasons are:

• Specify to Netlify which Hugo version to use:
  As in this answer on stackoverflow, if you do not setup the right version of Hugo, then the default one may be different and work differently as you see in local. A smooth solution is to specify the version you use in a config file netlify.toml at the site’s root directory.
  For congo theme I use this netlify.toml, which is a little bit different.

Sources #

To start my site and so for this tutorial I followed the steps described in:

• dolugen.com
• kiroule.com

Conclusion #

Now we have built our static website! Looking at the docs of the theme we can customize our site.

Photo by Ilya Pavlov on Unsplash.