5 min read 0 comments

I really, really like Jekyll. I still like it even after finishing my coding bootcamp where I learned React. I like React, but for maintaining my website, I think I will stay with Jekyll. And now that I know more about web development, it was less intimidating to take on adapting another theme.

Yes, I changed my theme again for the nth time. But this wasn’t too different from the previous theme I used, which was the Cayman Blog. The current theme, Simple Blog, is also created by Lore Pirri and also based on the Cayman theme.

What I learn every time

Every time I change my theme, I learn more about Jekyll such as:

  • understanding the Jekyll variables
  • how to use Liquid templating language
  • how to define attributes in the config.yml file, especially setting defaults for the front matter
  • how to make includes and layouts and how to use them

Start by testing the theme in a new folder

To use the theme, I tested it first by cloning the repo into a new folder in my local environment (I use macOS). I’ve already installed Jekyll by following the instructions in the Jekyll docs. I then followed the instructions in the readme file of the repo. (I actually create a new folder, git initialize it, and define its remote named upstream as the repo of the theme, then do a git pull upstream master to “clone” the repo. I then define another remote, which will now be the origin and push to this remote to deploy on GitHub.)

Most of the instructions for using Jekyll themes are not that easy to follow because, more often than not, one will hit an error along the way. In my case, I wasn’t able to run the script mentioned in the instructions, so I resorted to running the commands in the script manually. For example, instead of running script/bootstrap in the command line, I ran the commands I found inside the script, gem install bundler, then bundle install, without knowing the effects of this. Then, I did bundle exec jekyll serve, which I found in the next script to run script/server. The theme rendered perfectly in my localhost.

Early deployment is key

I then proceeded to change the config.yml file, the about.md, and the contact.md file, according to the instructions. One thing I learned however, before totally changing the files, was to deploy first. Deploying it on GitHub pages as early as possible saved me a lot of time and sorrow. It helped me decide whether the theme is usable or not, because it may render well in the localhost, but not in production.

Upon deploying the barely modified theme, I found out that it doesn’t build in GitHub. Unfortunately, no reason for the build failure was given, so I tried to figure it out blind. But after a while, I learned by trial-and-error (deactivating some features in the config.yml) that the Facebook feature is the reason for the build failure on GitHub. Not really wanting to use the Facebook feature for now, I decided to remove this from the config.yml file. Only then was deployment on GitHub pages successful.

Customize the theme of current site

This is actually the painful part. In the past, since I only have a few files in my site, I actually delete the repo and create a new one. This isn’t a good practice, I don’t think. This time however, I didn’t want to create a new repo. The next thing I did was also not a good practice. But my site isn’t that big still. I edited most of the files instead and created new ones that didn’t exist. The bad thing about the process was that the URIs to the old posts were modified, making most new users land on a 404 page if they come through Google (my site had been present for a while).

I moved on knowing this consequence and changed the templates according to my needs. One thing I didn’t need from the theme was the language translation feature. I only wanted to do an English language site. In the end, I just left the language feature in the codes, but removed it from the render (omitted the line that uses the includes html file that renders the translation of the page to another language), instead of modifying all of the codes to remove the variables and codes that refer to the language of the page.

Upgrade the Jekyll version if possible

At this point, I’m looking to add some features to my Jekyll site, such as perhaps a search bar. To get this, I looked at the available plugins for Jekyll. From this process, I found that I will have to upgrade the Jekyll version from 3.1 to at least 3.6. I decided to just upgrade to the current version, 3.8.2. To do this, I created a new git branch in my local environment. In this branch, I deleted the Gemfile.lock file. On the Gemfile, I removed the version number (or probably better to just indicate the current version number). I also edited the .gemspec file and edited the jekyll version there as well. I still don’t understand what this file really does at this point, however, so I might need to check that out.

After updating the Jekyll version in the files, I ran bundle install, then bundle exec jekyll serve. I got lucky and everything rendered right. Time to merge the branch to master. One thing I want to point out after doing a bundle exec command after upgrading the version is that now, I don’t have to do bundle exec commands after this. I only needed to do jekyll serve because the current Jekyll version (globally) now has the same versions of dependencies as the theme’s dependencies. Awesome.

For Jekyll v. 3.5 and higher, however, the gems configuration option had been depracated. So I went ahead and changed the configuration in the config.yml and Gemfile accordingly, using the instructions found in the Jekyll docs. Eveything is good again.

I heart Jekyll

All in all, I am satisfied with how I was able to use the theme and learn more about Jekyll in the process. It seems at this point that the next language I’m going to learn is Ruby.