Creating your own Jekyll Theme Gem

After searching for a short while, I found I couldn’t quite find a Jekyll Theme that I liked. All the ones that I came across needed a lot of work, so I thought I’d whip up my own theme and make it a gem. It’s a lot quicker and easier than you think.

For my theme, I used Materialize — a front-end framework based on Material Design.

Firstly, head over to RubyGems and sign up for an account — you’ll need these credentials later when you push your gem up.

Jekyll already contains a new-theme command which scaffolds together a skeleton for you. It’ll look something like this.

It provides a nice starter README, which explains the setup and what the theme includes. As well as this, the command creates a .gemspec file, which contains all the information and build instructions for your gem.

When you’re done with your theme, you’ll want to go in here and edit the details at the top, so once your Gem’s live, all the necessary information is available.

The site itself functions the same as a jekyll site, so when you’re developing you can use jekyll serve to boot up your site on a server, that way you can view and test your site whilst you’re developing your theme.

To test your gem, let’s build it and load it on another jekyll site.

This will generate a gem file within your directory, however it’ll be hidden as it’s part of your .gitignore file. Next, generate a new jekyll site, add your gem to the gemfile (specificying it’s path), bundle install, change the _config.yml to use your theme and then jekyll serve. This should serve up your new site, using your gem as it’s theme.

Head over to http://localhost:4000 and you should be able to see your site, using your gem theme.

Once you’ve styled, created and tested your Jekyll theme, it’s time to go live! Once you’ve edited your .gemspec file and made sure all the necessary files are included, use the build command to build the first version of your gem. Ruby Gems use Semantic Versioning so your first push might not be your major release, so it defaults to version 0.1.0.

Briefly, Semantic Versioning works by incrementing the numbers based on MAJOR.MINOR.PATCH releases. MAJOR version, as the word suggests, is a major release where you make incompatible API changes. MINOR version is adding functionality in a backwards compatibility manner. PATCH version is for any bug fixes. It’s best practice to follow these guidelines when releasing/updating your gem, so keep that in mind during future development if you further tweak your theme.

This is where you’ll need your login details you created earlier. Once filled in, head over to RubyGems and search for your gem. It should appear in the list of results, go ahead and view the page to ensure all the details are correct. If you make a mistake, don’t worry you can pull it off using a simple command.

Congrats, you’ve just published a gem! You can also add your theme to various jekyll theme sites, most of them require you to fork the repo and open a pull request with a new post about your theme.

As always, thanks for reading, hit 👏 if you like what you read and be sure to follow to keep up to date with future posts.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store