Linux on Melabit

Goodbye dc, welcome luka: a new RPN calculator for the Terminal

Sat, 09 Aug 2025 06:00:00 +0000

The Reverse Polish Notation (RPN) is a method for performing calculations without the need for parentheses. RPN was popularized in the ’70s and ’80s by Hewlett-Packard (HP), that used it in all its scientific and financial calculators.

When using calculators from rival Texas-Instruments, which all relied on parentheses, it was easy to lose track of how many parentheses had been opened or closed, often forcing users to re-enter the entire expression from scratch. Those who used an RPN calculator didn’t have these problems, although they had to overcome a small initial learning curve to get used to the new notation.

Today, physical calculators are rarely used, and almost everyone prefers to use an app on their phone or computer. However, there are still some die-hard nerds who refuse to give in to the graphical interface and insist on using the Terminal. Why? For example, because it’s much easier to enter numbers and complex operations with a keyboard than to press the glass keys of a virtual calculator.

– Image generated by Google Gemini.

A bit of history

Poland gave us Nicolaus Copernicus, Fryderyk Chopin, Joseph Conrad, Marie Curie, Arthur Rubinstein, and Stanislaw Lem. But it also gave us Jan Lukasiewicz, a mathematical logician (and philosopher) who, about a hundred years ago, invented a mathematical notation that did not use parentheses.

In this Polish notation, all operation symbols ( $ + $, $ - $, $ \times $, $ / $ ) precede the numbers they apply to. The same applies more generally to mathematical functions, such as $ \sqrt{} $, $ \sin $, $ \cos $, $ \exp $ (operators) and the numbers or variables (operands) they act on.

For example, $ 3 + 4 $ is written in Polish notation as $ + \ 3 \ 4 $, while $ (5 + 2) \times (5 - 2) $ becomes $ \times + 5 \ 2 - 5 \ 2 $.

For many years, this remained just an odd idea, because the benefit of not using parentheses didn’t seem to outweigh the unusual and more difficult-to-read notation.

Then, in the late ’50s, John McCarthy brought back Polish (or prefix) notation for LISP, one of the most influential programming languages of all time,¹ developed with the goal of being applied to the development of programs in the field of nascent artificial intelligence.

In fact, prefix notation not only greatly simplified the implementation of the LISP interpreter, but also made it possible to represent both code and data in the same form, an invaluable feature for a language designed to make computers intelligent. But better not to digress.

Reverse Polish Notation

But the real breakthrough came by inverting the order between operands and operators, that is, by writing the numbers first and then the operations to be performed on them, so $ 3 + 4 $ becomes $ 3 \ 4 \ + $ and $ (5 + 2) \times (5 - 2) $ becomes $ \ 5 \ 2 + 5 \ 2 - \times $.

This Reverse Polish Notation (RPN) was discovered and rediscovered at least three times in twenty years, but it only became popular in the early ’60s when Friedrich Bauer, the inventor of the concept of stack and one of the developers of the ALGOL computer language, and Edsger Dijkstra, famous for solving the “shortest path problem” and for a thousand other things, took up the concept again, because it reduced access to memory, which at the time was scarce and slow, and ensured that all operations were performed within a well-defined memory area (the stack), that was therefore easier to manipulate.

The advantages of RPN for performing mathematical calculations were so evident that HP used it in practically all its scientific and financial calculators, at least until the early ’90s. The development of larger memories and much bigger displays made it possible to easily view and modify the entire entered operation – not just the last number entered – thus reducing the necessity of using RPN.

A calculator in the Terminal

Those who wish to use a traditional calculator in the macOS or Linux Terminal have an almost mandatory choice: bc, the basic calculator, that has been a part of UNIX since 1975, a full 50 years. The current version, available on Linux and macOS, has been completely rewritten, but the original was just an interface for dc (desk calculator), one of the oldest utilities present in UNIX and even older than the C language.

And dc was… an RPN calculator. A choice that confirmed HP’s intuition: RPN notation was more efficient and easier to implement, and therefore also ideal for the limited-resource computers of the ’70s.²

Today, RPN is no longer a choice forced by hardware limitations, but rather a choice driven largely by convenience. Once you’ve spent half an hour learning to use it, you discover that it’s really much more convenient to perform calculations with this notation than with the traditional algebraic notation.

And then, maybe, there’s also a certain pleasure in going against the flow: in a world where everyone conforms to the dictates of (real or presumed) social media influencers, using an RPN calculator becomes a way to stand out, to feel different, almost a declaration of intellectual independence.

dc is still available on Linux and macOS and can be used in the Terminal, but it’s quite a hassle, its fifty years clearly show. The results of the operations are not visible unless you explicitly print them on the screen with p. The stack isn’t visible either, unless you explicitly request it with f. Negative numbers are indicated with an underscore _ and not with the usual - sign, so that $ - 4 $ must be written as $ _4 $. And so on.

But starting (almost) today, there’s dc2, or rather, luka.

The 21st-century RPN calculator

Since a few weeks we have a new RPN calculator for the macOS and Linux Terminal, initially called dc2, in homage to the venerable, now over-50-year-old calculator.

However, dc2 sounded too much like a rewrite of the original, while this is a completely new project, written from scratch in C. It therefore deserved its own name, luka, in honor of Jan Lukasiewicz, the inventor of the Polish notation (see the box above).

Compared to dc, luka is truly from another century, and it shows as soon as you start trying it out. It’s interactive, it shows the content of the stack at all times, it has a history of the operations, variables, a concise but complete inline help, a crystal-clear manual page (if only there were many more like this!)

And luka is also made in Italy. At a time when national identity is exalted for mostly trivial reasons, it’s nice to see something that really deserves to be valued.

The program currently has a small bug related to the display of the history, but the author crunches code much faster than I write words, so it’s very likely the bug will be fixed ASAP (vacations permitting).

Evolution of the code

The development of dc2/luka has been incredibly fast. Behind the project is Davide Mastromatteo, known among his pen pals as @mastro35 and author of the excellent blog The Python Corner.

In just a few days, Davide went from version 0.1.0, which was perfectly functional but had a still-raw user interface,

to version 0.2.0, with a much clearer view of the stack, the ability to use degrees and radians, and to change the number representation format, as well as a more compact help.

Version 0.3.0 introduced the history of operations and a further revised help,

while version 0.4.0, which coincided with the program’s name change, brought us variables and several new keyboard commands, as can be seen in the first two images of this post.

Using luka

Installing luka on a Mac or Linux is a breeze, at least for those who use homebrew (and those who don’t should start doing so immediately)

brew install mastro35/homebrew-mastro35/luka

Otherwise, just download the latest release of the source code, unzip it, and run

make clean && make

from the Terminal, obviously after navigating to the directory that contains the source code.³

Needless to say, anyone who has make and a C compiler installed on Windows can also compile luka on that operating system.

I almost forgot: soon there will be packages for Linux, in both deb and rpm formats, and who knows, maybe also aur. Perhaps even an installer for Windows.

There’s little to add about using the calculator itself. Those familiar with RPN will feel right at home and quickly use luka’ to its full potential. Those who don’t know RPN might be tempted to try it, if only to try firsthand how much more convenient it can be to perform calculations with an RPN calculator compared to a traditional algebraic one.

There are countless guides to RPN, but unfortunately, they are all oriented toward explaining its use with a physical calculator, such as the now legendary vintage HPs, or with graphical emulators for Android or iOS.⁴

Compared to these guides, there are some differences to consider. The main one is that, lacking physical keys, luka (but also dc) requires you to press ENTER each time to insert a number or function. Some function names are also different, as are the commands for managing the stack or for saving and retrieving variables. For example, luka uses store and load for variables, while physical or emulated calculators generally use keys named STO and RCL (but if the author reads this post, maybe he will change them 😂). However, apart from these tiny details, the underlying logic doesn’t change.

For my part, I tried in every way to make luka crash, and never succeeded. I tested it with factorials of absurdly large or small numbers, divided by zero, performed the infamous$ 0 / 0 $ and then asked to calculate the reciprocal of the result. But no matter what, luka always returned the correct result. In short, the quality is definitely there.

Conclusions

Trying luka costs nothing. It installs (and uninstalls) in a few seconds, works on macOS, Linux, and, for those who want, even on Windows. The results it produces are exact (and this is the most important thing). The developer is skilled and open to suggestions. In short, it’s an ideal tool for anyone who wants to perform calculations from the Terminal.

Sure, it’s a niche tool, aimed at a select group of sophisticated users who appreciate RPN notation and are not afraid of the Terminal. But that’s also what what gives it its unique charm.

And then, what about the beauty of seeing a program evolve before our very eyes, maybe even participating in its development with suggestions or criticisms?

And beyond that, there’s something special about watching a program evolve right before our eyes, especially when you can join the development with your own suggestions or feedback.

And one of the few languages, along with FORTRAN and COBOL, to still be alive and well. ↩︎
Not by chance, one of the most efficient programming languages ever is FORTH, which is based on a stack and uses RPN. ↩︎
What, you don’t even have make? Then hurry up and install homebrew! ↩︎
For iOS, I recommend without hesitation PCalc Lite or, even better, the full version Pcalc, which costsbout as much as a sandwich and a small bottle of water at a café. Alternatively, WP 34s, which manages to compact everything onto a single screen, or i41CX, perfect for those who once dreamed of having one. ↩︎

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. ↩︎