-- Leo's gemini proxy
-- Connecting to gemlog.blue:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini
This is a gemlog about project ATHN. A new competitor to the web. So this post will be written from the perspective of developing on that project. This post is about when static site generators make sense.
A static site is a site where the pages are predetermined. They're just a bunch of html or athn or whatever files on a server that you can request and get as is. As opposed to dynamic sites where the pages are generated when you request them.
But bridging the gap between static and dynamic sites are static site generators (or SSGs if you're in the business). They do pretty much exactly what it says on the tin. They take some input, usually some files in a directory, usually using some templating language, and deterministically generate a static site from it, ready for serving with any server software. Pretty neat huh. They're super useful, because static sites are just so much easier to deal with. And besides, most sites dont actually change that often. Take a directory listing, that only changes whenever you add a new file to the directory, perfect job for a static site generator.
But as cool as SSGs are, they dont come for free. Static site generators really do have some downsides. They require you to set them up, and to learn their way of doing things, usually involving some templating language. Personally it took me a couple of hours to figure hugo (a popular SSG) out, I of course dont know all of the features, but I was able to get the job done. But if I hadnt used hugo and just opted for manually making the site, that time investment would have been zero.
SSGs also universally require a compilation step, that's kinda the whole point. But you have to actually *do* that every time you change the source, depending on who's hosting your site that problem ranges from: "no big deal, I'll just check this box" to "I need to learn how to write systemd units" to "I need to change my entire infrastucture out". And depending on what SSG you're going with the compilation step can be more or less a pain to configure, more or less computationally intensive and more or less supported by your hosting provider.
So sure, it might be easier than dynamic sites, but it still doesnt come without some investment. and with that the opportunity for vendor lock in. If you're using, say google's home grown SSG on google's home grown hosting service and they decide to shut that thing down, or you just wanna switch for some other reason, you suddenly have to rewrite your entire site's source.
SSGs arent perfect, but what's the alternative? Well, just take a look back to where we came from. Ah yes, the simpler times (or the more frustrating times if you're a pessimist), where we just wrote it all by hand. Yes, that's the alternative, just doing all that work that the SSG did for you automatically... by hand. I know it might sound a bit dumb but hear me out.
There's this phenomenon that's common in web development that I like to call the 'but what if' fallacy. It goes like this: when you go to make something, you think about all the ways that it could be used, what if this, what if that, and you end up imagining all kinds of scenarios. Now that in and of itself isnt a problem. But it starts to become fallacious when you start to think that the best solution is the one that can handle all of those 'but what if' scenarios that are realistically incredibly unlikely, or at a closer look straight up impossible, to actually happen. When in actuality you should really be focusing on the bigger picture.
A relevant example would be this: You have a news site where the frontpage has links to the 3 most recent articles and a view all button. Say you write a new article about once a week and it takes you about 5 hours to do. Updating those front page links and testing that it all works as intended maybe takes about 30 seconds. For every *5 hours* you spend making a post... *once per week*. Is it really worth it to go through all the SSG trouble just for that, no not really. But what if I hired 100 journalists and made 100 articles per week, then I'd need an SSG to do that work automatically. Sure but that's not even remotely realistic, you should be thinking about the best solution for reality, not for the 'but what if' fallacy. And if by some miracle you actually do get 100 journalists you can just switch to an SSG.
If you have content that doesnt change that often, and when it does it has relatively little impact on the other content. You COULD use an SSG. But you COULD also just do it by hand. And you'd be avoiding all those nasty costs of SSGs that I talked about in the last section.
║ _╱
║ _╱
║┉┉┉┉┉┉_╱┉┉┉┉┉┉┉┉┉┉
Site complexity ║ _╱
║ _╱
┉ SSG ║ ╱
- Manual ╚══════════════════
Effort
If you look at the ASCII art chart above you can see that the effort required to manually write and maintain a site grows linearly with the amount of content and features on your site. But using an SSG the effort is more or less constant no matter how much content you have. But SSGs have that initial learning curve and time investment, and potentially also a big hump in the future if you ever decide to switch vendors.
So the big question is: When do these 2 lines intersect? Is my site complex enough to justify that initial time investment?
Answering that requires some pretty decent foresight skills, and some realism. You have to actually make a plan, do some design work and be honest with yourself. How much effort would it be to learn and set up the SSG? How many features do you need that can actually take advantage of an SSG? How much effort would it really be to do those things by hand instead? How often do you plan to update the site? You need to make those kinds of considerations in order to find out what option's right for your project.
I'd argue that the manual method's line is considerably flatter than most people give it credit for. Unless your site is really big and complex the manual method is really not *that* bad. And with modern IDEs or text editors and some basic scripting skills you can really speed up those monotonous tasks. I'll give some examples of what I mean:
With an SSG you might store some commonly reused thing like a donation link in a variable, in case it ever changes.
If you're doing it manually you'd just have that link hard coded in lots of places. But if you ever wanna change it you can just do a find and replace on that link for every file in your site directory. If you have a cool text editor like vim it's as easy as these 3 commands:
:args **/*.athn :argdo %s/@@@https:\/\/www.patreon.com\/myusername/@@@https:\/\/www.onlyfans.com\/myusername :argdo update
Another common SSG job is to have a fragment of a document (like a header or footer) shared across multiple documents.
Vim can also easily do this with a little macro. Put the shared header in a file called 'common_header', then open the files you wanna insert it into (in this case all of them) and type out a little macro like this:
nvim **/*.athn qw/+++ Header\n V/+++\n dk:r common_header :bnext q
And now we can just send this macro off on all our documents and watch it replace headers with superhuman speed (and of course save with :bufdo update)
Okay, one more example. Let's make a directory listing. This time a short and basic python script will do the job beautifully. We can even put this in our $PATH to use it anywhere (and feel free to take it for yourself).
#!/usr/bin/python
import sys
import os
def main():
argument_recieved: bool = len(sys.argv) != 1
dir_path = os.path.abspath(sys.argv[1]) if argument_recieved else os.getcwd()
if not os.path.isdir(dir_path):
return sys.stderr.write("Not a directory")
for file in os.listdir(dir_path):
if os.path.isdir(file):
print(f"@@@{file} | {file} (directory)")
elif os.path.splitext(file)[1] == ".athn":
title = open(file, "r")
title = title.readline().strip('\n')[3:]
print(f"@@@{file} | {title}")
else:
print(f"@@@{file}")
if __name__ == "__main__":
main()
I went overly fancy and made the directory you wanna list selectable, I made it automatically detect and label subdirectories and I even made it extract the title of athn documents and label the links with those. If you didnt it'd only be 3 lines of code (or less if you're good). If you're wondering why I'm printing the result it's because this script is meant to be run inside vim with `:r !script.py`.
Now if you're not a vim connisseur you might think that this looks like utter nonsense, and that it's no easier than learning an SSG. Because vim is stupidly hard and unintuitive, but you'd use your own text editor of choice. And you can do these kinds of things with any (halfway decent) IDE or text editor and any scripting language. And you might already know how to, or at least you can figure it out with a pretty quick internet search.
And these kinds of skills are universally useful. If you know how to use hugo, you know how to use hugo, that's it. If you can search and replace in directories that's useful in all kinds of scenarios. So learning these skills is a much more valuable use of your time than learning an SSG.
As we've seen, static site generators can save a lot of time and hassle for sites with a lot of content that take good advantage of the features they have to offer. But SSGs also have their costs, mainly:
Time investment in learning the software
Time investment in setting it up with your hosting provider (or on your server)
Boilerplate
You have to compile every time you make a change
Vendor lock in
But compared to doing all that work by hand they're:
Less tedious
Less error prone
But I've argued that manually writing a static site is much more powerful that many people give it credit for, especially if you're good with a text editor and some basic scripting. So dont be ashamed if your tech stack doesnt look so fat and impressive. It might just be a sign that you arent overcomplicating life for yourself, that you're good at planning and designing for the future, and that you're actually taking the smart approach. Or maybe you really should get a static site generator, I cant tell you, every case is different.
-- Response ended
-- Page fetched on Sun Jun 2 10:22:32 2024