Summary: If you have a small website, like a personal blog, you might not need a static site generator. Writing plain HTML and CSS works reasonably well. And maintaining consistency is easy for a small site. It's even straightforward to write and update a minimal RSS feed. By keeping the technical details to a minimum, we can instead focus on the writing.
There's almost this rule, that when starting (or in my case, restarting) a personal website or blog, there must be a post about how it was setup. Because many times, the technical aspects are a lot of fun, and it let's us procrastinate writing other posts. So here's my own post about exactly that, and why you might not need a static site generator for your website.
I've used quite a few static site generators in the past and present: at least Docusaurus, Hugo, and Jekyll come to mind. Using a static site generator often feels like the default choice when you have mostly static content. But let's take a look at why we're using them in the first place.
Static site generators maintain consistency and reduce duplication through templates. For example, Hugo uses Go templates, while Jekyll uses Liquid templates. This might sound great at first glance, but instead of writing HTML and CSS, you now have to figure out a templating language. There is also usually a configuration file format, like TOML, for metadata and site configuration. Not to mention a CLI, template functions, rendering customizations, breaking changes, and more.
For small websites, like a personal blog, there's not that many different kinds of pages, so keeping things consistent is relatively easy. Duplication is often fine, and search-and-replace for updating a bunch of files is usually enough (or writing a quick Nushell script).
For this site, I opted to use Neat CSS. It's a single CSS file, less than 200 lines (~3.2 kB) without minification or compression. It also opts to not have any navigation other than a single link back to the home page. This way, there's no need to change multiple pages when navigation changes.
When creating a new page, I usually just copy an existing similar page, clear out most of the body, and update the page title. This leaves me with roughly the following code duplicated on all pages.
<!doctype html>
<html lang="en-US">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="/favicon.svg">
<link rel="stylesheet" type="text/css" href="/neat.css">
<link rel="stylesheet" type="text/css" href="/custom.css">
<title></title>
</head>
<body>
<a class="home" href="/">↖</a>
</body>
</html>
Organization is trivial, since paths on the site correspond to file system
paths. The notable exception to this is the
index.html convention as discussed
below.
Have you tried writing HTML recently? I had not until a few weeks ago. I was under the impression that it would be a not-so-great experience. But my last time writing plain HTML documents was also at least 10 years ago. Probably more. It turned out to be a pretty refreshing experience. The standard has evolved a lot, and good editor support and formatters help (I have Prettier setup for my site).
Don't get me wrong, I still think Markdown has obvious upsides, and given the choice, I'd probably still pick it over HTML. But writing plain HTML is actually not that bad. I'd invite you to give it a try and you might be pleasantly surprised. Maybe your idea of it is as old as mine was.
This topic covers a lot. Everything from image processing, JavaScript building, using Sass or other CSS alternatives, fingerprinting and SRI hashing, concatenating files, to ensuring code examples compile, and generating sitemaps and RSS feeds. You can probably think of even more things.
Some of these are arguably useful. For example, in many Scala open source projects, we use mdoc to type check code examples in Markdown. This ensures we always have up-to-date and working documentation. That alone can be enough to motivate the use of static site generators.
It ultimately depends on your use case whether you need preprocessing or not. I initially thought I would need something to generate the RSS feed. But as it turns out, writing a minimal posts feed is straightforward. But you'll probably have to limit how the feed looks like. For example, maintaining full-text copies of posts in the feed (and updating relevant timestamps) is not pleasant. But most RSS readers can easily extract the full post content anyway.
Similarly, the syntax-highlighted code above was generated using Shiki. It outputs plain HTML with inline-styles for the colors. This way, there's no need for preprocessing or JavaScript. Yes, you won't easily be able to change theme for all code on your site through configuration. But maybe that also means one less thing to obsess over on your site.
Having a web server for local development can be useful. However, it's also possible to make the site work locally without one. I started without a web server, then realized there are some pretty good reasons to have one, and not only for live reloading support.
index.html from links, making them look how
we've come to expect.
/) links, which would otherwise
refer to the file system root.
I started with running live-server manually and then switched to the Live Server extension, which essentially wraps the former project as a Visual Studio Code extension for convenience. If these don't fit your setup, there seems to be plenty of other options available.
Having a website which can be browsed offline without a web server initially sounded like a great idea. But not being able to use root links meant I would always have to track where the page was relative to the linked resources. This became a bit more tedious than necessary.
Even with a static site generator, deployment is usually easy. Without one, it can really be as simple as pushing a git commit, since it's just the files being served. I host this site on GitHub Pages and the full source code is available.
Perhaps one of the biggest reasons for not focusing too much on the technical details is that it instead allows us to focus on the writing. We can find our own workflow: what editor to use, the time of day that works best, and so on. Otherwise, it might be tempting to constantly tweak the technical setup, when it's really the writing that matters most.