Why are static site generators so complicated to use?

Well, I've been playing.

This summer, I've played the excellent FromSoftware’s Dark Souls Remastered video game on my trusted Nintendo Switch, and I loved every minute of it.

That’s a lie…

A good (titanite) chunk of these minutes was absolutely awful, and hard, and difficult. But for the most part, it was delightful: video games as they should be, as far as I am concerned.

Dark Souls is quite famous for its level of difficulty. It is a game where players expect to die a lot and restart as many times as needed from the famous “bonfire” saving spots. While the universe of the game is rich, mysterious and fascinating, it’s the gameplay that unites its players first. The “lore” comes only second to the well-deserved reputation of being a hard game where players will see the words “YOU DIED” on the screen very, very often.

The difficulty of the game is only matched by how rewarding it can be. The joy of beating a boss or finding a new bonfire can become so intense that you forget how hard the game was in the first place. Just like when your favourite team scores a goal in a football match, the happiness and sense of relief make you forget how stressful the preceding action truly was, just a few minutes ago.

In Dark Souls, dying is an integral part of the mechanics of the game, and accepting that fact helps a lot. Dying, trying again, learning, dying again, redoing it all, ten, twenty, fifty time, is what makes perseverant players eventually better, to the point where the game becomes manageable, enjoyable, and — dare I say it — not that hard. There is a real sense of progress, and it feels pretty great.

Anyone can beat the game if they are focused and patient enough and ready to accept a lot of pain and frustration along the way. The beginning of the game, in particular, requires a lot of work: this is not a casual or typical gaming experience. How many times did I say to myself, “Well, you tried, but there is no point going on like this… Even if you beat these gargoyles, which you probably won’t, you won’t pass the next level anyway. You might as well call it a day and go read a book.”¹

I am talking about Dark Souls because I think modern static site generators are a bit like a hard video game: extremely frustrating at first, difficult to use, making you want to give up, until things get better and it becomes very rewarding. Succeeding at doing something feels great, and you end up forgetting how difficult and painful that simple action really was.

Out of curiosity, I have been wanting to see what the fuss was about with these tools: Hugo, Gatsby, Zola, Jekyll, Astro, 11ty, etc. There are so many that it’s hard to keep up.

The Jolly Teapot has a very minimal design, and I figured that it could live on one of these SSGs without too much work. Therefore, I played the game. I decided to learn how to use a few of these tools and to work on a mirror for this site as a personal project.

First I started with Hugo, as it’s apparently the most popular SSG. After 20 to 30 hours “playing” with Hugo, let me just say that I now think Dark Souls was pretty easy in comparison.

Sometimes I wonder if these static site generators are hard to use by design. You’d think it’s pretty straight forward and well documented, but for someone like me, who has spent the last 15 years or so working with Drupal, WordPress, Squarespace, and Umbraco websites, the SSG game is on a whole other level of madness.

The amount of time I spent making Hugo do something extremely fancy and completely unheard of, like ordering blog posts in an anti-chronological order is kind of crazy (I know I demand the impossible). I felt dumb and clueless more times than I can count. I’ve tweaked the front matter of my files blindly until everything was working. I’ve made dozens if not hundreds of web searches just to understand how to do the most basic things, like changing how the date is displayed. Fair to say that I didn’t finish this painful game, and I gave up halfway through.

Then I moved on to Eleventy. Whereas Hugo seemed like it had its moment of glory circa 2018, Eleventy feels more active, and the community shares a lot of good tips and solutions in discussions one to three years old. It also felt easier at the beginning. Maybe because I was learning from my previous mistakes, but what took me ten hours with Hugo took me just one hour on 11ty. Everything was very promising until I reached Eleventy’s final boss: images. I won’t go into much detail on how they are supposed to work, but this part is truly maddening and unnecessarily complicated.

I didn’t give up though. I knew I had to commit and push through.² I guess I can say that I “finished” 11ty, and now the whole Jolly Teapot is mirrored. Well, almost mirrored, as the search part felt like too much work for a side project.³

The “game” was fun, and I very much enjoyed this experience. The moment when I managed to make the Markdown rendering engine display footnotes properly felt like a victory, and I could feel myself smiling when I managed to make permalinks behave the way they are supposed to. It was very entertaining, and rewarding.

But a static site generator is not a video game, is it?

I’m not supposed to enjoy the difficulty. I’m not supposed to learn that much, start again, and get better after hours of repeating the same actions and failing over and over. For video games, this process is their main purpose: to entertain, and challenge you. For SSGs? The main goal is supposed to be to publish web pages. As I implied: my needs are very limited, and these tools, as simple as they might appear to the tech-savvy user, are way too complex for me.

I can see why so many people love these tools. The reward is intoxicating. These tools rely on an ecosystem most users already know and are familiar with: Git, GitHub, the terminal, JSON files, etc. SSGs like these make a lot of sense, and I definitely understand the appeal: you own your site, you own your code, you tweak, you modify, you edit. It feels great and you end up with a top-notch, fast website. This feeling really makes you forget how stupidly complicated the whole process of setting up a website is in the first place.

This whole experience made me realise two things:

One, that if SSGs are mainly open source, their communities seem to gravitate heavily towards the same tools like VS Code, GitHub, or Netlify. Not using one of these can make the whole documentation and process a lot harder to understand, and I find this a bit strange. I would not go the whole way of owning my website using an open-source tool just to eventually rely on a big tech company like Microsoft, or using a free server on Netlify (and you know what is being said about free products…)

Two, that Blot, which is also technically a static site generator by the way, is so good and precious! The main difference between Blot and other SSGs is that Blot is easy to use, elegant, and doesn’t require the “player” to use the terminal, install Node.js, Brew, Git, create a GitHub account, or promote the likes of Vercel and Netlify at every opportunity.⁴ Blot doesn’t assume its users know what a git branch is, or how to connect to a GitHub repository, or will Google every single piece of the puzzle to see where it fits.

Sure, I pay the price for this: I rely on an independent third party for maintaining the code and managing the server, with all the associated risks. What happens if the company goes bankrupt? But is this situation really worse than putting all my eggs in a Netlify or GitHub Pages basket? I wonder. After all, I have all my posts saved as text files on my computer. I own my domain, and, as I have proven with my 11ty experiment, it’s easy to recreate the website elsewhere, if needed.

Why aren’t there more Blot-like tools around? Why have most of these SSGs — as great as they are at what they do — not given birth to simpler, more usable tools that work like Blot?⁵

In the end, my experiment with SSGs was fun. I have heard a lot of good things about tools like Eleventy and Astro, and now I understand where they come from. These tools are truly fantastic, powerful, and modern. If you are already used to working with the terminal, Git, and are familiar with languages like JavaScript, you will not find them complicated like I did, hence their popularity I guess.⁶

But if you’re not already evolving in this environment, or if you don’t need all of the features and power of these tools, and if you’re like me, you can try them for yourself, like Loren, and see if you can learn faster than you can get frustrated.

Or, you can keep using much simpler tools, like Blot (for which I now have an even greater appreciation), without the thrills and buckets of pain of SSGs. To satisfy your entertainment and learning needs, or to challenge yourself, you are better off playing something especially made for that, like the Dark Souls video game series.

Next side project: Kirby.