I chose Hugo to manage this site mainly because it’s shiny and new. But there were some substantive reasons, too.

Hugo is famously fast—really fast—but that wasn’t the big draw for me. For a personal website, even one with many years’ worth of blogging accrued, Hugo’s speed just isn’t that important. Quoth the Code Barbarian:

being the fastest static site generator is like being the resturaunt with the cleanest bathroom: sure, I prefer a faster generator, but I wouldn’t pick one generator over another because one shaves off 100ms.

What attracted me more was the lack of dependencies. Hugo is just a single, pre-compiled binary. That’s one reason I didn’t go with the Ruby-based Jekyll. Despite being a Rails regular, I always get a twinge of vertigo when I have to wrestle with gems, bundler, rvm, and all that. It seems there’s always just enough time between bundler/rvm meltdowns for me to forget how it’s all supposed to work. So I never really get fluent, and never really feel confident working with those tools.

So how did getting started with Hugo go? I’m pretty happy now that I’ve got things set up as I need them. But there were some unexpected bumps in the road.

Templates

I ended up paying for snubbing my beloved Ruby. Hugo is written in the Go language, and its template engine isn’t exactly user-friendly. It’s especially unpleasant if you’re coming from a mature and sugary place like Rails. Quoth the Code Barbarian again:

I’m sure somebody out there likes Go’s HTML templating, but, as somebody who’s used to more sophisticated tools like Jade, it makes gouging my eyes out with a rusty fork seem like an appealing alternative.

I dunno about rusty, but… well, here’s an example. The following snippet is from the template for this site’s header. It determines whether to include MathJax, which can be done on either a site-wide or a by-page basis:

{{- if (or (.Site.Params.math) (.Params.math)) }}
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
{{- end }}

A few things stand out here. First is the Polish notation-esque way the logic has to be written, with the or to the left of its two arguments. What you really want, of course, is the more familiar infix construction:

{{- if (.Site.Params.math or .Params.math) -}}
...
{{- end -}}

But that doesn’t appear to be valid Go template-speak.

Then there’s the way the parameters are referenced: beginning with the anonymous and mysterious ., which refers to the current “context”. Concision is nice and all, but just a .?? A . with nothing to its left just seems unnecessarily obscure, almost Perl-like in its obfuscation. (And then there’s the fact that there are two sets of parameters named Params.)

Another small thing: the - sign attached to each {{ and }} prevents a blank line from appearing in the rendered HTML where the template code used to be. Rails used to need this kind of thing, but not anymore. And given how cluttered templates can get, every little bit of tidying helps. It’d be nice to have a configuration option that just makes the - implicit by default.

Getting even more nit-picky: I personally find the “mustache” notation {{ and }} unintuitive, even kind of distracting. It doesn’t sit well with the surrounding HTML like the corresponding <% and %> of embedded Ruby does. You might think it helps make the Go code stand out from the HTML, but that’s really a job for your syntax-highlighter. And something about those double curly braces just doesn’t say to me: your code here! I just see redundant C syntax instead.

These are small things, and probably idiosyncratic to me, in large part. But they did accumulate to noticeably slow down the whole getting-started process.

Themes

Ironically, none of that would have been an issue if I’d just gone with one of the existing, out-of-the-box themes, as I originally intended. Then I could’ve just poured my content into an existing template, mixed, and served. But I couldn’t find a theme that suited me! (Shocking, I know.) There are loads, including some great-looking ones. But they’re mostly designed for developers (gasp) and the people they develop for (escandalo!), not academics.

The Academic theme seemed the obvious choice. And it’s probably great if you’re a big-time engineering prof running a ginormous lab teeming with underlings who churn out ten publications a year under your name. But for a humanist shitmuncher such as myself, all the industrial-strength plumbing just got in the way.

The Finite theme was much closer to what I needed, but still overkill. And using it effectively would’ve required learning a lot about Hugo’s inner workings anyway.

So I sucked it up and created my own theme, Scarab. It’s basically a dumbed down version of Finite (but using Bootstrap instead of Foundation). It should probably be named Infinitesimal, not Scarab. But like I said: shitmuncher.

Docs

Luckily, Hugo has pretty thorough and clear documentation, including a solid tutorial on creating a new theme. But to really get where I wanted to go, I needed to read the full docs pretty much all the way through. And even though they’re thorough and clear (for the most part), they are occasionally terse. The organization also leaves something to be desired. So there was a lot of trial and error and googling, and there still is.

Git Glitch

Once I had the whole site built and themed, it looked like the sailing would be smooth. The workflow for creating new content is straightforward and fluid. But, of course, there was still one crag to navigate: version control.

I basically have three separate projects in one place. First there’s the top-level directory, hugo/, with subdirectories for my Markdown content, images, etc. Second is the hugo/public/ subdirectory, where Hugo assembles all that stuff into the actual HTML and related site materials that get uploaded to a public server. Third and finally, there’s the hugo/themes/scarab/ subdirectory for my custom theme, which I’m constantly tweaking and updating.

Each of these needs its own git repo. Why?

Well, this site is hosted on GitHub pages as a “User” page. So hugo/public/ needs to be on the master branch. And since I don’t want to make all my drafts and raw materials public on GitHub, hugo and hugo/public/ needs separate repos. As for hugo/themes/scarab, that’s its own project. People should be able to download or fork it on its own, without all my stupid content bundled in. So that’s another repo.

So I have three projects, two of which are in (sub)subdirectories of a third, with .gitignore the only thing making sure they don’t get all scrambled up. And every time I want to update my site, I have to do two commits: one for hugo/ and one for hugo/public/. I only have to do one push, since only the second repo is up on GitHub (I don’t have a paid/private account). Unless I’m updating the theme, in which case I have to do three commits and two pushes. It’s not ideal.

Conclusion

If I sound like I’m complaining, that’s because I love unnecessarily complex technical projects that give me something to complain about. Especially if I learn something in the process. And I did learn a thing or two in this process. I’m even a little sad now that it’s over and Hugo is humming along, staying out of my way so that I have to actually work on creating content. Maybe I’ll just try one more tweak to the theme first; I hear there’s a new free serif font that’s supposed to be amaze…