Theme Upgrade!

A year ago I published my first blog post. So much has changed since then, and I have been using just the default Jekyll theme the entire time. I wanted something more, so I decided it was time to give the site a bit of an upgrade.

Why a New Theme?

I liked the default minima theme. However, it made the site look basic. I want the opportunity to grow and evolve the look and features of the blog as the content grows and evolves. I wanted to be able to make these changes with simple configuration updates and not intensive custom solutions that require css or code.

I also wanted to learn more about how themes, Jekyll, and ultimately Ruby works. I have a bare minimum knowledge of this platform, and I think it is time to learn more about the tool I am using.

Research

I was not sure how to get a new theme for a Jekyll site. I started the search on the internet. The Jekyll site turned out to be a good place to start. The first link on the site is a link to GitHub with the topic jekyll-theme selected. It lists theme repos created by developers, that are sorted by popularity.

The top two starred were themes for academic purposes. As you might have guessed, this is not an academic site. I figured these might contain features, that I do not need, and not prioritize features that I would use. I scrolled further.

The third one was called Minimal Mistakes. It has over 13k GitHub stars and a commit less than a few hours old. So, definitely a popular repository that still gets updated. Two important criteria. I scrolled quickly through screenshots and list of features. I decided to install it and give it a test run.

Installation

The documentation site supporting this theme has a very fleshed out installation section. Following the directions was simple. There was only one error I had to debug throughout the process. It was due to my lack of familiarity with the Ruby ecosystem. Not an issue with Jekyll or Minimal Mistakes.

error: uninitialized constant Gem::Net::HTTP.

I tried just installing the net-http through gem. Same error.

I begrudgingly asked GitHub CoPilot “why is this not working???”. It recognized that my bundler version was 2.6.9 but in my lock file it was 2.6.7. I am not the versioning got into an inconsistent state.

After, installing with the bundler version that matched what was in my gemfile.lock. I ran

 bundle install

Success!

Then

 bundle exec jekyll serve

The site loaded with the new theme on localhost:4000!

Configuration

The first configuration decision I would have to make was the skin. The minimal-mistakes theme comes with a few different “skins”: air, aqua, contrast, dark, dirt, neon, mint, plum, and sunrise. I tried a few… dark, neon, and sunrise. I ended up sticking with the default skin, because I find it easy to read black text on a white background. In the future, I would like the ability for a visitor to toggle light and dark mode.

The next was, search! All you need to do to implement site search is add the following line to _config.yml:

search: true

The default search implementation is lunerjs. A light-weight search engine akin to Solr. A few test queries is enough to satisfy me. Minimal Mistakes themes provides good documentation on swapping out search providers if you are unsatisfied. I might look into that as the blog grows.

I decided to swap out the about page for a simple author profile sidebar. I like the author profile on the homepage and on each post instead of having it hiding on an about page. I also struggled with filling out an entire about page.

There are a boatload of other configuration choices to make. I might add comments or expected read times on the posts. Luckily, this setup allows me to easily add and remove features.

But It Works Locally!

I had an issue deploying to GitHub Pages. It was a classic case of me not properly reading the documentation. When I initially tried to deploy out the new theme, I got the following error. TLDR: the theme minimal-mistakes-jekyll could not be found.

Luckily, the documentation provides an easy fix. In short you have to load the theme as a “remote_theme”. This works by GitHub downloading the theme gem and applying it to your site. You can see in the build here it downloads and applies the theme at build time.

Takeaways

I am really happy with the new theme, thanks to the developer Michael Rose! It has been a fun year building the blog, and I look forward to continuing it.