Choosing a Static Site Generator
When it starts looking like you made the wrong choice at some point,
- You look more carefully to determine whether the perceived problem is inherent to the situation in question - or if you simply haven’t figured out what’s happening. Read the manual (again).
- You chuck it in the FuckIt-bucket and move on.
2 is where the static site generator Zola ended up a few days ago. This happened after I had spent a couple of weeks working with it alongside Hugo while also looking into other solutions.
As it turned out, I ditched Zola for all the wrong reasons. (Plot spoiler: My assumptions were wrong, and I got grumpy too soon)
But here we are, and that’s one thing less to worry about.
Can I interest you in a slightly used static site generator?
A static site generator (SSG) seems like a reasonably straightforward piece of machinery. It takes some input (e.g., a Markdown file) and then transforms it to HTML and CSS with an optional sprinkle of JavaScript.
Yet you have 347 static site generators to choose from at the time of writing. 1
People have written static site generators in no less than 46 different programming languages. I gave up counting the available template types. Nineteen licenses are in use.
In comparison, you only have about 278 Linux distributions to worry about if that’s something you’re into. 2
No way are you going to spend your time examining 278 or 347 alternatives in any detail.
You start with some requirements. Like:
- A. Features
- Can it do what I want it to do?
- B. Usability
- Without giving me a migraine?
Now you need shortcuts to determine which of the offerings you should spend more time examining.
Features: Out-of-the-box functionality vs. customization galore
If you know upfront that you will do some heavy modification of the standard layout options, you should look into SSGs using a template system you have experience with.
And if you, for some reason, need to wrestle with the guts of the system, obviously choose one written in a language you know.
Features: The theme is set
You (a designer, your boss) have already decided on a theme. In that case, you will save a lot of time using a SSG that already supports that theme. Be aware that some themes have been ported from SSGx to SSGy and are not always identical.
Another thing to be on the lookout for is that themes can add quite a lot of complexity to your setup. If the documentation is littered with $ npm --all-the-things, you know what you’re getting into.
Features: Integrations
“I plan to eventually use this as a frontend for some headless magic system .“I think the smart thing to do here is to stick with one of the most popular SSGs. Not because less used solutions would be inherently less suited for this sort of integration but because they are less likely to have documentation for working with headless magic system. This is just me guessing, but projects with many active contributors tend to have more comprehensive documentation. The same is true the other way around; magic headless system developers will document integration with the most popular SSGs long before they get to the abandoned one written in Brainfuck.
Features: For how long?
This ties into my previous point. There are a lot of dead or dying software projects out there. The same goes for SSGs. If the project is feature-complete and free from annoying bugs without having any dependencies, then maybe that’s not a big deal. But still. All things being equal, choose a project with an active community and some history behind it.
Usability: But will it give me a migraine?
Who knows.
You have to try things out, look at the documentation (which may be incomplete or just plain wrong), or trust other users.
The first two options require an awful lot of time.
For the third one, you could use popularity as a proxy. Yes, crappy things can be insanely popular - but we’re dealing with a corner of the world where most users can and will move on if something bugs them. On jamstack.org/generators, they show Github stars, which is a start. Gameable, maybe, but who knows?
Luckily you have a fourth option.
A 100/100 adventure with dead-simple 🦕🦕, ⚡ and blazing 🔥
How do people from the different SSG projects describe their solutions?
Sure, there is going to be some marketing fluff. But you’re an adult, and you can see through all that.
I spend some time with the source code for jamstack.org/generators, a cup of coffee, grep, sort, awk, and uniq. Not the worst way to start the day.
The idea was to isolate adjectives to see if any patterns emerged. Patterns emerged indeed.
The spectrum goes from > no bullshit, just the facts < to “Awesome! Beautiful! Get one for the kids while you’re at it!” Most descriptions containing adjectives fall somewhere in the middle. And they are remarkably alike in their choice of words.
“Simple” and “fast” is the way to go if you’re a static site generator.
Really simple, super simple, extremely simple, dead simple, very, very, very, simple. Most simplest, even.
So, what is this thing called “simple”? It could be architectural simplicity, few dependencies, or few lines of code. Some of the SSGs on the list are simple in these ways and require no more than a few pages of code to do their thing. Other SSGs describe their project as “simple” even though they have a dependency graph the size of Texas and a line count to rival a space shuttle.
Then we have fast. And not just regular fast.
Faster, blazing fast (six counts!), extremely fast, super-fast, ultra-fast, rocket fast.
There might be some historical reasons for this since some of the “old” popular frameworks have struggled with build time. If you are building a site with a modest page count, you have bigger fish to fry than shaving average build time from 8,2 seconds down to 2,8. Yes, you do.
You can get “magical” or “magic-free .” Opinionated” or not.
Only 15 of the SSGs are modern, which narrows the selection down if you don’t want to be left behind.
There’s even one suited for “hand-crafted development.”
You won’t believe the amount of 💗 and JavaScript we put into this motherfucker.
I have a handful of equally worthy contestants. Now what?
If there is nothing to base your final pick on (no facts, feeling, or hunches), you need to add chaos to the process.
You have spent time researching the available options. You have narrowed the selection down to something manageable. You have been a responsible adult human being. Still, the top-five candidates get the same score on all parameters. What to do?
Solution: You either pick an option at random or base your choice on something completely idiosyncratic.
Choose the last strategy. And not only because it’s fun:
Let’s say you have chosen something because the name reminds you of the smell at the back of your grandmother’s wardrobe.
Now suddenly, that option is superior to the other alternatives because they don’t remind you of grandma. Also, you get to pat yourself on the back for choosing a good solution. When things turn sour, you shake your fist at the sky.