Just, why?

I'm glad you asked.

Why put the effort into publishing long dry articles on the interwebs? From the outset, it sure feels like throwing words into the void and might be a more accurate indication of madness than speaking to oneself on the streets!

Now that my carefully crafted Straw Man is ready, we can start refuting it. The single most important reason why I think that this endeavor is not completely worthless is the following:

The process of putting my thoughts into structured words usually leads me to more thorough research, better retention and preservation of the whole experience.

Well, those are three reasons, but they all revolve around the idea of "better learning for me". Let's pick them apart.

More Thorough Research

I don't want to be wrong, and there are a lot of people out there with a great deal of knowledge about the topics I want to cover. Everyone knows what happens when someone is wrong on the interwebs!

I'm perfectly happy to hold half-truths about many things. After all, I can't afford to think critically about how exactly my fridge works. I have some ideas from my Thermodynamics courses but I don't know all the details. And that's okay! There is only so much I can learn about the world.

But, if I choose to explain fridges in public, I better know exactly what I'm talking about. Otherwise, I would be contributing to all the misinformation out there, and what's worse, someone will call me out on my nonsense.

Better Retention

In general, I will only remember the things I pay close attention to. And the more I wrestle with a subject, the better I will recall the nitty-gritty details. This leads to a more accurate understanding.

Preservation Of The Experience

This one is pretty self-documented. There is a copy of this website on my local machine, a GitHub repository as well as Cloudflare Pages. Say the probability of my drive going haywire is 0.5. While that of GitHub or Cloudflare burning down is a much safer 0.1. Then the odds that every trace of my rants is wiped off the interwebs would be 0.005 = 0.5%, and I could even half it once I finally do backups (famous last words).

I like those odds.

Attempt at Web Design

Knowing some front-end development doesn't mean I can make pretty UIs. So, since I insisted on a little personal touch, I had to tread carefully. My general idea was to apply the only Design Principle that actually works: KISS.

To limit the number of things I could wreak havoc with, I had to set some ground rules:

• Use a fixed palette of colors.
• Keep geometry flat.

Then, I looked for some inspiration. I had always liked the "Metro" design language in Windows Phone, so I looked into that. Turns out that it's based on the Swiss Style.

The Swiss Style

Source

I recognize the bottom-left shapes as (nuclear) missiles, the center-most forms as people holding hands in unity, while the big "nein" (German for "no") makes the whole thing clear:

We are united against nuclear weapons.

This poster drives its message home using very simple elements:

• The word "nein" uses the ubiquitous sans-serif Helvetica typeface, with a large font size that's hard to miss.
• Geometric shapes are simple and universal; many cultures can recognize them.
• Space is divided into four logical grids: source, "nein", people, and missiles, which gives the poster structure.

Needless to say, I tried applying these principles to varying degrees of success. I'll let the reader be the judge of the outcome.

Implementation

Sigh. It's time to talk about code.

I wanted to "control" the UI myself, so I couldn't possibly settle for any of the hacker-friendly, legacy or mainstream off-the-shelf solutions.

Over-Engineering?

At first, I wanted to generate the site from Markdown with Zola as a Nix derivation, then build a Docker image from it, which I can "easily" deploy to my VPS.

All for a blog.

Later on, I realized that this was silly and that I wanted to go for it mainly as a chance to deep dive into Nix. There goes that excuse. This was when I turned to Cloudflare Pages instead.

It's simple. All I had to do was link the GitHub repository and specify that it's a Zola project. Done.

Well, not really. I encountered an annoying problem where Cloudflare's images were not compatible with the last 6 versions of Zola. The issue was reported in October 2021 and is still unsolved at the time of writing.

I mainly chose Cloudflare because they already manage my DNS and I like to limit the number of web dashboard UIs I have to navigate.

Getting Sassy

Writing SCSS was most of the work, at about 400 lines. Though I didn't make use of the advanced Sass features but rather used it for the easier syntax. The process was smooth because SCSS is a superset of CSS and Zola supports it out of the box.

In the past, my CSS got very messy, very fast. So, once again, I set some ground rules:

• Avoid long chains of nesting in selectors. Things like div p img are hard to reason about.
• Avoid Classes when IDs will do.
• Avoid IDs when element tags will do.
• Use relative units (like rem) everywhere.

While crude and unsophisticated, these rules mostly served me well.

Website Layout

Grids! Grids! Grids!

Seriously, CSS grids are much easier to work with (cough flexbox, cough cough) when you don't have to handle dynamic elements. You can simply say what the layout looks like in your head.

#blog-page {
    display: grid;
    grid-template-columns: 25vw 50vw auto;
    grid-template-areas: "sidebar content empty";
}

This defines the layout of the current page, on sufficiently wide screens at least.

Choosing Fonts

After trying many sans-serif fonts, I eventually settled on Finlandica, "The official typeface of Finland". I don't know if using it in such a context is appropriate, as I'm not a Fin, but I like its sense of orderliness too much to give up on it.¹

Its strong and compressed shapes embody a traditional virtue in Finnish culture: honest and resilient determination – “Sisu”. Ink traps like cuts from a blunt ax, makes the typeface reliable in small sizes and gives it character in large headlines. Like the Finnhorse it’s a breed suitable both as riding horse and workhorse. In the spirit of “Jokamiehenoikeus” this typeface is Open Source. ― finlandica.fi

"Jokamiehenoikeus" means Freedom to roam and manifests as a public right to access the wilderness. It's written into law in many countries in Northern Europe. An interesting take on Open Source. But it's mixing apples and oranges: access to the Linux kernel doesn't imply potential damage to the "common" resource, simply because there are many copies to go around, which isn't the case for physical public spaces.

Next, I needed a monospace font for code blocks. This wasn't particularly hard, as I already had a favorite programming font: Iosevka. That's it, I'm not justifying the choice, I just happen to like it.

Syntax Highlighting

Zola can either directly embed syntax colors in the resulting HTML, or output CSS classes instead. The former solution is not an option, as I want to have both light and dark themes later on.

This leaves us with CSS classes. Now, I'm pretty sure it's possible to create a custom theme to fit my 11-color palette, but I couldn't find any documentation of the various classes involved (things like z-keyword and z-constant), nor was I in the mood for hunting them down.

So, I side-stepped Zola and used the highlight.js library instead as it had much richer documentation. Though I should eventually figure out how to use Zola's classes since that would be more efficient.

Still, I have a good excuse for not doing it right now:

"Programmers waste enormous amounts of time thinking about or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3%." ― Donald Knuth

So it goes.

I had to write JavaScript

It turns out that the pulldown-cmark crate has broken footnotes, and so does Zola. There were two small annoying issues:

• The elements don't render properly.
• There is no link from the footnote back to the text.

The first one is nothing a little intrusive CSS can't fix. But the second issue requires changing the HTML of the page sometime after generation, preferably on load-time. And no, I'm not going to statically patch it in an ad-hoc way².

Anyway, here's the JavaScript:

// The DOMContentLoaded event fires when the initial HTML
// document has been completely loaded and parsed, without
// waiting for stylesheets, images, and subframes to finish loading.
document.addEventListener('DOMContentLoaded', (_event) => {
  const references = document.getElementsByClassName('footnote-reference')
  // For each footnote reference, set an id we can refer to from the definition.
  // If the definition had id 'some_id', then the reference has id `some_id_ref`.
  for (const reference of references) {
    const link = reference.firstChild
    const id = link.getAttribute('href').slice(1) // skip the '#'
    link.setAttribute('id', `${id}_ref`)
  }
  const footnotes = document.getElementsByClassName('footnote-definition')
  // For each footnote-definition, add an anchor element with an href 
  /// to its corresponding reference.
  // The text used for the added anchor is 'Leftwards Arrow with Hook' (U+21A9).
  for (const footnote of footnotes) {
    const id = footnote.getAttribute('id')
    const backReference = document.createElement('a')
    backReference.setAttribute('href', `#${id}_ref`)
    backReference.textContent = '↩'
    footnote.append(backReference)
  }
});

Software is amazing, isn't it?

Conclusion

The way things are set up, I can simply make a commit on the main branch, and the site will be automatically built and deployed to Cloudflare Pages. Pretty neat.

I hope to document my learning journeys through this small platform.

If you don't already have your personal corner on the interwebs, I hope this post inspired you to get one. Though I cannot promise that I or anyone else will actually read it.