(framework) mistakes were made

It took a long time for me to go from “I want to write blog posts” to actually, y’know, writing anything. Not due to any sort of writer’s block, but because the idea of designing a new website was so exhausting.

Even once I decided to use a static site generator, I had to choose which generator, and then a template… Ugh! After four months or so I finally picked Hexo and tweaked a template to my liking.

That turned out to be a mistake. How could I have done better?

The perils of picking tools

Once, back in the before times, when we wanted to create a webpage we would write plain HTML in a text editor (uphill both ways in the snow) but that hasn’t been the in thing for decades now. The last time I had a go at creating a new website (circa 2010) it still seemed like content management systems were the way to go. Spend days or weeks choosing a platform that had all the features you need but wasn’t too complicated, or write your own from scratch and be responsible for all the database management, user authentication, and API design.

I’ve always fallen in the “roll your own” camp, which is why I have not had a functioning website in a decade.

When this new blogging impulse hit, I, older and wiser, determined to use a tool to abstract away all the blog boilerplate and website design. I wanted to simply publish posts without having to babysit my own Linux server. Conveniently, while I was ignoring the world of web, the tide had shifted away from databases and admin consoles to static HTML sites on free hosting.

Turns out I still don’t like outsourcing most of my application to other programmers, but it’s either that or go back to never finishing my own framework so what choice did I have?

Decisions, decisions

A lot of choice! There are approximately eleventy-billion static site generators out there, so how to pick one, if you only barely understand what a static site generator is? I settled on a few heuristics to get the fastest start on a new site:

1. How good is the documentation?

If you want to get started as fast as possible, be on the lookout for step-by-step instructions for getting up and running with all the features you’re looking for.

2. Is the generator written in a programming language you know (or want to learn?)

Eventually you may want to understand what is happening inside the generator, or edit some of the templates. Even if you are not interested in tinkering, the tooling around installing, updating, and running the generator will be tied to the language it’s written in. Some familiarity with that programming language will make the whole process easier.

3. Are there pre-built themes you like the look of?

Even if you intend to make a custom theme, starting with one that is most of what you want will give you a vast head start.

4. How popular is it?

The larger the user community, the more likely you are to find tutorials, Stack Overflow answers, and lots of themes or other sites for reference.

5. Is it actively maintained?

How often is it updated? Are there any problems regularly reported by users that aren’t getting fixed?

Mistakes were made

Where I went wrong was in prioritizing a pre-made theme I liked over community, language, and support. Hexo is a fairly popular static site generator written in node.js, but it turned out to have some fatal flaws for my needs.

Turns out I don’t like Node

I didn’t have strong feelings about language choice when I started, and I thought learning Node a little better might be useful. Instead I just felt annoyed whenever I had to debug anything, because I don’t care enough about getting familiar with the framework, and it has a few quirks that frustrated me:
- Node doesn’t have a standard templating language. Almost every theme I looked at used a different templating style, which made it difficult to generalize about how templates worked and how to customize them. On top of that, the templating framework used by the theme I chose turned out to be obsolete.
- There are too many dependencies. The quick-start instructions for setting up my Hexo site didn’t include checking in a dependency lockfile. As a result, some transitive dependency updated and for unknown reasons broke Hexo’s ability to generate my site. This crystallized my frustration with the overall Node dependency ecosystem.
The support community is not accessible to me

Hexo has a reasonable number of users, but many of them are Chinese-speaking. Many times when trying to debug an error or find a tutorial, I had trouble finding any results in my native language. I didn’t think this would be an issue when I chose it, but I ended up having to debug a lot more than I predicted.
Some of the defaults result in undesireable behaviour

The final nail in the coffin of my Hexo experiment was realizing that by default permalinks include date information, but default date-time stamps in posts don’t include time zone. This meant that URIs for all my posts sometimes changed depending on which timezone I was in when I generated the static files. This broke any links to my site and was overall much less permanent than “permalink” implies.

I probably could have worked all of these problems out, but the entire reason for using a static site generator is to not have to do all this code tweaking and maintenance!

Enter Hugo

After a week or two of sulking, I picked Hugo as a replacement generator. I don’t love any of the themes, but found one I can tolerate until I find time to make something custom. Hugo has the following selling points:

The community and support seem vibrant. I haven’t had any trouble so far finding documentation or tutorials for any issues I’ve run in to.
I am actively interested in learning more Go and find it straightforward to read both code and templates.
The specific date issues I had with Hexo don’t exist in Hugo.
The post and front matter formats are identical, so I was able to simply copy-paste my previous source files into the new generator.

Fingers crossed this will be the last major shakeup for a while, but at the very least I am moving on to new and different problems.