How to Create and Publish a Jekyll Theme Gem

One of Jekyll’s noteworthy new features is the ability create official themes in the form of Ruby gems. These themes can be installed by a Jekyll user to style their static blog or website with ease, leaving them to manage their content.

Prior to this new theming feature, Kezz Bracey wrote a great tutorial on how to create a Jekyll theme. In this tutorial, we’re going to extend upon Kezz’s post by converting our template into an official Jekyll theme gem.

Jekyll on Envato Market

The Jekyll category on Themeforest has a bunch of themes ranging from $16 to $29. Why not submit your own, all wrapped up as a neat Ruby Gem?

Jekyll on Themeforest — Jekyll themes on Themeforest

Preparation

Before we get started, I would recommend you read through the previous tutorial. I’m going to assume you already have a Jekyll theme created using Kezz’s method, or you may even have a well written Jekyll site that you’d like to convert into an official Jekyll theme.

You’re going to need to use the command line when working on your Jekyll theme, but once again, Kezz has you covered!

Open your command line tool and make sure you have the latest version of Jekyll installed (at the time of this article it’s 3.3) by using the following:

1	$ gem install jekyll

You’ll also need Bundler, which is a gem for managing other gems. I’ll explain why you need this later on. You can install this using:

1	$ gem install bundler

Finally, you’ll need to sign up for a RubyGems.org account. Doing this allows you to push your theme to their registry so other Jekyll users can download and use it.

Getting Started

To help us get started, Jekyll has a command just for creating a new theme. In your command line tool, locate the directory you plan to work in, and use the following command to create the base files for your theme:

1	$ jekyll new-theme awesome-jekyll-theme

You should see something like the list below in your working folder:

awesome-jekyll-theme/
  _includes/
  _layouts/
    default.html
    page.html
    post.html
  _sass/
  assets/
  Gemfile
  LICENSE.txt
  awesome-jekyll-theme.gemspec
  README.md

The _layouts/, _includes/ and _sass/ folders are the same as the folders you’d see in a normal Jekyll project, containing all your page layouts, “includes” (or “partials”) and Sass files.

The assets/ folder is for files you want to output to the user’s site. For example, JavaScript, image or style files. You would normally place these files into js/, css/ or images/ folders.

awesome-jekyll-theme.gemspec is the file that describes your gem theme. Here is where you can list the name, the version, a description, a homepage, and a list of gems for your theme gem.

The Gemfile is for Bundler, which we mentioned before. This links the gems listed in your .gemspec file with Bundler in your command line tool. We’ll be using Bundler later to test out your theme.

Finally, the README.md and LICENSE.txt are there to document your theme and to provide a suitable license. You’re probably familiar with these files if you’ve created a GitHub project before.

Note: It’s important to document your theme thoroughly. That way, people who want to use your theme will be able to do so easily, and use the options and controls you’ve provided within it.

Converting Your Theme

Given that a Jekyll project has a pretty similar file structure to a Jekyll theme, you can go ahead and copy most of your files over. You’ll probably want to overwrite the pre-existing layout files that come with the base theme with your own. So, all your layout files need to go into the _layouts/ folder, your includes into the _includes/ folder, and your Sass files into the _sass/ folder within the base theme you created.

Hint: New to Sass? Check out this course by Adi Purdila, 14 Days to Learn Sass

You’ll need to place your main styles, JavaScript and graphic assets in the assets/ folder. This is a key folder for Jekyll theming as it’s the only directory that will appear in the end users site. You may end up with an assets folder that looks like this:

1	assets/
2	styles.scss
3	scripts.js
4	theme-logo.png

In turn, you’ll need to update the paths in your code to reflect this path change. For example, css/styles.scss will change to assets/styles.scss.

Hint: To make sure your paths are correct in your theme, you might want to check out relative_url and absolute_url which have recently been added to Jekyll.

Your Theme Metadata

The .gemspec file is designed to provide core information about your theme gem. The base Jekyll theme comes with this file, but you’ll need to replace the example values with your own. Here’s an example .gemspec file:

# coding: utf-8

Gem::Specification.new do |spec|
  spec.name          = "awesome-jekyll-theme"
  spec.version       = "0.0.2"
  spec.authors       = ["David Darnes"]
  spec.email         = ["me@daviddarnes.com"]

  spec.summary       = %q{A short explanation of my awesome gem theme.}
  spec.description   = "A longer explanation of my awesome gem theme that isn’t the same as my summary."
  spec.homepage      = "https://alembic.darn.es"
  spec.license       = "MIT"

  spec.files         = git ls-files -z.split("\x0").select { |f| f.match(%r{^(assets|_layouts|_includes|_sass|LICENSE|README)}i) }

  spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.0"

  spec.add_development_dependency "jekyll", "~> 3.3"
  spec.add_development_dependency "bundler", "~> 1.12"
end

Below is a run down of what I changed in my .gemspec file:

The name should be the name of your theme, which should match with the .gemspec file name. The version should be the latest number of your theme gem. The authors can be a list of people, but, for now, it’s just myself developing this theme. email should be the same email you signed up with for RubyGems.org.

The summary and description should be short and long explanations respectively of your theme gem. You can either set the homepage to a live demo of the theme or even the GitHub repo in which is resides.

The license should match whatever license you’ve provided in the theme gem (the LICENSE.txt file). The files value should be left unchanged as that marks the files and folders that will be used in your final theme gem.

The last part of the .gemspec file is a list of gems that are needed in order for your theme to work correctly. In my example, I have just one gem that is needed for it to run: jekyll-seo-tag. The other gems listed, jekyll and bundler, are development gems and are only needed when someone is developing the theme gem.

Make sure to add all the gems you need for your theme in this file. You can find a full list of Jekyll’s plugins on their site.

Testing Your Theme

Now that we have our theme files and our .gemspec file has been filled in, we can now perform some initial testing. However, we’re going to need some sample content, so copy over the _config.yml from your old template theme, along with some markdown content. An index.md file with some content should be sufficient for an initial test, but you may want to add an example post, as well. Blogging is one of the key features of Jekyll, so it would be a good idea to test this.

Note: Make sure your front matter has a layout selected or you might not see the theme correctly when running locally.

Remember that we installed Bundler and that Gemfile in the base of our theme directory? Well, Bundler uses Gemfiles to manage gems in projects and if you open that file, you’ll see the following:

1	source "https://rubygems.org"
2	gemspec

What this file does is to tell Bundler to look on RubyGems.org for the gems in your .gemspec file. So, with that in mind, let’s test your theme.

In your command line tool, use the command below to install all the gems needed for your theme gem:

1	$ bundle install

This should install all the themes in your .gemspec, which, in my example, would just be jekyll-seo-tag. Now we can run the theme locally using:

1	$ bundle exec jekyll serve

You should then be able to view your theme at http://localhost:4000. If an error occurs, it might be because you’re missing a gem in your .gemspec file.

Note: You might need to whitelist gems in your _config.yml file, if you haven’t already done so, as well as stating them in your .gemspec. If you’re struggling to get to grips with Jekyll, Guy Routledge has created a great course for Tuts+ on Building Static Websites With Jekyll.

Refining and Adding Customisation

Next, you’re going to be spending some time refining your theme to make sure it works with a variety of content formats and sizes. You might also want to consider customisation options, either through a global setting in the _config.yml or on separate pages in the front matter.

The user has the ability to overwrite any file in your theme gem with their own file on their own Jekyll site. For example, if you have _includes/header.html in your theme gem, the theme user can overwrite that file with _includes/header.html on their own site. You might want to think about making your theme flexible enough that the theme user can easily overwrite your files to make their own site more unique.

Documentation

If you’re adding customisation to your theme, you’re going to need documentation to go with it. Documenting your theme gem is very important. If the documentation is poor, then people won’t want to use the theme.

Here are some of the things that I would expect to see in a theme’s documentation:

A good description of the theme and its uses
A list of features
Clear installation instructions
Some demo content to show how to use the theme
How the configuration options work
How the page options work
Any shortcodes / includes that can be used
References to any open source projects you used to help create the theme

All of this can be listed in the README.md, which was created when we generated the base Jekyll theme. When the theme gets pushed up to RubyGems.org, the readme file will be processed and shown on the gem page for people to refer to.

Along with your documentation, I would recommend providing some demo content to get people started with your theme. A _config.yml, index.md and example post file, similar to the ones you used to test your theme with earlier, along with a Gemfile should be sufficient. Although it should only require the user to add the gem to their Gemfile, it would be very helpful to provide an example setup that they can download and use straight away.

You’ll need to provide a screenshot for your theme, as stated in the official Jekyll documentation, with the name screenshot.png. Not only will this allow people to see how your theme looks at a glance, but it will also provide a consistency across all Jekyll themes so that they can be displayed in a gallery or admin UI in the future.

Publishing Your Theme

Once you’re happy with your theme, and you’ve tested and documented it, you’ll need to push it up to the RubyGems.org registry so that others can use it.

Locate your theme gem with your command line tool and use the following:

1	gem build awesome-jekyll-theme.gemspec

Make sure to match the name of the .gemspec file in your theme with the command shown above. This will create a file called awesome-jekyll-theme-0.0.2.gem, which is your official Jekyll theme gem! Next, you’ll need to push your gem up to RubyGems.org. Use the following in your command line tool:

1	gem push awesome-jekyll-theme-0.0.2.gem

If this is your first time pushing a gem to RubyGems.org, it will ask you to log in with the details you used to sign up. After that, the gem should be pushed up to the registry, meaning your theme gem has been published.

Hint: With most command line tools, if you write the first few letters of a file and then press Tab, it should autocomplete the rest of the file name, as long as there isn’t another file starting with the same letters in the same folder.

Once this has happened, you’ll need to do some further testing and follow your own instructions on installing and using the theme gem. The instructions should be fairly similar to the ones shown on the official Jekyll site.

Additional Reading

As well as following this tutorial, you might want to check out these resources when it comes to creating your own Jekyll theme gem:

Jekyll’s official documentation on theme creation
The RubyGems.org guide on creating gems
The official Jekyll forums, containing helpful threads and the Jekyll community
Gem based themes thread on the Jekyll forums