The hardest part about starting a new Hugo site isn’t getting the Hugo program to run. In Windows that part’s easy. All you do is download a binary, unzip and run it.

I have been a new user of Hugo at least three times in the past few years. I’ve never stuck with it. Every time, the initial pain point is finding a theme that a) works, b) has the features I want and c) I can understand and modify where needed.

It’s not so easy. The config.toml configuration file in one theme can be wildly different from that in another. Plus, Hugo is deep and completely customizable. The documentation is extensive, but much of it starts at 80 mph while I’m back in a 15 mph zone. It’s hard to tease out how to do that one specific thing you want to do when it seems that you can do everything, all the time.

Hugo is not alone in this. The learning curve for every static-site generator I’ve tried has been steep. I figured with Hugo, there are so many people working on coding it and even more just using it, things would just work more than not.

Finding the right theme isn’t easy. There are at least a couple of hundred to choose from, all made available on GitHub by users, with the most-recently updated themes appearing at the top.

When you’ve just started using Hugo and don’t know much about its capabilities, it’s hard to pick a theme.

I start by downloading the ones that look good to see if I can get them to work.

Hugo themes can be finicky and brittle. If you don’t have your posts in the right place, if you are missing some code in the front-matter section at the top, if you either do or don’t change something in the config.toml supplied in the theme’s exampleSite directory, the whole thing can blow up.

I wanted to use Hyde Hyde, but I wanted my name to be the title of the blog, and the theme’s style and layout broke my too-long last name in half. Not that my name is all that long. I couldn’t figure out how to modify the CSS because Hyde Hyde uses SCSS, and the CSS is broken up into multiple files. There are CSS variables. While SCSS is fascinating and something I might want to explore in the (even near) future, right not it doesn’t translate to a workable site.

For my Hugo blog, here are my table stakes:

  • Pagination (Listing of entries on multiple pages)
  • Display of tags on entries and on a tag page (Hugo offers tags, but it’s surprising how many themes ignore them)
  • Somewhat modern and responsive (many are responsive, fewer are modern)
  • I can figure out how to set it up without too much breakage

I was able to find that with Pixyll, the theme you see at the time of this blog post. (I probably will continue experimenting with Hugo themes, and you might see a new one very soon. Or not.)

Right now I’m serving this site from the Raspberry Pi Zero W in my coat closet. I experimented with a dynamic blogging system on this very, very small server, and while it ran well enough, a static site is much easier both on resources and configuration. After a little bout of permissions hell and a fight for file ownership between my Linux user account and the web server user, now everything works with the standard Unix permissions (755 for directories and 644 for files).

Features of the Pixyll theme include an email form, which does work, and a search box, which should work once I set it up. At least I think it will work.