Undo gem-based Jekyll theme

Written on January 29, 2017

Unlike Jekyll’s suggested method of using a gem-based theme, I like to have my theme located entirely in my Jekyll project’s directory.

This is because gem-based themes often feels like a black box to me. I could go to its source and look over and try to override with files located in my Jekyll project, but often times it is easier to have the entire theme in my project’s repo and know exactly what each piece of code is doing.

While I see benefits to abstracting the theme from the source of a project e.g. separation of content and styles and having cleaner repo commits, I think the barrier to entry in creating themes is steep in the gem-based scenario and often unnecessary.

Thankfully you can revert a Jekyll project to use a theme found in its project directory over an existing gem.

First if you plan on basing your theme on an existing gem-based theme, you’ll want to copy the contents of the gem over to your Jekyll project directory.

If you’ve already installed the gem-based theme, you’ll want to first locate the contents of the theme. In macOS you do this by using the command bundle show x. Where x is the name of the theme. If you’re using Jekyll’s default theme, the command would be bundle show minima.

To open the folder in macOS you can run the command open $(bundle show minima) and a Finder window will automatically open to the location of the minima theme.

Once you’ve located your theme, you can copy over all the contents of the theme into your Jekyll project. That would usually be all the contents of the theme minus the README and LICENSE files.

Next you’ll want to remove any references of the gem-based theme from your Jekyll project’s Gemfile and _config.yml files.

Again using minima as an example in the Gemfile you’re looking for a line that starts with something like gem "minima".

In your _config.yml file you’ll want to remove a line that starts with theme: minima.

Finally, run bundle update from the command line within your Jekyll’s project folder.

Now every time you run jekyll serve or jekyll build, Jekyll will build the theme based on the theme files located in your project’s directory instead of a gem-based theme.

Stay in touch

Thanks for reading this article. I'd love to stay in touch and share articles like this one in your inbox. Sign up for my newsletter.