How to create a jekyll theme

Install Ruby and the requirements

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 Ruby version using ruby -v)
RubyGems (check your Gems version using gem -v)
GCC and Make (check versions using gcc -v,g++ -v, and make -v)
Installing Ruby and Jekyll(https://jekyllrb.com/docs/installation/windows/#installing-ruby-and-jekyll)
Installation via RubyInstaller(https://jekyllrb.com/docs/installation/windows/#installation-via-rubyinstaller)

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

RubyInstaller is a self-contained Windows-based installer that includes the Ruby language, an execution environment, important documentation, and more.

We only cover RubyInstaller-2.4 and newer here. Older versions need to install the Devkit manually.

Download and install a Ruby+Devkit version from RubyInstaller Downloads. Use default options for installation.
Run the ridk install step on the last stage of the installation wizard. This is needed for installing gems with native extensions. You can find additional information regarding this in the RubyInstaller Documentation
Open a new command prompt window from the start menu, so that changes to the PATH environment variable becomes effective. Install Jekyll and Bundler using gem install jekyll bundler
Check if Jekyll has been installed properly: jekyll -v

Getting Started

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.

jekyll new-theme testing123

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.

Testing your Gem

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

# bash
$ gem build YOURTHEME.gemspec

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.

jekyll new mysite

cd mysite
atom .
ruby
Gemfile

gem "testing", "~> 0.0.1", :path => "../testing/"

# bash
$ bundle

# YAML
# _config.yml
[...]
theme: YOURTHEME
[...]

# bash
$ jekyll serve

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

Going Live

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.

bash$ gem build YOURTHEME.gemspec$ gem push YOURTHEME.gem

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.

bash $ gem yank YOURTHEME

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.