From melabit to melabit: Jekyll, installation and basic configuration

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. 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!

1. With Jekyll’s extensive documentation, the real challenge is distinguishing useful guides from time-wasters. ↩

2. From now on, I won’t mention Windows, as the necessary instructions are identical to those for Linux. ↩

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

4. Of course, this is irrelevant for vim or emacs masters. ↩

5. When I say “often,” I am not exaggerating at all. ↩