Some Thoughts About Hugo

how strange, i have all these pages full of notes and swears

Let’s get one thing straight off the top. I really like Hugo, it’s quite fun conceptually, copying things from Scrivener into a Markdown file is not terrible, and should get quite a bit easier/automatic once I can get my hands on version 3 and get things set up properly. Now that I’ve just about got my site’s template files set up properly, that’s all that I really need to do.1 Hugo lets me fiddle with basically everything, and set most things up the way I want them. I think it was also probably the easiest way for me to make this type of website. I’m planning on using it for the foreseeable future.


This whole, fairly uncomplicated site was notably more difficult to set up than I anticipated. I have a development background,2 and that helped quite a lot, and my prickly stubbornness got me the rest of the way.3 There are a few reasons for why this was difficult.

First, I’m playing with version 0.39 (currently) of an open source tool. This probably means you should take most of my following complaints with a grain of salt, although you should also remember that I’m claiming that this was the easiest tool to use that would do what I needed. That says things about my available options. The nice thing about Hugo is that you can get it as a standalone executable. I didn’t have to install a package management system, or manage dependencies, or install an entire language interpreter. I did have to install git (a command-line version control system) to make installing themes easy. I did have to deal with documentation that was pretty inadequate at times.

I left development over five years ago, so practices and tools and workflows have changed, and also now I get pretty grumpy when software assumes I’ll be some sort of developer when I use it. Hugo definitely does that. It’s really powerful, but a lot of its power comes because any theme’s template files are written in a combo of HTML and Go inclusions, with maybe some Javascript if the theme developer was feeling ambitious, and while a lot of settings could be abstracted out from the theme files to the site configuration file, they generally… aren’t. Hugo also doesn’t come with anything useful in the way of a default theme, so you end up needing to get one from the theme site, just about all of which are community provided. I think? It’s not very clear.

Which is fine, but an individual theme isn’t guaranteed to be up to date with your new version of Hugo, and you’ll probably end up wanting to change things a bit, and maybe the template files weren’t quite complete in the first place, and the next thing you know, you have a bunch of empty pages that should be holding Stuff.

Again, this is the static site generator that had the easiest entrance requirements on a Windows machine.

So I really enjoy what I can do with Hugo, and again, I intend to keep using it, but I’m not sure I’d be able to recommend it to that many people who want to set up their own site. The learning curve is waaaay steeper than the blogposts by adoring developers who used it to put up some project notes and a two-post blog about their Hugo Experience would have you believe. This is extra true for people running things on a Windows desktop.

A lot of this could be fixed with a really solid useful template that tries to abstract out a bunch of settings to the site configuration file so users don’t have to dig into the template files until they were ready, and that is also kept up-to-date. Which may already exist! But I was having a lot of trouble trying to find it. A lot of problems could also be fixed with clearer documentation for Hugo itself, particularly by describing how to put all the various templates and functions and variables together into a cohesive whole. It’s really very by-developers-for-developers currently, and I don’t think it has to be. There’s nothing about constructing a static website that demands that only professional software developers be able do it, and I’d really like to see some more widely usable options here that don’t rely on software-as-a-service or drag-and-drop hand-holding.

  1. Well, I also need to get a script or whatever sorted to SFTP the constructed site onto my webserver, but that should be pretty minor. [return]
  2. C++ embedded, nothing even remotely frontend, but I can look at unfamiliar code and not run screaming. More importantly, I know when to expect there to be code. [return]
  3. Ask my husband how often I turned down his offers to help because “I need to learn how to make this work myself, dammit.” Apparently I felt very strongly about how it was an Important Life Skill. [return]