Jekyll Themes


While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

As of Jekyll v3.2, themes are a first-class citizen in Jekyll. This means that theme designers can create Jekyll themes that are bundled as RubyGems and are properly versionable and updatable. This is a great move to foster a better theme ecosystem in Jekyll and make life easier for both theme designers and website creators.

Right now themes only support layout, include and Sass files, but the plan is to also support other theme assets in future releases. Themes need to be bundled as RubyGems, so the RubyGems website will be a good place to find themes and follow the latest updates.

Installing a theme

Add the theme by its name to your Gemfile:

gem 'theme-name'

You can have multiple themes in your Gemfile

Then add the theme in your _config.yml file:

theme: theme-name

Only one theme should be used in your _config.yml however.

Themes are also required to include a README file, which should be useful to learn the specifics of each theme.

Updating a theme

As themes are now bundled as Rubygems, updating when there’s a new version is now as easy as updating the gem:

gem update theme-name

Or, if you’re using bundler:

bundler update theme-name

Overwriting files

Jekyll will first look if it can find a version of any file in your Jekyll project before using the theme’s version of the same file. This means that you can overwrite any theme file simply by creating a file with the same name in your project.

Shiny new toy

As of this writing, Jekyll 3.2 is just released and only a few themes are available as Rubygems. Minima and Garth are two examples. Let’s hope for plenty more in the very near future!

Let’s also hope that the main Jekyll theme directory websites catch up on the change quickly.

Read more

Read the official docs for Jekyll themes for more details and to learn how to create and bundle your own themes.

Creative Commons License