I had my blog site for more than a decade now, but until now I was not putting
any effort or thoughts into maintaining my audience or promoting the site. It
was dormant for nearly a decade and I decided to rejuvenate it and start using
it as a platform I could leverage to share some ideas I think which are worth
sharing.

Before I embarked on the journey of renovating the blog site I needed to set
some goals and requirements up, so I would be able to assess my progress and
estimate how much effort is required. The primary goal is already known at
this point: I need a tool that would allow me to easily share my ideas, grow
and nurture the audience, and accumulate knowledge in one place over time.

I started to be increasingly unhappy with the Blogger) platform: they were
changing things and as the result parts of my blog became defunct, e.g.

in 2017, I lost the comment capability and did not have enough time to
investigate and fix it,

in 2018, my theme became incompatible with the new trends of the platform,

and so on.

Therefore, the first requirement became to self-host my blog site, so I would
have full control over the software that is supporting the site. This would
give the flexibility and determinism of how the site is configured and operates.

The downside for hosting the site myself is that it would require ongoing
maintenance cost (primarily calculated in the time I spend on the maintenance)
and with my quite busy schedule I was not sure that I could afford it on the
ongoing basis. So the second requirement became the low maintenance cost of
the solution. Preferably, I wanted to make changes only when I needed to
change site’s functionality.

I did some research and figured that a static website generator could be a
solution that addressed both aforementioned requirements assuming that I could
find a place where all underlying maintenance of the infrastructure and
application layer handled by somebody else (and, preferably, free of charge).

There are plenty of static site generators (SSG). According to some articles,
there are more than 400 different SSG at the moment, so the process of
selecting one that is right for you could be quite challenging. I decided to
define what I would like to see in the generator I could use and be happy about
it before I start shopping around:

should be written in one of the scripting languages that are widely adopted

This requirement comes from my desire of running that software on a
platform that is fully managed by somebody else (my initial thought was to
host the site in an AWS S3 bucket and generate the site using AWS Lambda
function)

should be lean with minimum dependencies for the generator itself

The more dependencies software has the more likely it is to get an
unexpected behaviour once one of the upstream dependencies make an
undesirable breaking change. I really wanted stability and to touch the
configuration in rare occasions only when I needed to change the behaviour
of my site and not in an adhoc response to an upstream breaking change.

should be extensible and should support a plug-in mechanism

I have a really high bar on what the final result should be, e.g. valid and
standard compliant HTML and CSS documents, semantic structuring, etc. In
order not to be limited by the generator I needed a way on how I could
influence the generation process without patching or tweaking the core of
the generator itself, since doing it this way would mean maintaining a fork
of the generator and as I mentioned above, it does not fit the second
requirement.

the template language should be flexible and should allow conditional logic

Over the years I worked with multiple template engines and I found that the
most comfortable engines are those that potentially allow you to break the
concept of separating design from code. Not that I recommend doing so, but
having such power gives you yet another flexible interface to express
yourself.

the architecture of the generator should feel clean, stable, and thought out

I do not know how to easily describe this, but my understanding of the well
engineered software is when its layout is simple to understand, structured,
yet easily extendable without introducing any invasive changes to the
structure, e.g. callbacks/hooks in the key transition points, so you could
hook the external code up and influence the logic, etc.

A bit more research brought me to the realisation that there is a trend in the
community and it has a name: Javascript, API, and Markup Stack(Jamstack).
The ideas behind Jamstack resonate with my vision on how I wanted to run my
blog, so if you want to understand the reasoning behind many choices I made
their website would be a good place to start reading about the approach.

After a lot of consideration the following three SSGs were the primary
contenders to become the engine of my blog site:

All of these three were aligned to the requirements, however I have an
indescribable allergy to NodeJS ecosystem and I prefer Python over Ruby, hence
Pelican was the first generator to spike with and to see whether we are a match
or not.

The more I worked with Pelican the more I was falling in love with the
software: with less than 600K of source code spread across just 15 files (with
a couple being redundant in my configuration) it is packed with features and is
very extensible through a plug-in system.

The next step was to create the templates (the collection of templates used to
generate the output is called a theme in Pelican). While I was spiking I found
a theme I somewhat liked (Brutalist by Matt
McManus), then I found a free theme that I liked a lot
(Striped by AJ), but that theme was just an
HTML/CSS/JavaScript concept which was unrelated to Pelican in any way.

Initially, I started to port the Striped theme to Pelican using the Brutalist
theme as the wireframe, but in the middle of that work I realised that despite
the Striped theme was posed as “a free, fully responsive HTML5 site
template” it was generated in a haste and was not that responsive as the
claim would make you think. There were lots of inconsistencies and no
overarching conventions on how things were structured within.

After a while, struggling to fix everything I was not happy with in Striped
theme’s code, I decided to take a different approach: I decided to re-create
Striped-like Pelican theme from scratch using Pelican’s default theme called
“simple” as the foundation.

The result (which is still an ongoing process) as you can see has some
resemblance to the theme I was taking inspiration from, but on the other hand
it is quite different and standalone in its own right. Up until some point I
was even retaining “Design by HTML5 UP” at the bottom of the left hand side
menu, but when I realised that almost nothing left of the original design and
layout, I removed it, the theme evolved much further that the inspirational
theme I started with.

This post is already getting too long, so I will conclude with the following:
I am going to publish a series of posts covering the development of this
website, the tips and tricks I learnt over the course of creating it, and the
infrastructure supporting the site and its deployment process in detail.

All blog posts related to these topics will be tagged with the “blog” tag, so
you should be able to find them easily (or even subscribe to the blog RSS feed
(you may need to copy the link into your RSS Reader) to get the latest updates
as soon as I publish them).