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.
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.
# bash$ jekyll new-theme testing123create
/Users/jameshamann/Documents/Development/testing123/assetscreate
/Users/jameshamann/Documents/Development/testing123/_layoutscreate
/Users/jameshamann/Documents/Development/testing123/_includescreate
/Users/jameshamann/Documents/Development/testing123/_sasscreate /Users/jameshamann/Documents/Development/testing123/_layouts/page.htmlcreate/Users/jameshamann/Documents/Development/testing123/_layouts/post.htmlcreate /Users/jameshamann/Documents/Development/testing123/_layouts/default.htmlcreate /Users/jameshamann/Documents/Development/testing123/Gemfile
create
/Users/jameshamann/Documents/Development/testing123/testing123.gemspeccreate /Users/jameshamann/Documents/Development/testing123/README.mdcreate /Users/jameshamann/Documents/Development/testing123/LICENSE.txt
initialize /Users/jameshamann/Documents/Development/testing123/.gitcreate /Users/jameshamann/Documents/Development/testing123/.gitignoreYour new Jekyll theme, testing123, is ready for you in /Users/jameshamann/Documents/Development/testing123!For help getting started, read /Users/jameshamann/Documents/Development/testing123/README.md.
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.
# ruby # coding: utf-8Gem::Specification.new do |spec|
spec.name = "testing123"
spec.version = "0.1.0"
spec.authors = [""]
spec.email = [""]spec.summary = %q{TODO: Write a short summary, because Rubygems requires one.}
spec.homepage = "TODO: Put your gem's website or public repo URL here."
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", "~> 3.6"spec.add_development_dependency "bundler", "~> 1.12"
spec.add_development_dependency "rake", "~> 10.0"
end
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.
# bash $ jekyll new mysite Bundler: Fetching gem metadata from https://rubygems.org/...........
Bundler: Fetching gem metadata from https://rubygems.org/.
Bundler: Resolving dependencies...
Bundler: Using public_suffix 3.0.1
Bundler: Using addressable 2.5.2
Bundler: Using bundler 1.16.0.pre.3
Bundler: Using colorator 1.1.0
Bundler: Using ffi 1.9.18
Bundler: Using forwardable-extended 2.6.0
Bundler: Using rb-fsevent 0.10.2
Bundler: Using rb-inotify 0.9.10
Bundler: Using sass-listen 4.0.0
Bundler: Using sass 3.5.3
Bundler: Using jekyll-sass-converter 1.5.1
Bundler: Using ruby_dep 1.5.0
Bundler: Using listen 3.1.5
Bundler: Using jekyll-watch 1.5.1
Bundler: Using kramdown 1.16.2
Bundler: Using liquid 4.0.0
Bundler: Using mercenary 0.3.6
Bundler: Using pathutil 0.16.0
Bundler: Using rouge 2.2.1
Bundler: Using safe_yaml 1.0.4
Bundler: Using jekyll 3.6.2
Bundler: Using jekyll-feed 0.9.2
Bundler: Using minima 2.1.1
Bundler: Bundle complete! 4 Gemfile dependencies, 23 gems now installed.
Bundler: Use `bundle info [gemname]` to see where a bundled gem is installed.
New jekyll site installed in /Users/jameshamann/Documents/Development/mysite.$ cd mysite
$ atom .--------------------------------------------------------------------# ruby# Gemfilegem "YOURTHEME" => :path => "path/to/your/gem"-------------------------------------------------------------------
# bash$ bundle
Fetching gem metadata from https://rubygems.org/...........
Fetching gem metadata from https://rubygems.org/.
Resolving dependencies...
Using public_suffix 3.0.1
Using addressable 2.5.2
Using bundler 1.16.0.pre.3
Using colorator 1.1.0
Using ffi 1.9.18
Using forwardable-extended 2.6.0
Using rb-fsevent 0.10.2
Using rb-inotify 0.9.10
Using sass-listen 4.0.0
Using sass 3.5.3
Using jekyll-sass-converter 1.5.0
Using listen 3.0.8
Using jekyll-watch 1.5.0
Using kramdown 1.16.2
Using liquid 4.0.0
Using mercenary 0.3.6
Using pathutil 0.16.0
Using rouge 2.2.1
Using safe_yaml 1.0.4
Using jekyll 3.6.2
Using jekyll-feed 0.9.2
Using jekyll-material-theme 0.1.0 from source at `../material-theme`
Bundle complete! 4 Gemfile dependencies, 22 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.--------------------------------------------------------------------# YAML# _config.yml[...]theme: YOURTHEME[...]--------------------------------------------------------------------# bash$ jekyll serveConfiguration file: /Users/jameshamann/Documents/Development/mysite1234/_config.yml
Source: /Users/jameshamann/Documents/Development/mysite1234
Destination: /Users/jameshamann/Documents/Development/mysite1234/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.436 seconds.
Auto-regeneration: enabled for '/Users/jameshamann/Documents/Development/mysite1234'
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.
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.
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.
