I’ve rebuilt my website! This post isn’t likely to be interesting unless you’re into static site generators or navel-gazing. It’s also not too long, as I’m omitting almost all the gory details.

A brief history of bitprophet.org

Navel-gazing!

  • Prior to 2009: Website was pretty much hand-rolled. Also ugly as sin because I know precisely enough CSS to be dangerous, but lack any graphic design skills whatsoever.
  • 2009: Started using static site generators because 2009. Chose Nanoc due to its flexibility & me being prone to over-engineering. Had lots of Big Plans for special features.
  • 2012: Realized I’d never had the time/energy to implement those Big Plans, and in the interim, Octopress had arisen, wrapping most of my Big Plan features around a Jekyll core.
    • Adapted an attractive & not commonly used Octopress theme to my tastes & relaunched, intending to “blog more”.
    • Succeeded, but only insofar as “very occasionally” is indeed more than “almost never”.

Switching things up again

Octopress worked fine for blogging, but its content layout is deliberately simplistic with a single “level” of non-blog pages. These days, I feel the need to break things up more – a single About page doesn’t entirely cut it. (And once this corner was turned, the other downsides of Octopress – effective abandonment, difficult upgrade strategy, etc – became their own excuses.)

I shopped around, seeking generators that could handle arbitrary nested non-blog content alongside the blog-oriented features I was used to. Without going into the details of why I didn’t choose your preferred option (Nikola, Pelican, Cactus, Hyde, Lektor, etc etc), I settled on: Hugo.

Because I can’t do anything like other people, this is unfortunately not your typical gushing “NEW TOOL SO GOOD OMG” post…

Hugo

I started out pretty bullish on Hugo:

  • popular & well maintained
  • beautiful (dogfooded) website
  • fast build speed due to Go implementation
  • a ton of features (including ones I didn’t even know I wanted)
  • looked very flexible regarding content layout
  • many themes on offer

And so forth.

To Hugo’s credit, it still is all of those things, but by the time I finished putting the site together, I had wasted an extremely frustrating amount of time reconciling its opinions & use cases with my own1. It’s been a good lesson on why reusing third-party solutions may not always be the right option, or at least, how skimming a tool’s documentation is a far cry from using it in the real world.

Implementation language also matters; I thought I was being pragmatic by not forcing myself to go with a Python or Ruby option this time, but it turns out Golang was a nontrivial factor in my frustration.

In the interests of pragmatism, I resisted the urge to table-flip and start over – but I would likely have saved a lot of time writing Yet Another Static Site Generator of my own, had I known what lay ahead. Though paradoxically, only by struggling with Hugo did I learn how simply some of its attractive features (like tables of contents) were implemented.

Tool choice: fraught with danger

I want to clarify that while Hugo represented a near-worst-case scenario for me in terms of poor fit (and compounded by the problems I had with Golang), this problem is not Hugo-specific in any way. It’s an intrinsic risk one takes when making any tool-choice decision. Only by truly getting down to brass tacks can you know how many rough edges, corner cases and horrible workarounds are needed to bridge the gap.

Sadly, for most nontrivial computing problems, this represents a (possibly large) investment of time and energy to evaluate each potential solution.


  1. I’ve got a big pile of specific notes from the process, far too large to share here. I might post it later. ↩︎