Introduction
At some point in time you will need to upgrade at least your version of Jekyll, and probably also the Jekyll Theme. This post describes how to upgrade Jekyll on Mac OSX installed under a Ruby version that in turn was installed using the Ruby Version Manager (RVM). Redoing the installation from scratch today (September 2019) I would probably have gone for a Homebrew and rbenv ]installation instead.
My intention was to also update the Jekyll Theme that I chose almost 2 years ago, So Simple. The changes between versions 2 and 3 of the So Simple theme, however, break all the customisations I have created to be able to host my diverse pages. I thus decided against updating the theme at this point.
Check and RVM version and PATH
If on Mac OSX, start by checking and upgrading the Ruby Version Manager. To check your present RVM version, open a Terminal and type at the prompt:
$ rvm version
PATH error
If command reponse reports a PATH error, the problem might be in your .bash_profile file in your home directory.
Easy mending
If $ rvm version returns an error, like for instance PATH is not properly set up, read the feedback at the prompt and follow the steps. The message PATH is not properly set up, can be solved by making sure that the PATH to the RVM binary is the very last path given in the .dot-file: .bash_profile or .profile. If both these .dot-files exists (both are in your home directory ~), you need to make sure that the path to RVM (export PATH=”$PATH:$HOME/.rvm/bin”) is the very last of the two. You can edit both .bash_profile and .profile using the command-line editor pico.
$ pico .profile
Retry checking the RVM version, and if the version is correct, go ahead and update as outlined above. If not try the forced update:
$ rvm get stable –auto-dotfiles
To invoke the installation close and open the Terminal or run the command $ rvm reload
Still not working mending
If the easy mending did not work out properly, here is how to edit directly in .bash_profile. The default installed PATH command related to RVM in my system was a single line:
[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" # Load R$
After searching a bit after how to handle the error, I changed the first line slightly and added two more PATH lines related to RVM. These three lines have to be the last entries in .bash_profile.
export PATH="$PATH:$HOME/.rvm/bin" # Add RVM to path for scripting (to manage R$
export PATH="$GEM_HOME/bin:$PATH"
[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" # Load RV$
After adding this line you have to stop the Terminal and then restart it to force the changes to take effect.
Upgrade RVM
If the response from
$ rvm version
is OK, you can self-upgrade RVM as outlined on the rvm official upgrade page:
$ rvm get stable
Upgrade Ruby under RVM
Before upgrading Ruby itself, note that your existing gems might become outdates and non-responsive. At some time, at least for security reason, you will have to replace outdated gems. There are several internet pages discussing how to go about updating Ruby and your gems, for instance this page on stack overflow.
To check out which versions of Ruby your (upgraded) installation of RVM hosts, open a Terminal and type at the prompt:
$ rvm list known
Under the heading # MRI Rubies the available versions are listed. To install one of the listed versions, type:
$ rvm install X.Y.Z
where X.Y.Z is one the listed versions. At time of writing this I tried installed 2.0.0. It took a very long time, also including upgrading Homebrew and pouring a multitude of new apps and updates while reporting caveats en masse. I understand very little of what happened.
Then I reran the same command ($ rvm install 2.0.0), and this time it worked without any error messages.
$ rvm install 2.0.0
Searching for binary rubies, this might take some time.
No binary rubies available for: osx/10.13/x86_64/ruby-2.0.0-p648.
Continuing with compilation. Please read 'rvm help mount' to get more information on binary rubies.
Checking requirements for osx.
[..]
Install of ruby-2.0.0-p648 - #complete
WARNING: Please be aware that you just installed a ruby that is no longer maintained (2017-04-01), for a list of maintained rubies visit:
http://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering
Please consider upgrading to ruby-2.6.3 which will have all of the latest security patches
As the version I installed was outdated and now longer supported, I again listed the available versions:
$ rvm list known
and sure enough ruby-2.6.3 was the latest. Thus:
$ rvm install 2.6.3
This installation went OK, finishing with the message that Ruby was built without documentation, to build it run:
$ rvm docs generate-ri
To check your installation (for details see the Jekyll instalaltion instructions):
$ ruby -v
Check your gem version:
$ gem -v
Check your gem environment:
$ gem env
Upgrade jekyll
You might need to exit and restart you Terminal session at this time. Then check your Jekyll version:
$ jekyll -v
Following the steps above in September 2019 I ended up with Jekyll version 3.8.6. But version 4 was released in August 2019. As this is the first release of version 4 I opted for not updating at this time. If you need to upgrade to jekyll 4.x.x the offical Jekyll Updgrage page have instructions for migrating between major Jekyll versions.
Upgrade repository gems
Before doing the upgrade described most of my repositories were at jekyll version 3.6.2, and I got some security warnings. To upgrade a reposiroy, simply open the Gemfile and alter the line:
gem "jekyll", "3.8.6"
to
gem "jekyll", "3.8.6"
Close and save the Gemfile and run the command:
bundle update
or
bundle update jekyll
Upgrade Jekyll Theme
After having upgraded Jekyll and its dependencies it was my intention to also upgrade the Jekyll theme (So Simple) I use for my pages. The change from version 2 to version 3, however, turned out to be a major overhaul. To the extent that I would have to create a completely new set of customisations. For me, upgrading the SO Simle theme would mean the same effort as migrating to a completely new theme. At this time I did not have the time for this.