Hugo – Quest for The One Blog, Part 9

This one’s about Hugo, the static site generator. I’ve seen references to it all over the place during this ongoing research project. (Also Jekyll.) It seems to be popular among programmers, for reasons that should become obvious as I describe it below.

A static site generator is a tool that takes a series of input files, usually plain text files, and turns them into a big directory of HTML, CSS, and Javascript files. Those files can be uploaded directly to a web server which of course becomes a web site. It works a lot like a compiler, which turns source code into binaries. Thus the appeal to programmers.

I don’t know why “static site generators” are cool now, but they’re pretty trendy and there’s a whole ecosystem around them. Maybe it’s a backlash against the WordPress Industrial Complex, the massive server-side steampunk engines spraying diesel fumes and black smoke into the air, bringing servers to their knees, using precious energy the planet doesn’t have, just so you can type a blog post into a WYSIWIG editor. Which is sort of strange since blog engines like WordPress were a response to building static web sites by hand, so in a way, Hugo is a regression in technology.

But if you just want to throw a couple of pages up on the web as a resume or portfolio, a static site is a great choice. When you don’t have to worry about any sort of server-side scripting engine or authentication or database, your security concerns plummet, and your web hosting requirements shrink to almost nothing (and become cheaper). “Fast and secure” seem to be the top promotional features of these static site generators, along with “not having to know HTML.” (I’m dubious about that last one. It helps a lot.) There are even a few options for hosting static sites, complete with SSL and custom domain support, completely free (eg. GitHub Pages and Render).

The drawbacks of a static site are numerous. Comments? Probably not going to happen. Like Buttons? Unlikely. Accounts? No way. Private web pages for your inner circle? Nope. Anything that involves taking input from a user and storing it somewhere is probably not going to happen, at least not without getting third-party services involved.

Video Tutorials

One of the first things I noticed about Hugo is that the official documentation is sparse at best, and missing or even obsolete at worst.

This is apparently a “feature,” because Hugo is developed so rapidly that they spend all of their time improving it instead of documenting it, which is why it’s the best, or so agile evangelists would have us believe. As of this writing, there have been five released versions of Hugo in the last month.

I turned to YouTube to see if I could find some tutorials. I don’t normally do that, but I was having a bad back day and it was easier to lie down and watch videos. Most of my searches came up with the same results.

Chris Stayte. This was the best one-video tutorial introducing Hugo that I found, but it cracked me up how amazed he sounded about relatively simple computer concepts. Look at that! The page changes when you change the source files! It’s amazing! Anyway, it doesn’t go much further than the web tutorials, but it was a help to see it in action.

Mike Dane. He’s made a long series of short tutorial videos which go into a lot of detail (well, as much detail as you can go in 8-10 minutes), so you can pick up some information here and there. It’s a good effort, but it’s definitely made to appeal to the younger crowd. It’s helpful, if you can tolerate the instructor looking about 17 years old.

But most of my knowledge came from reading web sites and tinkering with it. I started at the Hugo documentation, of course. I also found some useful information perusing some loosely-organized tutorials on Kodify.

The key to learning Hugo is to absorb a lot of different sources, and try to coalesce the information that stays constant. Eventually you start to get an idea of how Hugo actually works, as opposed to just copy-and-paste things into the system, if you know what I mean. It’s easier for me to understand and learn and use this kind of stuff when I know how the underlying engine works.

The first thing that’s important to know is what Hugo does and what it doesn’t do. Saying “just use Hugo to build your web site” is roughly like saying “just use a C compiler to build your application.” The capabilities of this thing are boundless, because it doesn’t enforce very many rules, and everything it does is governed by modifiable configuration files and themes. Hugo is little more than a tool that mass converts Markdown text files to HTML, using a set of templates (aka. “theme”) as a guide for the conversions. It’s the Wild West. Anything is possible, and anything can go wrong at any time.

Tutorials for using Hugo tend to be very brief. “Just put your markdown files here and run the hugo executable, then copy the output to your web host.” That’s basically how most tutorials describe the process. The part where you tinker with the templates and configuration files and open 20 Google tabs and scratch your head for hours on end is left out.

It’s The Journey

I started my foray into Hugo on Sunday. I set out to install it on Windows. I expected it to be a hassle, since it’s usually referenced as a Linux or even MacOS tool. It turned out to be very simple. The Hugo quick start mentions using a “package installer” but all you have to do is download the Windows distribution, and unzip the archive somewhere. It contains exactly three files: A README, a LICENSE, and hugo.exe. You’ll need to add it to your command path.

After that we turn to the command line. To create a new, empty site, we go to an empty directory and run the hugo executable:

The site will be created in a directory named with your site name at the current location. All of the files necessary to build a site are created for you, except for the “theme,” which, it turns out, is the most important part, and the most difficult to get working. If you try to visit your brand new, empty static site before installing a theme, it looks like a blank white page. You can add all the Markdown content you want but without a theme, there are no instructions for turning it into web pages.

The theme is the guide by which plain text files are converted into HTML. It’s roughly analogous to WordPress themes, in that they control the look of the web site, but they’re a bit more complicated than that because they also govern the structure of your content directory. There are a variety of sample themes available, but not only do they visually look different from one another, they also tend to function differently as well. There isn’t very much standardization, and you have to study each one to figure out how it works.

Installing a theme is not so much an installation as it is cloning the theme’s git repository to your local hard drive. If that doesn’t mean anything to you, then Hugo probably isn’t for you. It’s easy once you have the prerequisite software installed and know how to do it, but it’s not very intuitive unless you’re a programmer. Perhaps now you can see why Hugo might appeal to programmers.

The first three themes I tried to install didn’t work. I still don’t know why. I received a wide variety of errors on the command line that didn’t make sense, and sometimes no errors, but also no web pages. I recorded everything I did in a screencast video so someday I can go back and study what went wrong. But I gave up after the third try. Nothing made any sense. I ended my first day with Hugo in shame and disgrace.

Maybe Next Time

I think I was trying for too much, too soon, without fundamentally understanding how the system works. I tried to drop in the Endgame Viable posts that I exported last time, and I was copying files all over the place willy-nilly without really knowing what I was doing. The next time I work on this, I’m going to create an empty site and an empty theme from scratch and add content, one file at a time, so I can figure out precisely how it all works. (The hugo executable has an option to create a theme as well.)

One very cool feature of Hugo that deserves mention is that it includes a simple web server. You simply type “hugo server” and it spins up a server in memory that serves up your site-in-progress. You can even modify the source files and it will detect the changes and rebuild the web site in real-time. It makes development very fast and easy. I mean, for a static site generator. It’s a whole lot better than trying to setup IIS.

I should add allegedly to the above paragraph, because I haven’t yet seen it do very much with my own eyes, due to the problems I had installing themes. Most of what I saw were blank pages or randomly formatted pages with broken links.

I’m really curious to see what I can do with this thing. It appears to have the infinite flexibility that I would require for building my archive site. We’ll see. There’s still a lot of work ahead of me for this theoretical blog migration. I had set a tentative personal goal of trying to be ready for a “re-launch” around the end of the year, and that doesn’t seem all that far away.

This post is part of The Quest for The One Blog.

Next: Part 10.