Uncommon but useful static site generator features

Roughly 25 years ago, I released my first static site generator. Compared to back then, we now live in a world of embarrassing SSG abundance, where there seems to be a handful of quality SSGs for every language, framework, or mental model I can imagine. Other than the mess of non-portable Markdown extensions, it feels like a golden age.

Yet, there are still numerous features I rely on that aren't widely supported in popular SSGs. Here are the features I wish were more common. (And, yes, I have implemented these in luasmith.)

Relative link translation

Let's say you have a link between two files in your site's source. In Markdown, this could be a source file named post1.md with a link like [some other post](post2.md). In the process of converting to HTML, these files' extensions might change to .html (or they might be placed into subdirectories like post2/index.html).

My opinion is that any link that worked before conversion to HTML should work after. Unfortunately, many SSGs don't support this feature, either because the links get broken during conversion, or you have to use special syntax that doesn't work in most Markdown editors or viewers (like those on Codeberg or GitHub).

luasmith implements this using a fragile hack that works for my purposes, but a robust solution is to track the original path of each item and replace that with the new path in links (leaving the hash part of the URL alone).

Internal link-checking

On the topic of links between files, SSGs should automatically find broken internal links. When I say "internal", I mean a link between files within the same site. I see plenty of broken internal links on blogs I read, so clearly this feature is not widespread.

luasmith implements this, and it also checks link ids/anchors as well.

Note: external link validation sounds nice in theory, but my naive attempts at it have been slow (necessitating a cache) or brittle/inconsistent (due to service disruptions). I might pursue this in the future.

Reachability analysis

Here's a mistake I recently made: I added a draft post with a few screenshots. Obviously, when building my "production" site, I filtered the draft post out, but the draft's linked screenshots passed through and I unintentionally uploaded these extraneous files to my web host. SSGs should be able to identify files that aren't reachable from index.html (or any other relevant entry points, e.g. 404.html on certain web hosts).

I just implemented this for luasmith (checked in, but not released), so that it (optionally) removes any files that aren't reachable.

Directory-implied metadata

If I put related posts in the same directory, it should be possible to tag all those posts by virtue of them being in that directory. Several popular SSGs let you bulk-tag items using a metadata cascade, but I like having the metadata come directly from the file system, so that I can't forget to add the metadata (or keep it in sync, as things move).

luasmith is highly opinionated, so I added support for this, but I recognize that this is probably not a common requirement.

Aside: in the past, I even used the "last modified" date for ordering posts on a blog, but I wouldn't recommend that today since most version control systems (Git included) don't persist file dates.

Viewing without a server

Yes, I'm crazy, but for a static site, I like to be able to view the web site directly from the file system, without having to spin up a web server. The trick here is that viewing files from the file system in most browsers means that absolute URLs and root-relative links (i.e. starting with /, which is more popular than I anticipated) won't work. You need to actually compute the relative path from source to destination, e.g. for linking index pages or stylesheets.

Note that when I implemented this for luasmith (by computing a "path to root" for each item), I discovered that you'll want to convert these relative links into absolute URLs for RSS/Atom feeds. It's technically not required, but several RSS readers I tested weren't able to load relatively-linked images, so absolute URLs in RSS/Atom seems like a good idea.

Misc.

Other things I like to see in SSGs (but are relatively more common):

• Self-contained in a small, statically linked binary
• Eschews bespoke templating languages in favor of something I already know

Finally, to add a dash of delicious controversy, here's an unpopular opinion: SSGs should not add tables of contents to the top of posts. I know that these tables are popular (despite me originally only associating them with SEO spam), but providing a quick overview and navigation between headings is a job for the browser.

luasmith

If you like (or are willing to learn) Lua, and you found yourself nodding in agreement while reading this post, then I have some good news for you: there is already a ~500 KB, Lua-based SSG named luasmith that supports these features (and more!), for the low, low price of zero dollars!