Philosophy of hand-written HTML

On writing html by hand, bad abstractions, transpilation, writing for an audience, and importance of strong contexts.


Abstraction, at it's core, is "the action of removing or separating something from a context".

For example - the web's markup language is HTML, yet most sites don't have a guy writing all the HTML tags by hand. We tend to use WYSWIGs, or blog generators, or write in languages that only later produce HTML.

To abstract is to hide. Hiding, sooner or later depending on your use case and the quality of the abstraction, will become an obstuction.
When the abstraction doesn't work for you, you can either (a) accept it, or (b) look for escape hatches.

Most decent abstraction layers provide their escape hatches. Take the C compiler as an example which takes C source code and spits out assembly. Most cases, you'll be happy with the assembly the compiler produces, but in the edge cases you really need to write assembly, you can use __asm__.

Escape hatches are not a hack - they're a feature, as long as they aren't overused. I found myself overusing the escape hatches of markdown -> HTML blog generators.

The goal of this blog is self expression. Best way to express with creativity is through lack of constraints. Using markdown took away my freedom to do cool stuff like this. Or build highly interactive yet extremely simple pages like my CSS Grid Walkthrough.

Could have I done similar stuff in a decent markdown blog generator like hugo? Sure. But achieving the same things would require me to learn the escape hatches and keep them in memory. I found the congitive strain of doing that repeatedly a bit too much, taking away the fun from the process.

Distinct context

Your writing style, the content, the effort put into it, everything depends on the context you're writing in. I write differently if I know it's going to be read by an audience. My brain automatically starts a background process that constantly evaluates what is written from my imagined perspective of a reader.

I like to take my personal notes in addition to the blog posts. I also take them on a computer. I used to take them in markdown as well as run a blog via markdown, all in the same directory. In retrospect: it blurred the line between the two, leading to a distasteful mixture of the two styles.


Translation layers come and go. Your static site generator from today probably won't be as hip in 10 years. In theory, moving between them should be simple, but they rarely spit out legible HTML. And if you customized your markdown capabilities or want to move to a different markup language (asciidoc, org mode), chances are you'll have to reimplement all the customizations all over.