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

50 years of Microsoft

Fri, 04 Apr 2025 06:00:00 +0000

Whether you Like it or not, Microsoft is the world’s largest software maker that, through methods both fair and questionable, has managed to get its products installed on the vast majority of computers on the planet.

Today, Microsoft turns 50, and it feels like just yesterday when its two founders, Bill Gates and Paul Allen, assured Ed Roberts that they had a BASIC interpreter ready for his Altair 8800, the first truly personal computer, despite having never seen the Altair or the 8080 processor that powered it.

Qualche anno dopo, i due dimenticarono di dire a Tim Paterson, l’autore di QDOS (Quick and Dirty Operating System, ovvero il Sistema Operativo [fatto in modo] Veloce e Sporco) per il processore 8086, che avevano promesso ad IBM un sistema operativo per il suo imminente Personal Computer, che era basato proprio su quel processore. Così acquisirono i diritti di QDOS da Paterson per un tozzo di pane, lo ribattezzarono MS-DOS e lo licenziarono a IBM, catapultando Microsoft e sè stessi nell’olimpo dell’informatica e dei profitti.

A few years later, the two forgot to mention to Tim Paterson, the creator of QDOS (Quick and Dirty Operating System), that they had promised IBM an operating system for its upcoming Personal Computer, which just so happened to be based on the same 8086 processor. So, they acquired the rights to QDOS from Paterson for next to nothing, rebranded it as MS-DOS, and licensed it to IBM, launching Microsoft (and themselves) into the pantheon of computing and massive profits.

And then there were the blatant copies of the Windows user interface (right, Apple?), the borderline-intimidatory tactics with companies licensing Windows, and the use of Internet Explorer as a weapon to crush competition from other operating systems. Then came the lawsuits, the departure of Bill Gates, Steve Ballmer’s clowning around, the colossal failure of Vista, and the equally disastrous Windows 8.

But today is a celebration, so let’s play nice and clink our glasses.

– Image generated by Microsoft Designer AI.

Still, even on a day of celebration, I can’t help but ask Microsoft one question.

You’re celebrating half a century of history, you’re famous across the entire solar system, and you’re certainly not short on cash. So how is it possible that, for such a milestone anniversary, you couldn’t hire a half-decent artist to design better wallpapers than these?

P.S. Even those who stick to their smartphones can feast their eyes on this, or this, or even this and, if that’s not enough, on this.

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