Jake LaCaze

How I made this site with Hugo and GitHub Pages

Building your own website isn’t quite as easy as 1, 2, 3. But it ain’t that much harder.

📝 NOTE: This post is now outdated, as I've moved my site back to micro.blog. But I'm leaving the post up in case it can help someone else in the future.

This weekend I got the itch to customize my personal website again.

(Just FYI, if creating your own website sounds like a horrible idea, then check out mataroa.blog1. You get a simple, distration-free blog with email newsletters for $9 a year. But if you instead find yourself itching for more control, then keep on reading.)

I’d made plenty short-lived personal websites with GitHub Pages and Jekyll in the past. This time I wanted to try something different, so I decided to give Hugo a shot. The only previous experience I’d had with Hugo came from my micro.blog2 days. Before this weekend, I’d never built a Hugo site from scratch.

I mostly followed a tutorial I found on someone else’s blog, so this post won’t be a step-by-step repeat of that wonderful resource. In the hope of saving you time and sparing you some headache, I’ll instead focus on some issues left unmentioned in most tutorials for making your own site with Hugo and GitHub Pages.

The theme

I chose the PaperMod theme because I fell in love with a fork of the Paper theme3 on micro.blog. The theme is simple and elegant.

A few things I love about the PaperMod theme:

  • Social icons
  • Dark/light theme toggle
  • Post navigation at the bottom of each post
  • Search page included
  • Tags pages automatically generated

The tutorial

I mostly relied on a tutorial by Chris J. Hart4.

As I’ve already said, I won’t be repeating his great tutorial. But I had some problems not addressed in his tutorial, so I’ll cover those issues below in the addendums.

Addendums

Let’s take a look at some extra information I would include to any tutorial about building your own site with Hugo and GitHub Pages.

Put a CNAME file in the static folder

Updates caused my site to forget the custom domain (jakelacaze.com), so after an update, I had to re-enter my domain in the Settings panel of the repository for my site.

Screenshot of custom domain settings on GitHub
Re-entering your custom domain after every update isn't the hardest thing in the world. But it's among the most annoying things in the world.

The fix ended up being to create a CNAME file (with my custom domain as its contents) inside the static folder.

Screenshot of a CNAME file inside the static folder
A screenshot of my CNAME file inside the static folder

Putting a CNAME file in the root directory didn’t fix the issue. I can’t say why putting the CNAME in the static folder works; I can only report the facts as far as I understand them.

Fork the theme for your submodule

The tutorial–and most others like it–recommends using your desired theme as a submodule.

I instead ended up forking the theme so that I could easily edit it.

I ran into a problem when I tried to change the theme’s RSS feed to show full content rather than just a summary. I needed to change only one word, but to do so appeared to require a change from the original theme repository and developer. By forking the theme, you can make all the changes your heart desires, directly in your main branch5.

Maybe there’s a workaround if you don’t fork the theme, but I couldn’t find one. So, unless you already know the solution, I’d recommend forking the theme in case you want to change something later.

Confusion about the the config file name

The tutorial references config.toml as your config file. The convention now appears to be to use hugo.toml instead6.

You’ll have a basic hugo.toml file when you create your site. I changed mine to hugo.yaml because I was already familiar with the YAML syntax. Just something to keep in mind . . .

See my repo for more

Feel free to check out the repository for my personal site7 if you want to dig deeper into my customizations, or if you’re interested in something I forgot to mention here.

Jake LaCaze loves the way Gary Marcus rewrites his bio at the end of each blog post, and he's considering stealing that idea for himself.

  1. mataroa.blog - Tell ‘em Jake LaCaze sent you. Just be ready for them to reply Who? ↩︎

  2. micro.blog - Personal blogging that makes it easy to be social ↩︎

  3. PaperMod theme - GitHub repo | Demo ↩︎

  4. Tutorial: How to Create a Simple, Free Blog with Hugo and GitHub Pages ↩︎

  5. Fork a repo on GitHub ↩︎

  6. hugo.toml vs config.toml on GoHugo ↩︎

  7. GitHub repo for jakel1828.github.io ↩︎