10 Jul 2019
Jekyll themes with GitHub
Recently we covered turning a Jekyll theme into a Gem and hosting it privately on GemFury. In this post we’re demonstrating how you can host your theme on GitHub . GitHub allow both public and private repository/theme hosting.
Create a theme repository
First, create a repository on GitHub. Anyone can use your theme if the repository is public.
Clone the repository to your local machine and open it from the command line. The Jekyll
new-theme command builds a basic theme structure that includes the
_sass directories. Start building a theme by entering the following into your command line:
$ jekyll new-theme mytheme
This generates a basic Jekyll site which other sites can inherit from. The Jekyll
new-theme command also creates a gemspec file (
mytheme.gemspec). This holds the version, and other relevant theme details.
It is good practice to add all relevant details to the
.gemspec file, and the
README.md file. You will receive build errors if the
README.md files contain “FIXME” and “TODO” entries.
Push these changes to your theme’s repository on GitHub to ensure everything is up to date.
To build a themed site the
Gemfile should specify where to download the theme from. Open your site’s
Gemfile and add the following line:
gem 'mytheme', '>= 0.1.0', :git => 'https://github.com/GITHUB-USERNAME/mytheme.git'
Jekyll also needs to know that the site is using a theme. Specify the theme you are using within the site’s
Using Different Versions
It is also possible to specify a particular theme ref/commit, branch, or tag to use.
gem 'mytheme', '>= 1.2.4', :git => 'https://github.com/GITHUB-USERNAME/mytheme.git' :git => 'https://github.com/GITHUB-USERNAME/mytheme.git', :ref => '6afec' :git => 'https://github.com/GITHUB-USERNAME/mytheme.git', :branch => '1-2-beta' :git => 'https://github.com/GITHUB-USERNAME/mytheme.git', :tag => 'v1.2.4'
Private repositories can be accessed using OAuth Tokens instead of personal credentials. To create an OAuth Token follow these steps:
- Open your GitHub account settings
- Select Developer Settings from the left-hand menu
- Select Personal Access Tokens from the left-hand menu
- Select the Generate New Token button
Set the relevant permissions which the token will have access to. Once the token has generated, note it and keep it private. Keys are not recoverable once they’re lost.
To use a private theme the repository URL specified in the site’s
Gemfile needs to include the token:…
gem 'mytheme', '>= 0.1.0', :git => 'https://TOKEN:firstname.lastname@example.org/USERNAME/mytheme.git'
Be sure to specify the theme you are using within the site’s
Gemfile.lock will always lock to a specific commit/version. Run the
bundle update theme_name command to pull new theme changes/versions.
Using themes with GitHub can be more convenient while you’re developing. With GitHub repositories, you don’t need to release a gem for every change or update. Once a theme is stable it may be more beneficial to use a Gem. Using Gems help to keep consistency with versioning across your sites.