Generating a Static Blog With Hugo

Well, here’s part 2 of making this blog! As noted at the end of Part 1, I decided to use Hugo along with the Cupper theme. As of writing, I’m still getting things off the ground, but I’m thinking that I’ll deploy it with Netlify.

Hugo Setup

Hugo was fairly straightforward to set up, but I did run into a few confusing things.

Installation

I tried to begin with the quickstart guide, but it only had installation instructions for Mac users. The installation page wasn’t much more helpful since I was expecting to see a way to obtain it from a distro package repo and didn’t want to install brew for it.

Luckily, I found that Hugo is available in the Arch community package repo. So, I simply installed it with pacman:

pacman -S hugo

I also saw that it was available in Ubuntu package repos, but since I was on Ubuntu LTS it was a bit outdated (from 2020), so I decided to just grab it from within Arch.

Creating an app

Creating an app is easy and similar to popular web frameworks like Rails:

hugo new site blog

You can replace “blog” with whatever you want to name your project. Next you’ll want to go into your project folder and initialize a git repo:

cd blog
git init

Initializing git makes the next step possible.

Adding a theme

Take a look at the themes available for Hugo and choose one you’d like to use. I went with the Cupper theme. I really like it’s minimalism and layout. It’s apparently a port of a documentation project by the same name, which hasn’t been updated for about 4 years.

Clicking the theme on the aforementioned theme page should take you to a page with some instructions on installing the theme. This can be done manually or with git. I chose the git method to install Cupper:

git submodule add https://github.com/zwbetz-gh/cupper-hugo-theme.git themes/cupper-hugo-theme

This clones the git repo for the theme into the themes/ directory of your project. To make your project use the theme, you can add it (by the name of its directory) to your config.toml:

echo theme = \"cupper-hugo-theme\" >> config.toml

However, themes often provide more configuration options in their example config. So as suggested by Cupper’s documentation, I copied the example config.yaml, and removed the default config.toml:

cp themes/cupper-hugo-theme/exampleSite/config.yaml .
rm config.toml

Adding a post

This is where I ran into my first hiccup. According to the quickstart guide, to make a new post, you can run:

hugo new posts/my-first-post.md

I ran the command, but with making-this-blog.md as the post name. Edit the post with your favorite markdown editor, and change draft: true to draft: false if you want it to be published. I copied in the text I had writted in Notepad earlier and saved it. Yay, my first post!

To make sure everything looks right and see your first post, you can now run the Hugo server:

hugo server

I loaded up the default URI in my browser at localhost:1313. Cool, the blog is there! But when I clicked the “Blog” nav item, I was presented with a 404 error. I thought I must’ve done something wrong, or misunderstood how posts were generated. The server log showed that it had picked up my new post.. so why couldn’t I find it?

I copied the posts from the theme’s example site, and they worked fine. After a bit more troubleshooting and creating a new site, I realized the error: the quickstart guide says to use hugo new posts, but the theme is using the post directory! My post had ended up in the posts directory. All I had to do was move my post to the directory expected by the theme, and it worked just fine.

From now on I’ll need to make new pages in the correct directory:

hugo new post/new-post.md

The official Hugo docs make it clear that they expect the plural posts directory, so I’m not sure why the theme differs.

Next steps

Now that I’ve got my basic blog set up, I need to:

1. Write more!
2. Upload to Github or Gitlab
3. Publish on Netlify
4. Point my domain to Netlify

I’ll be writing more about this journey as I continue. Thanks for coming along.