Design decisions behind this blog

Since I want this blog to be useful for other tech savvy people, as well as to explain most of the tech related decisions that I make and why I make them, I thought that explaining how this blog is made could be a good starting point to show which kind of content will you find here.

In the first place, you’ll find that I am a proponent of simplicity and minimalism, but not because of some kind of religion or cult. Nowadays most websites are developed in an absurd way. What could be achieved with a little HTML and CSS, is sought to be done with complex and bloated Javascript frameworks. Instead of looking for simplicity in the solutions, we look for speed in the development, sacrificing the quality of the software that is produced. The web is, in its essence, really simple (although it could be simpler; look at Gopher). With HTML you define the content and with CSS you give it some style. This would be enough to develop most web pages, many of which are simple business landing pages, business or personal blogs. Want an e-commerce site? Surely you could do it with almost no Javascript. Your grandmother wants to start a blog and has no idea about computers? I’m convinced that a CMS could be developed with simple HTML and CSS, relegating the processing and database to the backend. If such a CMS existed, you would just install or deploy it on a hosting provider and give your grandmother access to it. What about complex web applications like Google Maps? My point is not that you should stick to this or that technology, but that you should ask yourself: do I really need all this crap to do something as simple as displaying some characters and colors on the screen?

I won’t elaborate much more on this, as I consider this to be a complaint that has been running around the net for a long time [1] [2] [3] [4]. As suckless.org points:

For short: There is an industry which is specialized on extending the resource usage to display just some characters on your display. Millions of jobs are based on outputting HTML in an inefficient way. Look at PHP and all the techniques to extend its “scalability”. It is not scalable, it’s a prototyping language. Not to mention all its syntactic irregularities. Nowadays classes on classes on classes with getter and setter functions define buttons which can be stripped down to just a simple character string. The web is the practical example why corporate software development does not work and never will. It only ruins our environment, sanity and many brains which could be used for the better of humanity.

In addition, making the blog simple has the advantage that it will run on almost any hardware, on any HTTP server software, reduce the resources visitors have to use to render the page and reduce the impact on bandwidth.

Tools

When I was thinking about the tools I would use, my first thought was to write all the HTML by hand. The idea was to design a header, a footer and a CSS style file. The content would go between the header and the footer, written by me in raw HTML. Believe me, it’s not that tedious. Many people don’t know it, but most of the time you don’t have to close the p HTML element and the same occurs with some other tags. Also, in lots of text editors, you can program snippets, so you don’t have to type all the HTML tag structure every time.

The problem with this approach was that I wanted some features that were difficult to do it in that way: the ability to transform the page to other formats or to comply with other protocols (maybe Gopher or Gemini), to have an RSS feed and other features. One alternative was to use a framework focused on simplicity, like Hugo or Zola. When Zola was running as the preferred candidate, I found ssg and I got amazed with its simplicity and effectiveness. It’s a simple script, with less than 250 LoC, that relies on find(1), grep(1), and lowdown or Markdown.pl. With ssg, I only need a src/ directory with files written in Markdown format and a dst/ directory where the HTML files will be located. I also have a _header.html and _footer.html files in src/, along with other files that will be literally copied into dst/. The src/ directory tree looks like this:

src
├── about.md
├── contact.md
├── _footer.html
├── _header.html
├── index.md
├── images/
├── post1.md
├── post2.md
└── style.css

Then, I run:

ssg src dst 'title' 'http://domain.tld'

And HTML content is generated in dst/. Very easy. Now, instead of writing HTML, I write files in Markdown, which is imo an easier format to write in. I can also convert .md files to other formats with many existing tools. Okay. The RSS problem remained unsolved. I was writing a simple sh script to transform the index.html to a feed when I found, again in Roman Zotolarev’s site the rssg tool. When the index.html or index.md complies with an specific format (parsing rules are stated in the previous link), then rssg outputs an RSS feed when executed:

rssg src/index.md 'Title'

Simple, isn’t it? And what about sending files to the server? I use rsync:

rsync -rv --exclude=".*" dst/ [email protected]:/var/www/

Note that I use --exclude=".*" because ssg uses a .files in dst/ folder for managing incremental updates. I don’t want that file (nor other dotfiles that could be unintentionally moved to dst/) to be sent to the web server.

Finally, I made two scripts, generate and upload, that wrap the above commands. The workflow is very simple, write post -> generate -> upload and the scripts work in almost any Unix like system (the only real dependencies are lowdown and rsync, but can be found on most operating systems). The only change I made was to the date command that is used in rssg, because it varies according to the type of OS (for example, the one that is part of GNU Coreutils is not the same as the one that can be found in OpenBSD).

Appearance

I wanted a style that met my preferences. Among them was to be retro and not overloaded with elements. I also wanted to minimize the size of the CSS file so that visitors wouldn’t have to waste bandwidth for my aesthetic whims.

It was important to me that the site was accessible to everyone, so I tried to comply with WCAG. To make sure of this, I used tools like WebAIM Contrast Checker or the color selector integrated into Firefox’s developer tools. If the font or other elements are too small or too large, the page responds very well to zooming, so that everyone can adapt it to their desired size.

A dark version of the theme is pending for the future. For now, addons like Dark Reader work fine.

The page is perfectly navigable in text-based browsers such as Lynx or w3m.

The appearance may vary, since changing the appearance is very easy, due to the simplicity of the blog and the fact that I only have to make small changes to the CSS file. I wouldn’t like to stick to the same style forever.

Compatibility

As far as the HTML tags are concerned, I have tried to make the site compatible with most browsers and in most of their versions.

The CSS I believe is compatible with most browsers, although I haven’t worried too much about it, since the page works perfectly without CSS.

Hardware

For now, the server is running on a cheap and low resource (1 vCore, 2 GB RAM, 20 GB storage) VPS in a hosting provider. In the near future, I plan to run the server on simpler hardware, such as a Raspberry Pi or any SBC, powered by solar energy. In this way I’m doing the planet a small favor and showing that it doesn’t take too many resources to host something as simple as a blog.