Jekyll on Melabit

A year of melabit.com

Wed, 31 Dec 2025 06:00:00 +0000

2025 was a turning point for this little blog. Leaving the comfort zone of Wordpress.com was neither easy nor painless, especially when I discovered that once the site was online, Jekyll was slow, too slow to be usable.

Thankfully, Hugo saved the day, although there are still many details to be ironed out, first and foremost the website’s graphic design.

– Image generated by Google Gemini.

Managing posts in two different languages is not easy, but it is worth it, as posts in English allow to reach a pool of users that would be unimaginable if I only wrote in Italian.

The main concern with the new site is the near absence of comments on posts. I don’t know if it’s because they’re too complicated, too long, or both. The fact is that the lack of comments is really worrying. And this is despite the fact that there are a good number of visitors and that on average 5% of them spend 15 minutes or more on the site. Maybe in the end they’re too exhausted to comment, who knows!

Needless to say, I never use AI tools to write the posts. At most, I use them to look up a few technical terms when I can’t remember the Italian equivalent (for instance, I always forget that Tab in Italian is Scheda, not Linguetta). Sometimes I try to use AI to improve the flow of a few sentences, but it’s almost always a waste of time. In the end, the text sounds so flat that it’s better not to write it at all.

However, I admit that I use AI for the initial translations. I need it mainly to save typing time, even though it then takes quite a while to refine the result and make the translation more fluid and natural.

I also often use AI to generate the images at the top of the posts. In this case, I have no choice. While I’m not bad at writing, I’ve always been second to last in the class when it comes to drawing and graphics, and only because the last one was really terrible. So I’m doing you a favor. But even with Google’s much-celebrated Nano Banana, it took a lot of effort to convince it to generate the image for this post, with the right text, the real homepage, and so on. Anyone who says that Nano Banana is so smart that it understands what you want right away is telling you lies.

If all goes well, 2026 will bring some new developments. I’m not sure in what order, but revising the graphic theme is definitely at the top of the list.

Stay tuned! In the meantime, best wishes for 2026. May it be a year full of good things and happiness for everyone!

Jeeeeeekyll? No, Hugo!

Sat, 24 May 2025 00:00:00 +0000

As I was writing about my transition from WordPress to Jekyll, I knew I had to prepare for another change.

From a technical point of view, Jekyll is a fantastic platform: it is easy to program, has impeccable documentation, and works perfectly during the development phase, with a limited number of pages and test posts. But, as I experienced firsthand, when Jekyll is asked to handle a real site with hundreds of posts, performance drops dramatically and response times become unbearably slow (and quite embarrassing, too).

In the late ’90s, it was normal to wait several seconds for a webpage to load.¹ But today, we’re used to pages that load instantly, so having to wait three or four seconds is unacceptable.

A high price to pay

Before I started working on the new site, I was well aware that Jekyll was slow. However, this slowness was always attributed to the site generation phase, which is performed sporadically and can be automated. And that was exactly what happened: during development, with a few dozen posts, I could regenerate the site in 10–20 seconds, quite annoying, but not dramatic; now it takes 15 minutes to regenerate the entire melabit.com.

What I didn’t know was that the generated site would also suffer from the same problem, which became evident as soon as I finished the development phase and started working with all the posts.

At that point, I was still convinced that optimizing the code and images and applying an aggressive caching would mitigate the issue. And in any case, I had gone too far to turn back. However, I soon realized that this strategy wasn’t enough, and that a radical rethink was necessary. So I started looking around.

Alternatives

Static site generators are like Linux distributions: there are too many of them, and in most cases it’s hard to understand why they even exist. At the moment, Jamstack lists 366 of them, while Static Site Generators counts nearly 500. Most have been abandoned, maybe because nobody was using them, or because the developer lost interest in continuing development. Let’s say the interesting ones are a dozen or so, maybe a few more.

Among these, I considered Bridgetown (very briefly, I admit), which is derived from Jekyll and therefore, at first glance, seemed like a natural evolution. However, I realised that few people use it, there are few plugins and even fewer themes. If Bridgetown is derived from Jekyll, how could I be sure that it didn’t suffer from the same slowness issue? Better to stay away and stick with the original.

Another candidate was Middleman, which is developed in Ruby like Jekyll. But Middleman is designed to generate plain websites, and you need a specific extension to make it support typical blog features, such as lists, taxonomies, feeds and comments. Also, the templating language is ERB (Embedded Ruby), which is a sensible choice since it’s integrated within Ruby. However, it meant having to relearn everything from scratch.

Long story short: in the end, the only serious candidate was… the good old Hugo.

Looking for speed

Many years ago, I wrote a post about Hugo, finding it interesting, but crippled by documentation that calling poor was being generous.²

However, its quality is not in question. Unsurprisingly, Hugo consistently ranks at the top of all the charts evaluating the quality of static site generators, just like Jekyll.

And Hugo has a real ace up its sleeve: it’s fast. In fact, it’s blazingly fast!

I can’t say whether Hugo is truly the world’s fastest framework for building websites, as claimed in the slogan at the top of its homepage. However, I have verified firsthand that Hugo can generate this entire site in under a minute, 15 times faster than Jekyll. Most importantly, the generated site is fast and responsive, exactly as you would expect from a modern website. That puts everything else in the background.

Hugo

So starting today, melabit.com is moving to Hugo, with a new design³ and trying to keep all the features of the Jekyll-based version. The first of these is the [Comma-based commenting system]https://melabit.com/en/2025/03/05/from-melabit-to-melabit-managing-comments-with-jekyll/), which after the transplant worked practically on the first try.

The permalinks have changed and now explicitly indicate the language of the post, which is a more rational approach. The feed has changed too. For now it’s the old RSS, but at some point I’ll check whether it’s possible to add ATOM.

Right now, the search function is based on Google, and will not work until the site is indexed again. Pagination needs to be revised, as does the logic that shows the featured post in the list of all posts. But these details can be sorted out later.

Because of how my mind works, I’d love to go into the details of how I modified Hugo and the chosen theme, but I’m afraid it would be boring, in particular after all the very detailed (but now almost useless) posts I wrote about Jekyll. I’ll think it over. In the meantime, if anyone is interested in knowing more, feel free to say so in the comments.

– Image generated by Google Gemini.

But you could at least distract yourself by watching the images appear one line at a time on the screen… 😂 ↩︎
Not much has changed since then. One of the (few) posts I can recommend without reservation is this one on managing context and variables in Hugo. It’s a very technical read, but essential for learning the basics needed to modify and extend Hugo. ↩︎
I’m not thrilled with the design, but it’s the best I’ve been able to come up with so far. ↩︎

From melabit to melabit: hosting Jekyll

Tue, 18 Mar 2025 06:00:00 +0000

– Source: Scott Rodgerson on Unsplash.

As promised (or threatened?) in the last post, this post is dedicated to exploring the available options for hosting a Jekyll-based website (or any other static site generator), whether for a personal blog like the one you’re reading, a professional studio, or a small business website.

I could summarize this in two lines and only refer you to what I wrote 6–7 years ago (here and here), but so much time has passed that a proper update is needed.

For those interested in reading the other installments of my transition from WordPress to Jekyll, below is the full list of posts that have been published:

Introduction

I’m not a professional developer, I don’t know much about web development, and I consider myself just a hobbyist when it comes to server and network management.

The thoughts shared below are purely personal reflections, shaped by years of experience and experimentation in managing computing systems – some more complex than others – and web services, both still active and long gone (sadly, more than one). I hope these insights will be useful to anyone considering similar solutions, but those looking for professional answers should turn to someone with deeper expertise.

Why using a Mac isn’t a good idea

As I mentioned last time, I find it impractical to use a Mac as a web server for a Jekyll-based site (or, more generally, for any website, whether static or dynamic).

The reason is simple: for a site with moderate traffic, a Mac is overkill – an unnecessary waste of resources.¹

Development is a different story (I used a Mac for that myself). Having a UNIX-based system with a polished graphical interface, powerful yet user-friendly editors, and tools that streamline coding and debugging is invaluable.

What about an old Mac lying around, why not repurpose it to serve my site?

An old Mac is still great for writing, managing emails, browsing the web, video conferencing, making music, learning to code, and much more. Even better if you install a recent version of macOS using Open Core Legacy Patcher.

But using an old computer as a server, keeping it on 24/7? Personally, I wouldn’t do it, it just doesn’t seem reliable enough. And even if you wanted to try, you’d run into the same broader issues I’ll discuss in the next section.

Why doing it yourself isn’t worth it

Instead of a Mac, we might consider using a PC, perhaps one of those slightly older but still capable mini-PCs, available for just over 100 euros, like the Lenovo M95q or the HP 800 G3. Another option could be a Raspberry Pi 5, though unfortunately, it’s no longer as budget-friendly as it used to be, at least if we plan to use it as a regular desktop computer.

As I mentioned years ago, once you install Linux on these mini-PCs, they become perfect “for learning how to manage a web server and the associated Linux system, or for experimenting with different CMSs or static site generators before deciding which one to use for your website.”

You don’t even need to connect a keyboard and monitor, as everything can be done from the Terminal via ssh. For those who prefer a graphical interface, remote access is easy with Chrome Remote Desktop or with one of the many remote access services we’re all familiar with these days.

But can we use these mini-PCs to run a “real” website, one that needs to be online 24/7?

In my opinion, no.

A website needs a fixed public IP address, and in Italy only Fastweb offers this for free, but under certain conditions. Other providers either don’t know what it is or require special contracts, which are of course more expensive than regular “home” or “business” plans.

I know, there are dynamic DNS services. But the ’90s are long gone, and today I would never trust my web services to a volatile service with unpredictable IP update times. Besides, if you want any level of reliability, you’re going to have to pay for it. At this point, is it worth it?

Another issue is sudden internet or power outages, perhaps due to street work or because your colleague or partner decided to turn on all the air conditioners at once or run the washing machine, oven, and hair dryer at the same time.

Sure, there are UPS devices, but if we’re away from the office or home, even the UPS will eventually run out of power, and our server will shut down.

And let’s not forget the security issue, the inevitable and constant attacks from countless idle youngsters with nothing better to do with their time. If we’re not already security experts, are we really willing to delve into matters far beyond our skill set?

What is worth doing yourself

If you want to do it yourself, the best option is undoubtedly to use a virtual machine on one of the countless cloud services, from UpCloud to Digital Ocean, or Heroku and Linode (now Akamai Cloud), not forgetting the big players like Amazon AWS and Google Cloud (and yes, there’s also Microsoft Azure). If you’re hesitant to buy American right now, here’s a list of European cloud providers.

A virtual machine on the cloud is inexpensive and doesn’t have any of the drawbacks listed so far, except for the security issue, which, however, is at least partially managed by the service provider itself.

Even more secure, and completely free, is to use services like GitHub Pages, which automatically regenerates and publishes the site on github.io every time a linked Jekyll-based repository is updated. The related documentation is very detailed, so there’s no need for me to add anything further.

What I have done

I am a user like many others, and the solution I have adopted can be a good example of how to manage web hosting efficiently and relatively cheaply (which is always a plus), without compromising on service quality.

This site is hosted by Shock Hosting, a hosting service I have been using for years, with a great support service. Actually, I’ve had very few problems over the years, and they’ve always been minor, like paying a bill twice by mistake, but every time the support response couldn’t have been faster.

The basic “Low Shock” plan at $2.99 per month offers unlimited disk space and data transfer, with no artificial speed limits (which few competitors offer). This plan is more than sufficient for a static site, but also for a site based on WordPress or other CMSs (based on my direct experience). The higher plans are identical to the basic one but allow hosting more domains, and switching between plans only requires opening a ticket and a short wait.

The domain name is also managed by Shock Hosting and costs 12 dollars per year (one dollar per month), which is the standard cost for a .com domain.

Of course, Shock Hosting is just one of countless hosting services available, although I find it hard to beat in terms of price/quality ratio. In any case, before making a choice, I recommend paying close attention to the terms of service, as most providers impose more or less strict limits on disk space or data transfer. Others may offer very attractive prices for the first year or the first few months, only to raise them significantly later. If you can test how their support works before committing, that’s a big plus.

Otherwise, choose a service that allows you to pay monthly or quarterly so you can carefully evaluate whether it meets your needs. You can always choose to pay at longer intervals later on.

Avoid like the plague those services that offer massive discounts if you commit for two, three, or more years, or even for… eternity. Nothing on the internet lasts forever; in fact, the so-called eternal services are often the first to disappear. And if that happens, you’ll ve lost everything you paid for in advance, so much for saving money!

The hosting service alone is not enough for melabit.com/posts/en because it doesn’t support running comma to manage comments. The simplest solution would have been to switch to a virtual server, still on Shock Hosting, but I don’t like simple solutions. Besides, the hosting service offers several advantages that I didn’t want to give up: it handles web server management and site security, performs backups, renews the SSL certificate, provides analytics, and much more. All of this is worth far more than the few euros per month it costs.

Just as I was thinking about what to do, I came across this post, and I decided to give the German kitchen a try by purchasing a virtual server from Hetzner. To run comma, the base CX22 plan is more than enough. For less than 5 euros per month, it offers a machine equivalent to the base plan from Shock Hosting, which costs twice as much. The virtual machine is powerful enough that I can also generate the site on it and then transfer the result to Shock Hosting using rsync.

When I chose Hetzner, the ongoing trade war between the U.S. and Europe was only in the minds of the gods, but in hindsight, it turned out to be a wise decision. If I ever lost access to my US-based hosting service or if the cost became prohibitive for a European, it would take very little effort to move everything to a safer location. Bye bye, USA.

Let’s do the math

In this post, I’ve written about why I don’t think it’s worth it to run a website on either a Mac or a PC. But is it at least economically viable to do so?

Let’s start by calculating how much I spend per month for melabit.com/posts/en. Hosting costs me 3 euros, and the virtual server costs 5 euros. That’s a total of 8 euros per month, which adds up to 96 euros per year. I should also add the cost of the domain, but that has to be paid anyway, so I’ll leave it out.

Now, let’s assume I’m stubborn and insist on using a mini PC or a Raspberry Pi to manage my site. Say the barebones computer costs around 100-120 euros. Then, I need to add a decent SSD and a sufficient amount of RAM, which adds at least another 60-100 euros (for the Raspberry Pi, the RAM is fixed and can’t be upgraded, but instead, I’d need to buy a case, a power supply, a practically mandatory heatsink, and an NVMe SSD adapter, again totaling about 100 euros).² Then, I’d also need a UPS, which will add another 100 euros.

The total comes to about 300 euros (give or take 30-40 euros), roughly the same as what I spend in three years. But there’s no guarantee that a mini PC, or even worse, a Raspberry Pi, will last three years of uninterrupted use. Maybe today the fan breaks, tomorrow the power supply, the SSD starts acting up, or the UPS batteries die. In short, even financially, it’s not really worth it.

Trust me, the cloud is much, much better.

In theory, you could dedicate an entire Mac to a website that gets a lot of traffic. But in this case, you need a truly professional solution; doing it yourself is not an option. ↩︎
Staying close to the lower limit of 160 euros seems really difficult to me. ↩︎

From melabit to melabit: managing comments with Jekyll

Wed, 05 Mar 2025 06:00:00 +0000

As noted in the last post, Jekyll does not have a built-in commenting system, but its themes often allow comments to be managed by connecting to third-party services such as Disqus and similar platforms.

The problem with these services is that they can stop working overnight (as happened last year with Muut, which no longer even has a website), or they have opaque usage policies and user data collection practices.

Another issue, which is far from negligible, is that most of these services require users to register before they can comment. Registration is useful for filtering inappropriate comments or spam, but it also acts as a barrier for casual readers who just want to share their thoughts.

Then there is the problem of cost. Some comment management services are paid and not exactly cheap, take Hyvor Talk as an example, which costs 12 euros per month. A price that is more than reasonable for a professional site or a small business that wants to interact with its users – especially since these services often also handle newsletters and other promotional materials – but that is completely out of scale for a toy handmade blog like this one.

Looking for the ideal commenting system

My interest in comment-related issues began a year ago when, after the sudden shutdown of Muut, I observed the enormous work being done behind the scenes by Mimmo, MacMomo, and Paoloo to recover from Muut all the comments from Quickloox – one of the must-read blogs for anyone interested in Apple, Macs, and related topics – convert them to the format of the new commenting engine, and reinsert them neatly into the blog.¹

A few months later, I began working on my own transition from WordPress to a Jekyll, and the commenting system was one of the main problems to solve. With WordPress, this isn’t an issue, because comments are integrated and stored in the site’s database along with the text of the post. But with a static site, like the one generated by Jekyll, it is necessary to implement some mechanism to add comments, which by their very nature are dynamic objects.

In hindsight, I could have followed Mimmo’s advice and chosen Comma from the beginning. But coming from WordPress, using a database seemed like the most natural approach.

So I tried Cusdis, Commento, Commento++, Remark42, and Zooment, all database-based commenting systems.¹ I carefully followed the instructions step by step, I used Docker, I ran Linux virtual machines on the cloud, I tested services that are supposed to handle everything automatically, like Railway and Vercel. Nothing worked. There wasn’t a single commenting system that worked like it should!!²

I also ruled out all systems that rely on GitHub, such as Giscus, Staticman, or utterances. These are perfect for developers who already have a GitHub account, but impractical for casual readers who would be forced to create yet another unnecessary account. That left only one option. Comma, of course.

Working on Comma

And Comma it was. Comma is written in Go and is distributed only as source code. To compile it, we need a compiler for the Go language. On a Mac, the compiler can be installed by downloading the prepackaged package and following the instructions, or via the usual Homebrew with

$ brew install golang

Similarly, on Linux, Go can be installed by downloading a compressed file and extracting it into the usr/local directory, or using the package manager commands of our distribution,

$ sudo apt install golang
$ sudo dnf install golang
$ sudo pacman -S go

depending on whether we are using Debian/Ubuntu, Fedora/CentOS, Arch, or one of their countless derivatives.

Once Go is installed, compiling Comma is a matter of seconds,

$ git clone https://github.com/Dieterbe/comma.git
$ cd comma/src
$ go build

where the last command checks that the program compiles correctly. If everything is fine, we can run

$ go install .

which compiles the source code and installs the comma executable in ~/go/bin/ (as usual, the ~ represents the Home directory of the account we are using).

Before cloning the Comma repository, I made a fork in my personal account, but only because I wanted to tweak a bit the code a bit.

The first thing I did was to change the filename extension of the comments from .cmt to .xml (lines 67 and 105 of my comment.go file). Comma comments are stored as XML files, and there was no reason to use a non-standard extension. Also, this change makes it easier to open them with a text editor, which will automatically format them for better readability. A small convenience, but very useful during development. To further improve readability, I also added four spaces before each XML tag (lines 71-73 of comment.go).

Lastly, I removed the requirement to enter an email address when submitting a comment (lines 94-96 of main.go). My goal was to have a site free of any form of user tracking, thus avoiding many headaches related to GDPR compliance.³ In theory, this could pose some security risks, but do we really think that someone with malicious intent would enter their real email address?

For the frontend – i.e., how the user sees his new comment as well as the list of previous comments – I used most of the original code from the author of Comma, adapting it to work with Jekyll. To that I added Markdown support and filtering of potentially malicious code from comments. For these two features, I took a lot of inspiration from the code that by Mimmo, MacMomo, and Paoloo wrote for Quickloox.

As for the icons associated with each commenter, I chose to generate them with Jdenticon, probably because its symmetrical geometric patterns fit my personality better.

The final appearance of the comments seems quite pleasant and well integrated with the rest of the site, and the localization works well, even in small details like the more prominent thin line under “Add a comment,” that changes depending on whether the text is in Italian or in English.

All the frontend code is in _includes/custom/comma-comments.html. While I was at it, I also added a small JavaScript function to the post page (_layouts/post.html) that allows users to jump back to the top of the post with a single click. I originally needed it during development, but I believe it could be useful for readers as well, so I left it in the final code.

Putting all together

Once the comment system and the code to display them on the site are ready, we need to make everything work together. First, we need to create a folder to store all the comments,

$ cd
$ mkdir ~/comments

and start Comma manually,

$ ~/go/bin/comma ~/comments localhost:5888
$

telling it it to listen for new comments on port 5888 of the local computer localhost and save them in the ~/comments folder. The last step is to add a line to _config.yml to connect Jekyll to the comment server

#--- Comma comments ---
commentserver: http://localhost:5888

and everything should work on the first try.

If instead of a physical computer we are using a cloud virtual machine, we will need to replace localhost with the machine’s reverse DNS name (see the previous post). However, the exact steps depend on the service we are using, so I can’t be more specific.

On a real site, things get a bit more complex, for example, because one needs to use the secure https: protocol instead of simple http:, which requires proper web server configuration. But again, the details depend on the web server, the configuration of installed services, and so on, making it impossible to explain everything without writing a whole manual.

However, I can say for sure that a real website requires Comma to be started automatically, just like the web server that manages the site.

Assuming that the site is running on a Linux server (in the next post, I will explain why using a Mac as a web server doesn’t make much sense) and that Comma was installed by the user webuser, in order to start Comma automatically on every system reboot (as well as when the program stops unexpectedly), we need to run

$ cd /etc/systemd/system
$ sudo touch comma.service

which creates an empty configuration file called comma.service. We need to add the following lines to this file,

[Unit]
Description=comma backend server
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/home/webuser/go/bin/comma /home/webuser/comments :5888
Restart=always
RestartSec=1
User=webuser
Group=webuser

[Install]
WantedBy=graphical.target

making sure to replace webuser with the actual username of the user who installed Comma. Running,

$ sudo systemctl enable comma

activates the automatic startup mechanism, allowing us to almost forget about Comma’s existence. To manually interact with the service, we can use the following commands,

$ sudo systemctl status comma
$ sudo systemctl stop comma
$ sudo systemctl start comma

which are useful for checking the status of the service or manually stopping and restarting it. These commands are particularly useful during debugging, but can also be helpful in production, so it’s good to know they exist.

Conclusions

I had originally planned to end this long journey through the technical description of the new site here. However, while writing this post, I realized that a few words about hosting might be useful. And that will be the subject of the next post.

And not even a small database like SQLite! All these comment systems use heavyweights like MariaDB or PosgreSQL. ↩︎ ↩︎
If I were mean, I might think the instructions were wrong on purpose to push me to use their paid cloud solutions. But I am a good guy. ↩︎
I have nothing against GDPR. In fact, I think it is a very useful regulation, at least in theory. In practice, however, it does little to truly protect user privacy and ultimately becomes a not-so-useful bureaucratic burden. ↩︎

From melabit to melabit: developing a web site in Jekyll

Sat, 01 Mar 2025 06:00:00 +0000

After the first part dedicated to installing and configuring Jekyll, this second part of these annotated notes dives into developing a Jekyll site using a pre-existing theme. On the other hand, developing a theme for Jekyll from scratch is far beyond my expertise, but those who can do it don’t need to read these notes.

What do we want?

First, we need to have a clear idea of what the site should look like graphically and what features it should support. Do we want a personal blog with a simple list of posts? Do we want a more elaborate magazine-style site? Do we need a showcase site to present our business or a specific project? Do we want a photography or documentation site?

Once we’ve clarified the site’s “specifications,” we can look for the Jekyll themes in this site for Jekyll, or here, here and here (I can’t tell them apart by name because they are all called Jekyll Themes). The most patient among us can go through the themes one by one, while others may prefer to filter by the type of site they’re interested in and only look at those themes. In any case, it’s good to take note of the themes we like the most and try out the demo sites, when available. It’s useful to keep an open mind – we could find an interesting theme that doesn’t fit our original specifications, and it’s worth noting that down, too.¹

How a theme is structured

Now, it’s time to try some theme out. To avoid being too generic, I’ll describe the installation of the Mundana theme which, coincidentally, is the one I used for melabit.com/posts/en.

Like Mundana, most Jekyll themes that are not gem-based are installed by cloning their GitHub repository or downloading a compressed file (in which case, all the following parts related to git can be skipped). In both cases, what we install is both the theme and the actual site because, in Jekyll, there is no strict separation between design and content.

The first thing to do is install git on the computer. On macOS, it comes preinstalled, but it’s usually an outdated version, and as I mentioned last time, it’s always better to keep system tools separate from development tools. With Homebrew, installing the latest (or nearly latest) version of git on the Mac is a matter of seconds,

$ brew install git

On Linux, the process is similar, but this time we must use the package manager of our distribution. This means we need to execute one of the following commands,

$ sudo apt install git
$ sudo dnf install git
$ sudo pacman -S git

depending on whether we use Debian/Ubuntu, Fedora/CentOS, Arch, or one of their many derivatives.

As already mentioned, installing Mundana is done by cloning its repository,

$ git clone https://github.com/wowthemesnet/mundana-theme-jekyll.git
Cloning into 'mundana-theme-jekyll'...
remote: Enumerating objects: 324, done.
remote: Total 324 (delta 0), reused 0 (delta 0), pack-reused 324 (from 1)
Receiving objects: 100% (324/324), 4.12 MiB | 24.52 MiB/s, done.
Resolving deltas: 100% (116/116), done.

or by downloading and extracting the project’s zip file.

The developers suggest making first a fork on our GitHub account and then cloning from there. This makes sense if we plan to contribute to the code; otherwise, it seems like an unnecessary step. Anyway, those who know what a fork is don’t need further instructions.

Once the installation is complete, we can navigate to the Mundana directory and explore a bit (for clarity, all directory names end with a /).

$ cd  mundana-theme-jekyll
% ls -nhp
total 72
-rw-r--r--   1 501  20   398B Feb 12T19:58:00 404.html
-rw-r--r--   1 501  20   510B Feb 12T19:58:00 Gemfile
-rw-r--r--   1 501  20   1.7K Feb 12T19:58:00 Gemfile.lock
-rw-r--r--   1 501  20   2.0K Feb 12T19:58:00 README.md
-rw-r--r--   1 501  20   1.7K Feb 12T19:58:00 _config.yml
drwxr-xr-x  11 501  20   352B Feb 12T19:58:00 _includes/
drwxr-xr-x   6 501  20   192B Feb 12T19:58:00 _layouts/
drwxr-xr-x  11 501  20   352B Feb 12T19:58:00 _pages/
drwxr-xr-x  20 501  20   640B Feb 12T19:58:00 _posts/
drwxr-xr-x   5 501  20   160B Feb 12T19:58:00 assets/
-rw-r--r--   1 501  20   149B Feb 12T19:58:00 docker-compose.yml
-rw-r--r--   1 501  20   9.2K Feb 12T19:58:00 index.html

The Mundana directory contains two service files for RubyGems, Gemfile and Gemfile.lock, as well as the docker-compose.yml file, which is only needed if we run Jekyll inside a Docker container (which is not relevant here). Everything else is related to Jekyll.

Static pages go into the _pages folder, while all the more dynamic content, such as the blog posts that are updated more frequently, goes into the _posts folder. The content of static pages and posts can be written in either HTML or Markdown.

The _layouts folder contains files that generate the main parts of the site, such as static pages, blog post templates, or sidebars, while the _includes folder contains snippets of code that can be included in other pages, more or less like library functions.

These four folders, all prefixed with an underscore _, are processed by the Jekyll engine, which uses them to generate the actual HTML pages for the static site.

The assets folder, on the other hand, holds site content that Jekyll does not process, such as the CSS files that define the site’s design, the JavaScript files for interactive features,² and all site images. When Jekyll generates a site, this folder is copied as is, and the system automatically creates links to the various files.

Finally, the _config.yml file contains all the site configuration parameters, such as the site name and description, the links to the site’s logo and favicon, the required plugins, the pagination settings, and a list of files and service folders that Jekyll should ignore. The _config.yml file can become quite long and complex, so for simplicity, here’s just a small portion of the default _config.yml file for Mundana.

# Site
name: 'Mundana'
description: 'Mundana is a free Jekyll theme for awesome people like you, Medium like.'
logo: 'assets/images/logo.png'
favicon: 'assets/images/favicon.ico'
baseurl: '/mundana-theme-jekyll'

[...]

# Plugins
plugins: 
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-paginate
  - jekyll-seo-tag
  
[...]

# Paginate
paginate: 10

# Exclude metadata and development time dependencies (like Grunt plugins)
exclude: [README.markdown, package.json, grunt.js, Gruntfile.js, Gruntfile.coffee, node_modules]

Since we’re at it, let’s make our future work easier with a small modification to the _config.yml file, replacing the line baseurl: '/mundana-theme-jekyll' with baseurl: ''.

Almost forgot: plugins (and their dependencies) are also Ruby gems and are not installed by default, so we need to install them. First run

$ rm Gemfile.lock

to prevent conflicts between plugin versions listed in the Gemfile.lock file and newer versions that Ruby suggests to install. After that, run

$ bundle install
[...]
Fetching gem metadata from https://rubygems.org/............
Resolving dependencies...
Fetching jekyll-paginate 1.1.0
Installing jekyll-paginate 1.1.0
Fetching jekyll-sitemap 1.4.0
Installing jekyll-sitemap 1.4.0
Bundle complete! 4 Gemfile dependencies, 39 gems now installed.
Bundled gems are installed into `[...]/.gems`

that installs the actual plugins (and automatically regenerates the Gemfile.lock file with the newly installed versions of the plugins).

Testing Jekyll again

All that is left now is to test Jekyll again, this time with the theme we just installed.

$ bundle exec jekyll serve --host=0.0.0.0

The site will be quickly regenerated and will be available on our real machine at the URL http://localhost:4000. If we are using a virtual machine or a cloud server the port will still be :4000, but the URL will depend on the configuration of the machine (for cloud servers, the URL usually has a label like reverse DNS name or something similar).

Compared to the simple gem-based themes covered in the previous post, Mundana is clearly on a different level. At the top of the page are the four most recent posts, along with their images. In the center, a featured post is prominently highlighted against a contrasting background (for example, it could be the most recently published post). Below that, all other posts are arranged in reverse chronological order. On the side, a sidebar contains posts that we want to highlight.

If we replace Mundana’s default posts with our own, add the images, make two or three modifications to the _config.yml file, and within minutes we could have a site ready to go online, with all the posts neatly organized into well-structured pages (as you can see here).

When the default theme is not enough

A well-designed theme is very convenient and, as we’ve just seen, allows you to get online quickly with minimal effort. However, it may not fully meet everyone’s needs as it is.

For example, I wanted to create a multilingual site in both Italian and English – something that Mundana does not support by default.

Additionally, I wanted the site’s Home page to display a summary of the latest posts with thumbnail previews of the featured images, but didn’t want the thumbnails to appear in the individual post pages. Mundana handles the first requirement correctly, but not the second.

Another issue concerns pagination: the default pagination looks nice, but it displays a single horizontal row of links to all the generated pages. When there are too many pages, this row expands excessively, overlapping other graphical elements on the page or extending beyond the browser margins.

Lastly, Mundana natively supports the Disqus commenting system, but I preferred a self-hosted solution, to avoid reliance on third-party services that could change their terms of use or, worse, shut down unexpectedly.

Let’s get to work!

All the modified theme code is available on GitHub, at https://github.com/sabinomaggi/mundana-theme-jekyll-multilang.

Pagination

Let’s start with pagination. Since Jekyll version 3 (we are now at 4.4.1), pagination has been managed by the jekyll-paginate-v2 plugin. In Mundana, the pagination code is integrated into the index.html file and is quite simple, which can cause issues when the number of pages grows.

I moved the pagination logic to _includes/custom/paginator.html,³ making sure that the links only point to a subset of the available pages: those adjacent to the current page, the first and last pages, and an intermediate page calculated based on the distance of the current page from the first (or last) page. This approach allows pagination to work correctly even on very narrow windows or mobile devices.

There isn’t much to say about the code: starting from the current page, all other pagination elements are determined, dynamically generating the HTML code for each link. All the logic is written in Liquid, the templating language used by Jekyll. Liquid’s syntax is a bit peculiar and requires some workarounds with variables, but the important thing is that it works.

Actually, the most interesting part of the code is the first line, which dynamically changes the text strings based on the active language. But that brings us to the next section.

Multilingual support

Jekyll can handle multilingual sites using the jekyll-polyglot plugin, but it does not interact well with the jekyll-paginate-v2 plugin,⁴ so I needed a different solution.

Polyglot is very easy to use: you just need to add the plugin under the relevant section in the _config.yml configuration file and define two new variables for all the languages you want to support.

[...]

# Plugins
plugins: 
  [...]
  - jekyll-polyglot

[...]

# Polyglot
languages: [en, it, de, fr]
default_lang: en

To set the language of a post, simply add the lang: variable (e.g., lang: en or lang: it) to its front matter, and you’re done.

The front matter in Jekyll is a block of metadata in YAML format placed at the beginning of a Markdown (.md) or HTML (.html) file.

The front matter is enclosed by three dashes (---) and provides information about the page or post, such as the title, language, layout, and settings for customizing the page behavior. For example:

---
title: "Welcome"
layout: default
permalink: /it/
lang: it
---

When Jekyll processes the site, it uses the front matter to:

Define the template to use for rendering the page (layout: default).
Customize the URL associated with the page (permalink: /it/).
Set specific variables for that file, which can be used in layouts and themes (lang: it).

If a page or post includes the lang: it variable in the front matter, Polyglot can use it to apply content or styles specific to the Italian version of the site.

My idea was to manually emulate the behavior of polyglot. The first step was to define two new variables in _config.yml, that are similar to those used by Polyglot:

#--- Custom localization variables ---
# Polyglot does not work well with Paginate-v2
# define these two variables instead
locales: [en, it]
default_locale: en

I also added a new variable to the front matter of each page or post, which, following the same pattern as _config.yml, could be either locale: en or locale: it.

To simplify language management, I created two subfolders, en and it, inside the main _posts directory to store posts in their respective languages. This way, it is very easy to add the correct locale variable to each group of posts with sed.

Lastly, I leveraged a Jekyll feature: when Jekyll finds a file with a language indicator in its name, it treats it as another version of the original file (without the indicator), inheriting all its content but using the specific variables defined in its front matter.

In other words, if I have an index.html file that contains all the code for the Home page of the site, and I create a new empty index_it.html file, adding the locale: it variable to its front matter, the index_it.html file will inherit all the content from index.html, but will use the locale variable to localize the page for Italian. This mechanism is well documented in some pages I consulted, but unfortunately I can’t find the links anymore.

One last detail: when using pagination, the locale: it variable must be defined inside the pagination: variable in the front matter:

pagination:
    enabled: true
    locale: it

Therefore, all code that dynamically determines the language of a page must always check both the page.locale and the page.pagination.locale variables.

Of course, all text strings on the site must also be adapted to the selected language. To achieve this, there is a _data/translations.yml file containing English and Italian translations for all the strings used.

Needless to say, setting up the localization mechanism correctly took the most time during the development of melabit.com/posts/en. However, the way it’s done allows to add a new language in just a few steps: add the new language code to the locales variable in _config.yml, add another folder inside _posts, and include the language flag image in assets/images. Almost makes me want to try it… 😂

Thumbnails and comments

After dealing with localization, removing the thumbnail from post pages was easy. I just had to find the relevant lines of code and comment them out. Problem solved.

Comments, on the other hand, were a completely different story, even more complicated than localization. But that will be the topic of the next post.

For example, while writing this post, I came across this theme, which doesn’t match my original idea for a site but might have worked just as well (but I’m not changing now). ↩︎
Jekyll is a static site generator, but even static sites today require a certain level of dynamism to handle things like search functionality, comments, and more. ↩︎
I placed all the new code inside the custom folder to physically separate it from the original theme files. ↩︎
Since several posts from 4-5 years ago report successfully using both jekyll-polyglot and jekyll-paginate-v2, this may be a Mundana-specific issue. Alternatively, it could be an incompatibility that has emerged in the latest versions of Jekyll or of the two plugins. ↩︎

From melabit to melabit: Jekyll, installation and basic configuration

Tue, 11 Feb 2025 06:00:00 +0000

This post is not meant to be a detailed guide on installing and configuring Jekyll; for that, there are excellent guides listed below.¹

Instead, this post is a commented collection of notes I took while developing melabit.com/posts/en. They are the result of days and days of trial and error, changes in direction, and research to find the right command. These notes were useful for me to remember what I had done and how I had solved the issues that arose from time to time. They might be useful for you to get everything done more quickly and smoothly.

Installing Jekyll

To experiment with Jekyll, there is nothing better than using a virtual machine, preferably with a lightweight Linux server version. A good alternative is a virtual cloud server, even a cheap one, like UpCloud, Google Compute Engine, Amazon EC2, or similar. However, for serious work, it is much more convenient and faster to use a real machine, especially since following these instructions makes the risk of damage almost nil. Luckily, I had an old Mac available, which allowed me to try and retry, knowing that if any issues arose, I could easily reset it.

The best guide for installing Jekyll is undoubtedly the official one, with specific instructions for the most common operating systems.

The guide for macOS is well-done, but the installation requires Homebrew and a number of steps to be followed carefully. On Linux, the installation is much easier, while on Windows, the best approach is to install the Windows Subsystem for Linux (WSL) and then work essentially in a Linux environment.²

An important detail missing from the macOS instructions—but present in those for Ubuntu, FreeBSD, and other Linux distributions—is that before executing the final command gem install jekyll (or even before starting the Jekyll installation), it is advisable to add these lines to the ~/.bashrc or ~/.zshrc file (depending on the shell used):

#--- Install Ruby gems in the user account, e.g., in ~/.gems ---
export GEM_HOME="$HOME/.gems"
export PATH="$HOME/.gems/bin:$PATH"
#--- end ---

Then, execute source ~/.bashrc or source ~/.zshrc to activate the new environment variables (I usually just close and reopen the Terminal).

What are these lines for? They instruct RubyGems, Ruby’s package manager, to install all its gems,³ including Jekyll, in the user account instead of system-wide. This is a good practice as it separates the native Ruby installation within the operating system from everything we install ourselves, allowing us to fix inevitable errors without risking system integrity.

At this point, you can proceed with the actual Jekyll installation,

$ gem install jekyll

Immediately after, install another very useful gem, Bundler,

$ gem install bundler

which, inexplicably, is completely omitted from the macOS instructions.

To instruct bundler to install everything within the user account, execute

$ bundle config set --local path $GEM_HOME

Finally, if you are using a virtual machine or cloud server and your main operating system is macOS, install this gem,

$ gem install rmate

which will allow you to use TextMate, which I consider the best overall editor for macOS, to edit files remotely instead of using nano, vim, or emacs directly on the virtual/cloud machine (being a Linux server version, it lacks a graphical interface).⁴

Your first Jekyll site

After installing Jekyll, all guides suggest creating a new site with

$ jekyll new my-new-blog

which creates a new my-new-blog folder in the current directory. Moving into the new folder and starting Jekyll’s built-in web server,

$ cd my-new-blog
$ bundle exec jekyll serve --host=0.0.0.0

will allow you to view the new site at http://localhost:4000 if using a real machine. With a virtual/cloud machine, you should point the browser to the public URL provided by the server, always using port 4000.

This procedure is useful for verifying that everything works, and Minima, the default theme, is very clean and elegant. If Minima is enough for you, you can stop here, simply add a site title and content, and you’re ready to go.

However, this process gives only a vague idea of what Jekyll can really do since its features are tightly integrated with its themes.

Jekyll and its themes

Minima is an example of a gem-based theme, installed outside the site’s folder and theoretically easily replaceable with another gem theme, like the one shown below.

However, such themes are rare, generally minimalistic, and harder to modify or extend. Worse yet, they are often designed for outdated Jekyll versions and may not work with the latest ones.⁵

Most Jekyll themes instead come in a format that combines content and design within a single folder. This is very convenient when you find the right theme but makes changing themes later much more complicated.

Installing most Jekyll themes essentially means installing an entire pre-built site, then replacing the default posts and images with your own. Therefore, it is best to first choose a theme that suits your needs and then start customizing it.

But this will be the topic of the next post.

If you no longer like Jekyll

Then you need to uninstall everything. The modern way to do this is with

$ gem uninstall --all --ignore-dependencies --executables --verbose

or, for those who love compact commands

$ gem uninstall -aIxV

If you followed the initial advice of installing everything in the user account, no admin privileges are needed. Otherwise, you’ll have to prepend sudo as a penalty for your mistake.

After uninstalling all gems, you could also remove ruby and related packages using Homebrew on macOS or the package manager for your Linux distribution. But with today’s large disks, is it really worth the effort just to save a few MB?

Until next time

This post is already too long, so let’s end it here. The next post will dive into the actual development of a Jekyll site. See you soon!

With Jekyll’s extensive documentation, the real challenge is distinguishing useful guides from time-wasters. ↩︎
From now on, I won’t mention Windows, as the necessary instructions are identical to those for Linux. ↩︎
A gem is a program or a library written in Ruby that contains everything needed to run it or to develop new programs that utilize its functions. Gems are installed using the standard package manager, RubyGems, whose gem command allows performing all installation, update, and uninstallation processes for various gems. ↩︎
Of course, this is irrelevant for vim or emacs masters. ↩︎
When I say “often,” I am not exaggerating at all. ↩︎

From melabit to melabit: why Jekyll?

Tue, 21 Jan 2025 18:00:00 +0000

– Source: Jametlene Reskp on Unsplash.

As I mentioned in my last post, leaving the WordPress comfort zone wasn’t easy at all.

Going from focusing solely on writing something interesting – while a team of system administrators and web programming experts handled everything else – to having to do it all by myself was a massive leap.

It took quite some time to set up the new system, add missing features, and resolve the (many) unexpected technical issues. And let’s not forget that, in the meantime, I was still managing my regular work and trying to write a post now and then.

Thus, the primary need was to base this new blog on a stable and reliable platform, a platform that wouldn’t change every week or, worse, suddenly vanish because its developer got tired of tinkering with the project.

Having abundant, well-written documentation was also essential: clear guides for configuring the system and finding quick solutions to problems (which are inevitable) are a tremendous help, saving countless hours of frustration.

With these criteria, the choice was inevitable, and it was the same as many years ago: Jekyll.

Because Jekyll may have its flaws, such as the slow site generation and the bulkiness of the generated code, but it’s been around for 16 years. It continues to be regularly developed without dramatic overhauls (the latest release was in September 2024), and you can find guides online for virtually anything you might encounter when building a site with this platform.

After all, it’s no coincidence that GitHub chose Jekyll as the platform for generating sites directly from its repositories.

Back then, I was so convinced about Jekyll that I wrote all 482 posts of the blog on wordpress.com in Markdown, with a YAML front matter like the one used by Jekyll and saved images in folders named after the posts.

On WordPress, this wasn’t necessary because all I had to (and could) do was copy the text into a new post, add the images, and click publish (well, it’s a bit more complicated, but you get the idea).

However, having everything neatly prepared in the right_ format significantly simplified the transition from WordPress to a static site based on Jekyll. I just had to set up the basic structure, add the posts and images, and generate the site to have everything ready to go (again, it’s slightly more complex than that, but you get the idea).

If I hadn’t kept the original texts, I could have used a WordPress plugin to export the posts from WordPress to Jekyll. (It’s true, there’s a WordPress plugin for almost everything!) But the plugin doesn’t support comments, images are dumped into a non-standard directory and need to be moved, and all links have to be fixed… Ultimately, in my case, it would have taken more time to clean everything up than to start from scratch.

Now the foundational work is done, and all the main functions of the new site are more or less working. At this point, it’s easier to explore alternative—and hopefully more performant—solutions to Jekyll.

At the top of my list are Bridgetown, a Jekyll fork_ worth diving into, and Middleman, which intrigues me even if I’m not entirely sure why!

It will be fun.

From melabit to melabit: goodbye WordPress, hello Jekyll

Thu, 02 Jan 2025 06:00:00 +0000

– Image generated by the Microsoft Designer AI.

Eleven years ago, when I started writing in this personal space, I never imagined I would stick with WordPress.com for so long. WordPress.com is a convenient and reliable blogging platform, but it has always been ill-suited to my way of working. Over time, I learned to live with these limitations, but the idea of changing platforms never left my mind.

From the start, I had a clear idea of which alternative platform I wanted to use. A few years later, I revisited the available options and detailed the steps to transition in a long series of posts. Ultimately, though, I didn’t follow through, perhaps because I wasn’t fully convinced about the decision.

After all, leaving the comfort zone of a platform that has caused you zero problems over the years to embark on a new journey where you manage everything yourself is no small task.

A few months ago, however, Automattic, the company behind the open-source WordPress software and its related products, decided to share by default all content hosted on WordPress.com with “third parties.” Actually, this means sharing it with AI-powered text generators (think ChatGPT and similar tools) that are constantly hungry for new material to improve their training.¹ In that moment, my decision was made.

As if that weren’t enough, shortly after, Matt Mullenweg, WordPress’s founder, lost his temper, highlighting how, despite WordPress being the world’s most popular open-source content management system (CMS), the increasingly centralized and authoritarian control over its development threatens the platform’s open and transparent future.

And so, the die is cast! It took a lot of time and effort, but starting today, this little blog has its own home: melabit.com/posts/en, where I can experiment with much greater freedom than before. Let’s see how it goes.

The new site is still a work in progress. The basic structure is in place, but there will definitely be adjustments and improvements in the coming months. The very first thing to do is to expand the international section, which currently contains only a handful of posts, with several broken links or links to the original posts in italian. Additionally, I would like to implement a system for notifying users of new posts.

In the meantime, please don’t hesitate to flag any issues or poorly functioning elements in the comments.

For technical details and the transition process, stay tuned for upcoming posts.

Rest assured that all old content and comments will remain available on melabit.wordpress.com. At least until Mullenweg kicks me out… 🤣🤣🤣🤣🤣

While it is true you can opt out of sharing your content—and I did—it’s also true that you must explicitly choose not to share your data, rather than the other way around, which would be more logical. And even then, there’s no guarantee that your content won’t be scraped anyway. ↩︎