For this relaunch of the blog, I started using Hugo as my static site generator. Hugo is written in Go, and it is unlike much of its competition in many ways.
The biggest difference is that Hugo comes in the form of a single executable. It has no dependencies, and it does not require you to install any sort of programming language. The implications of this one difference are staggering. In addition to making it easier to install and get started, as well as easer to update and maintain, Hugo’s single-executable means that it is trivial to place the executable file into your git repository. Doing so means that as long as you can clone your Git repository, you can reproduce your entire build environment on any computer. This is an extremely big deal for me. One of the minor reasons why I stopped working on the old iteration of the blog was that the build environment was set up on my oldest, slowest laptop. I didn’t like getting on it all that much, and I did not want to spend a ton of time replicating the environment on another box. With Hugo this is no longer an issue.
Another consequence of Hugo’s design is that it changes the way it interacts with external tools. By default, it tries to provide as many features out-of-the-box as it possibly can, so much so that for most use cases, you likely will not need to seek out external functionality. As a result of this, it doesn’t have that many hooks into, or awareness of external tools. Even when it does, it tends to be simple and deliberate. For example, Hugo is able to provide syntax highlighting for code blocks out of the box. It also allows you to use the Pygments tool to do it instead, but it is up to you to install Pygments and make sure that the executable is on your system path. The documentation is very clear in telling you a) that you have to do this, and b) how to do it, so there is no guesswork involved.
In most cases, however, you will not integrate external tools into Hugo, but instead wrap them around Hugo. That is to say, if you wished to transpile ES6 code or convert SASS into CSS, you would place these files outside of your Hugo project’s directory, run your transpiling/conversion/whatever, and stuff the resulting output into the Hugo folder. Basically, your site gets to benefit from these technologies without having to directly involve Hugo in their use.
This is a subtle but important difference. When one service has to call out to another, it involves executing the external command, determining the result of the execution, and finding a way to pull in the output to make use of it. There are lots of different ways to do these tasks, and lots of different ways of handling both success and failure. Any time you have to do it, it becomes a potential pain point.
But, if you can execute these external different services independent of one another, maintenance becomes much easier. If a service or process is broken, you can quickly tell, and then focus on just that service until you find a solution. The fewer parts are moving at once, the easier a mechanism tends to be. Hugo’s approach is a smart - and I assume intentional - display of the concept of Separation of Concerns.
I also like that Hugo doesn’t ask you to learn much about the Go language. It isn’t used in configuration files, and its templating language requires you to know a few functions for manipulating Strings and Dates, but that’s it. It feels like the authors used Go to write the tool because it is fast, and because they liked the language, but they didn’t expect the user to have to like it themselves. This goes against the grain of most static site generators, which embrace their target programming language, but I find Hugo’s approach to be much less stressful, and much more focused on the process of creating content, not code.
One thing I do not like about Hugo is that it does still encourage the use of its templating language. Like with the ERB stuff I used in Middleman, using Hugo’s templating language in your Markdown files destroys their portability. Thankfully you can choose to keep the templating stuff out of your Markdown and relegate it to your template files, but I am aware that this does rob me of some of Hugo’s true power. That is a sacrifice I will have to make with any Static Site Generator.
Hugo uses a “convention over configuration” approach at its core. There are only two or three directories your site must have, and it will take the content in those folders and use it in a predictable way when generating the final site. I find that I can make a configuration change and easily predict how it will affect the final output.
Figuring out those conventions, however, is not easy. Hugo’s documentation is expansive but not very deep. It will tell you all the things it can do, but it doesn’t always explain all of the options and variations that are available. If what you are trying to do doesn’t match up with the examples shown in the Hugo docs, they can actually become more confusing than helpful. On a related note, the doc pages constantly refer to one another, so much so that you may have to go down a rabbit hole of related concepts just to figure out the one thing you are actually trying to do.
Like with other Static Site Generators, Hugo users and enthusiasts tend to write HOWTO articles and guides that are way more complicated than they need to be. I almost gave up on using it after examining the structure of various Hugo themes and being completely perplexed. I only ended up truly grasping the fundamentals of Hugo after reading the book Working with Static Sites, which shows how to build a simple Hugo site from scratch, sans any templates. Once I read through that, those templates became a lot less confusing, since I knew which parts were being used by Hugo, and which content was intended for external processing.
If you are interested in learning Hugo yourself, I suggest you find a similar kind of learning resource, one that wants to teach you fundamentals rather than get you ‘up and running in no time’.
The last thing I wanted to point out about Hugo is that it is fast. Really fast. “Build your site in a less than a second” fast. I never knew how important this might be to me until I saw it with my own eyes. When you can see the results of your work without having to wait, mistakes become a heck of a lot easier to fix.
All things considered, it is still too early to tell if Hugo is a long term solution, but so far it has been a wonderful experience. I have a nice simple directory structure, and I found a clean little theme with a single, easy to read CSS file. I am able to make changes and immediately see the results without getting any surprises. And since the core of the site’s structure is so clean and simple, I should be able to add more features piece by piece – and just as easily remove them if things go wrong.
I hope it works out for me.