Creating a Jekyll Theme: A Comprehensive Guide

Introduction

Learn how to create and publish your Jekyll theme by following this step-by-step tutorial. From installation to going live, we cover everything you need to know.

Installation

Jekyll is a Ruby Gem that can be installed on most systems.

Requirements

• Ruby version 2.5.0 or higher, including all development headers. Check your version with ruby -v.
• RubyGems. Check your version using gem -v.
• GCC and Make. Verify versions with gcc -v, g++ -v, and make -v.

Installing Ruby and Jekyll

The easiest way to install Ruby and Jekyll is by using the RubyInstaller for Windows.

1. Download and install a Ruby+Devkit version from RubyInstaller Downloads. Use default options.
2. Run ridk install to install gems with native extensions. More info in the RubyInstaller Documentation.
3. Open a new command prompt, and install Jekyll and Bundler using:

   gem install jekyll bundler
   

4. Check installation with jekyll -v.

Getting Started

1. Sign up at RubyGems.
2. Initialize a new theme with:

   jekyll new-theme your-theme-name
   

3. Edit the .gemspec file with your theme's details.

Use jekyll serve to preview your site as you develop your theme.

Testing Your Gem

To test your gem:

$ gem build YOURTHEME.gemspec

1. Create a new Jekyll site:

   jekyll new mysite
   

2. Add your gem to the Gemfile and update _config.yml:

   gem "your-theme", path: "../your-theme/"
   theme: your-theme
   

3. Run:

   $ bundle install
   $ jekyll serve
   

Visit http://localhost:4000 to verify.

Going Live

Once satisfied with your theme:

1. Edit the .gemspec file.
2. Build the gem:

   $ gem build YOURTHEME.gemspec
   

3. Publish it:

   $ gem push YOURTHEME.gem
   

Follow Semantic Versioning: MAJOR.MINOR.PATCH.

To remove a gem:

$ gem yank YOURTHEME

Congratulations! You've published a Jekyll theme. Consider sharing it on Jekyll theme sites by submitting a pull request.