About this site

Making this very website is quite a journey for me, as I've always been looking at sites mostly from technical standpoint, but with this one, in in order to stay consistent and bring me joy, requires special discipline of mind to be developed and some decisions have to be made. This page describes some parts of this journey I am on.

This is mostly a note for myself, however. Trying to develop and describe some principles here.

Text-first

I am trying my best to design this website in a text-first manner. It actually does use some modern front-end techniques, but should in theory be usable but ugly even in old browsers (even the text ones, like links and lynx). Seriously considering moving to table design, just for sake of being accessible. Also, most colors on this site are in CGA-16 Palette, just because, well, why not.

This site also used a 23kb IBM BIOS font, it was pixelated and cool, but looked like trash with fractional DPI monitors. And there is not much to do about it without JavaScript (which I try to avoid unless absolutely necessary).

Lesson learnt: Choosing minimalism over aesthetics.

Of course, in the modern world a lot of people do not bother reading text - for them it is easier to download and watch a 1.5GB 20-minute video in 4K format. I do not care, text will always prevail.

I've been tempted to add tons of cool javascript features on this site, but I am holding so far. It is weird - as a web programmer I write JavaScript to be run on customer's machines all the time. I minify and obfuscate that code, of course. It is perfectly normal, industry standard. But as an internet I want as few code possible to run by itself (without me explicitly running it) on my computer. It is unrealistic of course. All I can do is try my best to not increase the number of such code. Now there is a single javascript on this site - it allows to switch color theme (there is no need, actually, as site's CSS respects browser theme preferences, but just in case...)

Plain text

I am designing this one to be a "simple" website - no CGI, CMS, APIs, CRUDs, SQL, Clean URL rewriting and all that buzz. There is no search on this site (maybe there will be one day, if it grows mature enough to have content worth of searching). There's no analytics of any kind on this website, at least for now (as I don't really care about those).

Also, part of the reason, is the convenience vs. freedom thing. With CGI site engine one is bound to its hosting, its database and limitations of the engine. With "simple" sites everything is merely files on a hard disk, no need to "migrate" anything and "maintain" it.

With CMS, one can simply go to some "admin" page and "post" something on their website, in matter of seconds. Simply updating this site costs me some effort, not too much but enough to think well before updating it, about its structure, about where do this and that belongs, and if it belongs anywhere at all.

Tools to build a static website

I decided to make my site a "static" one - to have a number of files and have them generated into a set of html pages. Heck, in the past, ony my very first website, I've been writing them myself, by hand (because free hosting I've used back then did not support CGI or anything), and many people still do, even in this beautiful technically-advanced 2024 dystopia. Back to the basics!

There is a website with a list of static site generators. Well, it did not exist back when I first decided to make site in a static manner.

Previously, I've tried using hexo to build a website - it is written in node and allows a degree of freedom - there is no need to compile the site builder itself, and changes can be made. And I can bend it to my needs, because I love JS. But it turned out that most of the time I was customizing hexo to make it do exactly what I wanted the way I wanted - to make the generator exactly the way I wanted it to, to have all the coolest features, and eventually all I was doing was modifying hexo to fit my needs, not writing anything meaningful.

Next thing I tried was making my own site generator. And it was gorgeous (for my needs), but demanded some support - when you make everything from scratch there is no ready solutions, so you have to implement them yourself (even the smallest things). It felt too complex to bother, as I did not have any further plans for the generator - was not going to make it an open/public tool for others to use.

I felt I needed more constraints. To use a system whose limitations would be only a matter of myself not wanting to adjust to them.

Zola

Then I tried zola and kinda liked it, the site is currently built using it. It sucks in so many ways, but suits most of my needs. There are several gripes I have with it, so probably will eventually move from it:

  • No option to create custom RSS feeds. Some data on this site comes from YAML file, and is merely an array of entries.

  • The only option is SCSS. Zola uses several conventions for it, and I am fine with those. I really-really don't like SCSS, I prefer LESS. No idea why is SCSS so popular. Maybe just because it used to be "the new big thing". SCSS also is too verbose and has a really weird imports system. There are isolated modules, which is good, but there is no way to reexport things even, which is just weird.

  • Tera template engine the thing uses sucks. It lacks dynamic, too verbose and some parts of its syntax are just weird. It works good for me, tho

  • It either minifies HTML - or leaves it unchanged. No option to pretty-print HTML. Why would I need that? Well, because Tera templating engine sucks. Its flow control instructions leave a lot of spaces and line-breaks - it is just designed this way. Want to define some variables on top of your template? Well too bad, you end up with some empty spaces in your HTML.

  • It always minifies CSS. There is no option to disable that. Minifying does not make much sense nowadays, my site will always remain infinitely small and blazingly fast compared to, say, google website (fun fact: opening a something "as simple as" google search page gets your browser to download about 3MB of various resources, and all one normally needs on that page is the search field. This site completely takes is less than 3 mb in a zip archive).

  • There seems to be no way to override some variables in zola's scss. So if I was, say, to generate two versions of my scss (the "light" theme and the "dark" theme, for instance) - I got no option to do so. This looks like be the first major issue with zola for me. Of course, that's not zola's issue - more like an issue with sass-rs library it uses, but stuff like that is why I might consider switching from zola to something else (maybe back to the generator I wrote even)

I want things to remain as open as possible, for some passerby to be able to read the source if they want to. Same applies to HTML actually.

Housekeeper

Eventually It came to writing a small tool-set I wrote in node to mitigate some of zola's limitation and do some house-keeping - format HTML, make the entire thing portable by replacing links with relative links, and then archiving it, the archive link is on the home page, - so you can even read this site offline (why would you anyway? but you can)

The house-keeping tool is ugly and slow. Zola takes less than a second to assemble the entire site, my tool takes another couple. Being fast and efficient is one of zola's main selling points - well I don't care, I want my HTML tidy.

However, the house-keeper is optional and I try to remain this way. Once there is something important zola doesn't allow me to do - I will probably move from it. It will be relatively easy because all the actual content of the site is in a separate "content" folder, and it is mostly generator-agnostic.

Perhaps, that point will be chirp, as zola does not allow custom RSS feeds and custom pagination for data formats, and I don't want to use JS for that and definitely do not want each "post" there to be a separate file.

Nevertheless, even if I am to write a custom static site generator again - I will know exactly what are my requirements.

Content formats

Most of my life whenever I've developed a website - almost every time it was some sort of CMS or CGI. The data was stored in some database, encoded in some format with special symbols and escaping and stuff. Now I'm using markdown for sources of most content of this website. I've tried to use markdown for CMS too - even on wordpress, there is a plugin to write content in markdown format, but it makes much more sense as a set of files.s

Markdown, well, just makes sense: it is plain text that can be copied and pasted and allows fore some basic markup, but unlike html and whatnot it is also readable as a simple text file. It is also sort of standard - can be compiled not only to HTML but also something else.

Then there is the "template" - a set of html files with some special markup, and zola replaces that markup with the html it generates from markdown.

Then, several aspects are in YAML format. I have used JSON previously, but YAML feels way more alike to markdown - I like to think of it as "markdown for structured data" - it is easily readable and requires no additional escaping or special symbols, so it is (and it is more important) easily writable also.

For example, books and albums sections of this site are mostly in YAML format, as well as Chirp. Even nav menu on top is now in YAML format - so no need to rely on zola's automatic generation and its sorting rules.

nav.yml describes the menu on top

Other section of this site, "chirp", has its source as a YAML array. It is actually nice to have all the list of my "posts" in front of me, as a simple plaintext file.

To be frank, I used to hate YAML because it feels like one of those trendy hipster programming languages or something - no delimiters, no brackets and spaces are significant. But now, when I use it for structured content (not structured data) it feels as perfect as can be.

Lesson learnt: YAML is perfect for writing content (not for data representation)

For YAML files I use JSON schemas. I generate these JSON schemas from typescript definitions (because JSON schema is awfully verbose and it is pain to write and maintain). Node package ts-json-schema-generator has all I need to build the schemas.

I use the schemas to not make too much checks in templates (too much logic in view files just feels bad), and also for the content to be consistent - to force myself to, say, fill in the date, title and url in every record.

Consistency

Things change. I change. My preferences and opinions on things change. I update and will update some pages of this site - with new details or removing obsolete details.

The thing I am after, however, is some degree of consistency. I will try my best to not change the links of this site (so the link will be alive as long as the site is alive, even if its design or engine changes).

The thing I learnt here is to always hard-code links (paths) for every page when my data is all stored in files. So if my generator tool changes (other one may have a different conventions) I can somehow retain the data in a semi-automated manner. And also, this guarantees paths won't change even if I decide to change file structure again.

I hate it when I make a bookmark and then return to it a year later only to see the site has undergone a redesign and the article is still there somewhere, but under some other SEO category now or something.

Tools

I use git to store the site contents. I make all the changes and commit/push them to git. Then I simply SSH to server, pull and build the site there (there's a bash script for that just in the repo). I could automate it of course to auto run on push to a specific branch, but I don't want to over complicate things - CI setup, web hooks and all that jazz... Nah, I better just SSH and run a single bash script every time I mean it to be built. The easier everything is - the easier it is to set up again if something goes wrong.

Because of git approach - I can be sure the last version of the site is always present in git, some sort of fail-proof back-up.

To work with git I've been using lazygit lately. Because it is awesome. And also I am lazy, so fits me perfectly. Oh, also it is terminal-based. And it is in scoop, homebrew and there is a debian repo of course.

LazyGit

To write most of the content I use Visual Studio Code. Could be any text editor, but VSCode has a nice set of extensions (yaml jsonschema validator, prettier is integrated and some other stuff) and I use VSCode in my everyday work anyway.

I format markdown and yaml files with prettier with proseWrap: always

The principles

I am thinking on a list of rules I want to set for myself on this.

  • Text-first. It is tempting for me to add a lot of meaningless "engaging" "content" here, add some images and vids and whatnot. Add background music maybe (it used to be a common trend in the past to have music on your site). Add more bling-blings! Not gonna do it. I want the thing to be boring, but informative and full of sense.

  • Honesty. It is tempting to add click-baity things here, too. It is surprisingly hard to resist the urge to write stuff in a cryptic manner. Trying to fix it every time I stumble upon it. I don't think I'm genuine and a "good" guy. But becoming one is my goal...

  • English. English is not my main language. I am also quite illiterate and tongue-tied myself. I use a lot of parasite words. Frankly, my english sucks. However, English is a truly "international" language: it can be read and understood by people from all across the globe. After all, trying to express my thoughts helps to learn the language better, too.

  • Biases. I am pretty stupid. That's the main reason I'm going to change texts on this site as my opinion changes. Will try not to write about things on which my opinion changes too often, too.