Setting up a Website with Hugo

A brief overview of how I set up this site.

1. Install Hugo

I’m doing this on a Mac, so installing Hugo is as easy as running

1

brew install hugo

in the Terminal, assuming you already have Homebrew installed.

This gets you the extended version of Hugo, which supports Sass/SCSS. Depending on the Hugo theme you choose, this may or may not be necessary (for this theme, it’s certainly recommended).

You can also check out the official docs for installing Hugo if you’re running with a different setup.

Once you have Hugo installed, running hugo version in the Terminal should return something like:

1

hugo v0.81.0+extended darwin/amd64 BuildDate=unknown

2. Create a New Hugo Site Project

If you’re like me, you already have a “Projects” folder sitting on your Desktop where all your curious undertakings and questionable experiments alike sit pretty.

In this case, I’ll call my project directory Persite (short for “Personal Website” - it’s important to have snappy nicknames for projects so that working on them feels cool) and create it inside my Projects folder:

1

hugo new site Persite

So the root folder of the Hugo project is ~/Desktop/Projects/Persite.

Inside your project root, you should see a couple of files and folders already created for you (e.g. config.toml, content/, themes/).

3. Choose a Hugo Theme

Time to go shopping. You can check out the complete list of themes published on the official Hugo site and pick something you like there, or use the same thing I did. Be warned, this theme no longer seems to be under active development, and in fact appears to have been co-opted by another developer.

To install the theme, you just need to get the folder of the theme’s data in your own themes folder. You have a few options for doing this:

1. Download the latest .zip of the theme and extract it to the themes folder.
2. Perform a git clone of the theme repository in the themes folder.
3. git init your own project root, then git submodule add <theme_repo_link> themes/<theme_name> .

I made my own git fork of the theme repo, then went with option 3 using that fork, since I planned on making some code changes to the theme and wanted to keep those distinct from the personal website project itself.

Each theme will have different configurations you need to set up - follow the instructions they’ve laid out in their setup docs before proceeding. In my case, there were a bunch of lines to add to the config.toml file, values to be changed where necessary.

4. Create Your First Post

Whether the theme’s setup instructions had you just copy over the example data as a placeholder or not, it stands to reason that you’d want to make some original content sooner or later. To create new stuff in your content directory, you can use the hugo new command.

For this theme, posts are stored under the aptly named posts folder, and I’d like to write my first post in a file called first-post.md , so the command is:

1

hugo new posts/first-post.md

And now I’ve got a file at ~/Desktop/Projects/Persite/content/first-post.md.

In first-post.md, you’ll see some content known as “front matter”:

1
2
3
4
5

---
title: "First Post"
date: 2021-03-16T16:57:42-07:00
draft: true
---

This defines metadata for the post, and depending on your theme, you may be able to add more to customise your content further. For example, here’s the front matter for my first post:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
title: First Post
subtitle: or, How I Finally Got Around to Setting Up a Website
date: 2021-02-28T14:35:08-08:00
tags:
  - hugo
categories:
  - Dev
featuredImage: /img/modified_hugo_logo.png
linkToMarkdown: true
---

The rest of your content can go under the front matter.
Check out the Basic Syntax for Markdown page if you need some help writing in Markdown.

5. Test Your Server

To start up the Hugo server, you can simply run:

1

hugo serve

Assuming everything is configured and set up correctly, you should now be able to check out your site at localhost:1313.
Even better, every time you make a change, your site should reload automatically!

6. Deploy Your Site

If you haven’t already initialized your Git repo for this project and pushed it to GitHub, now would be the time.

Head on over to Netlify and register an account. You can also use your GitHub account to sign up.

Follow Hugo’s instructions at their Host on Netlify post to set up your site with Continuous Deployment - this makes it so that every time you make a push to the deployment branch, your site gets updated automatically. Convenient!

7. Extras

Custom Domain & SSL/TLS

What’s the point of setting up your own website, and then having to share a link that looks like https://clever-kilby-51074d.netlify.app/? Or even worse, having a sweet domain name that starts with http://? Certificates from Let’s Encrypt are free, there’s no excuse.

You can buy a domain through Netlify, which I hear is a pretty straightforward process that comes with the SSL/TLS setup more or less automated for you.

Alternatively, buy your domain through another service like Namecheap or Google Domains, then go through a slightly more complicated process with Netlify involving configuring DNS servers and waiting around for a bit (it’s not that bad). You can check out their docs on custom domains to get an overview.

Netlify CMS

If you want to add a Content Management System (CMS) to your project so that you can create posts, upload images, etc via the browser, you can check out Netlify CMS’ setup guide for Hugo.

Zapier

Another cool thing about Hugo is that you can future-date your posts, and they will render only when the specified time comes. Of course, you’d have to trigger a redeploy of your site to have that work.

To automate redeploys, you can grab a webhook endpoint from Netlify, then use Zapier to trigger a POST request on a regular schedule.

More Customisation

Once you’ve figured out your favicons and logos and whatnot, you might really want to get into customising the theme for yourself (e.g. changing theme CSS, editing templates, maybe even actually writing some Go). To that end, I’d recommend starting by reading up on Hugo’s Content Management and Templates to get an idea of how the framework operates, then moving on to implementing more complicated changes.