When I moved off of Blogger and created cmwolfe.net, static site generators were all the rage. They were a reaction to all the heavy platforms like Wordpress and the aforementioned Blogger, as well as a reaction to the proliferation of big, Javascript frameworks and Single Page Applications. For many people, all of these tools were too heavyweight for a simple personal blog that needed little more than some HTML, CSS, and a smidge of Javascript.
Static site generators allow you to automate the process of churning out plain HTML pages for all of your blog posts. They also almost universally allow you to write your actual post content in a format such as Markdown. Thus they allow you to create a blog made up of lots of simple, individual HTML pages without all the pain of having to hand write them all.
For many use cases this sounds perfect. And indeed they can be! But static site generators can also be hell. Here are some of the general lessons I learned about static site generation, which I feel can be applied to most tools of this ilk:
Potentially High Learning Curve
Earlier I said that static site generators were a reaction to both complex web technologies, as well as overly restrictive publishing platforms. I used the word “reaction” intentionally, as it implies that SSGs do not simply work differently, but opposite of traditional publishing platforms and CMS’es. That means simpler webpages without extra cruft, as well as freedom – and in some cases, very little guidance – in regards to configuring, styling, and structuring your website.
This control and freedom comes from the fact that while Static Site Generators create clean, simple HTML, the Generators themselves are complex bits of code. The configuration, styling, and structuring of your site is driven not by pure HTML/CSS/Javascript, but by the programming language the tool is written in, by 3rd party libraries written in that same language, and/or via templating languages and DSLs. In other words, in order to use a given SSG, you need to be familiar not just with the language it is written in, but that language’s developer ecosystem. If you are already familiar with this stuff, great! You should have no trouble getting started. Otherwise it is essential that you learn them as quickly and as deeply as possible, or you will run into all sorts of problems you will be unable to fix.
I am not necessarily against any of what I just said. It is kind of hard to offer more control and customization options than a publishing platform such as Wordpress without bringing some sort of programming language into the mix. The problem I have, rather, is that most SSGs do a terrible job of explaining any of this, and as my next point explains, that becomes a big problem.
SSGs are Unsure of their Audience
Most SSGs have a homepage that brags about how simple it is to get a site up and running. Just download some package and a nice site template, run a few commands and voila - you have a site up and running! They often go out of their way to avoid discussing the fact that the tool is built on a specific programming language and uses a ton of external libraries. It very much looks as if they are all marketing themselves to the people who are currently using Wordpress/Blogger and are happy with it.
There are so many problems with this. First of all, why market to that audience? The whole point of SSGs is to act as an alternative to big CMS platforms. But if people are happy with those platforms, it is likely because they are happy with how simple they are to setup and use.
So why, then, would anyone write a tool that allows for greater flexibility, more control, and more customization, and then market it to people who have no interest in any of these things? For better or worse, SSGs are intended to be used by programmers who can, will, and want to write some code to create their website. They will understand if you explain to them how the tool works, what it uses, and what it integrates with.
Instead, we get glossy product sites that paper over those crucial details. This makes it much harder to determine whether the tool is right for you. It also means that the documentation can sometimes be crap. The SSG likely has all sorts of special functions you can use in your site templates to format data and render partials, but good luck finding any details about how they work. Every single one of these tools should have API-documentation in the style of Javadocs, Python documentation, or Rubydocs, and they should be easy to find. In most cases, that simply isn’t true.
SSGs are too often marketed to an audience who doesn’t want them, at the expense of the audience that could make use of them. I can only assume that this is driven by money. Either some of these project authors want to eventually monetize their work, or they hope that some company will see their project and hire them, and they only way for either of those things to happen is to make sure the tool has a flashy marketing pitch. Again, I am not opposed to any of this, but just be straight with us, okay? Otherwise give us documentation we can actually use.
Dependency Hell
When an SSG uses other libraries to drive some of its functionality, there is a chance that updates, version mismatches, and other weirdness will crop up. You don’t think about this when you first start out, but after a while it will lead to a maintenance burden you might not have thought you would have.
Feature Creep
Static Site Generators remind me a lot of JavaEE. JavaEE is a collection of specifications for how certain Enterprise technologies should work in the Java ecosystem. Anyone is welcome to create an implementation of any one of the specs, so long as you implement the spec in full. Beyond that, however, you are welcome to add additional features to your implementation. Every single vendor who implements JavaEE tech does exactly that in an attempt to lock in users.
See, if all you ever rely on is the features defined in the spec, your code should, in theory, work on every implementation out there. That’s good for the user, but bad for the vendor, who almost certainly wants you using their stuff long enough that you choose to pay them for a support contract. So they add better, nicer features that only their product offers. The users take advantage of these features, then later realize that migrating to a new product would require refactoring them all away, and suddenly they chose not to migrate after all.
Whether intentional or not, Static Site Generators do the same thing. They all start off telling you to write your content in plain Markdown. But not only is Markdown limited in its scope, but it also has a very specific purpose. It isn’t intended to be used to create images with captions, or change the content or formatting using logic branches. In order to facilitate this, most SSGs have some sort of templating language that allows you to add inline code into your Markdown. Thus we have a JavaEE scenario – if you stick to plain Markdown, your site content should, in theory, migrate to any other SSG or platform. But in reality most people will use those templating features, at which point your posts are no longer portable to another platform without a lot of work. This takes away one of (in my opinion) the major selling points of a Static Site Generator, which is portability through simplicity.
Feature Creep Part 2
Despite the fact that SSGs sell themselves on their ability to write simple web pages without extra cruft, it seems that everyone still gravitates toward the cruft sooner or later. Lots of guides and howto articles about Static Site Generators teach you how to integrate Javascript frameworks, Typescript, SASS, LESS, and who knows what else into your build process. Part of me is glad to know that you can add these technologies if needed, but a stronger voice in my mind says that all of this misses the point of an SSG in the first place. Still, the frequency with which I’ve seen people integrate this tech into their static site is high, and if you see it happen enough you can easily fall into the trap of convincing yourself that you need it all too. This is a mistake, as it will add extra layers of complexity to a system that you may already not understand.
The Bottom Line
I do not think it is useful to say “Static Site Generators have a specific purpose”, because they do not have a singular purpose across the board. Rather we should say that each Static Site Generator tries to serve a specific purpose, and it is important that you determine whether any single one of them suits your needs. Picking one simply because it is written in your favorite language, or because people talk about it a lot is a surefire path to disappointment and failure. Look at the documentation. See what people are using it for. Can you find out the tool’s history, and how it has evolved over time? All of these things can reveal information that is more telling than any splash page will ever be.