Jekyll

Remote Theme

Jekyll plugin for building Jekyll sites with any public GitHub-hosted theme

Usage

Add the following to your Gemfile

  gem "jekyll-remote-theme"

and run bundle install to install the plugin

Add the following to your site’s _config.yml to activate the plugin

  plugins:
    - jekyll-remote-theme

Note: If you are using a Jekyll version less than 3.5.0, use the gems key instead of plugins.

Add the following to your site’s _config.yml to choose your theme

  remote_theme: benbalter/retlab

or ¹

  remote_theme: http[s]://github.<Enterprise>.com/benbalter/retlab

¹ The codeload subdomain needs to be available on your github enterprise instance for this to work.

Declaring your theme

Remote themes are specified by the remote_theme key in the site’s config.

For public GitHub, remote themes must be in the form of OWNER/REPOSITORY, and must represent a public GitHub-hosted Jekyll theme. See the Jekyll documentation for more information on authoring a theme. Note that you do not need to upload the gem to RubyGems or include a .gemspec file.

You may also optionally specify a branch, tag, or commit to use by appending an @ and the Git ref (e.g., benbalter/retlab@v1.0.0 or benbalter/retlab@develop). If you don’t specify a Git ref, the HEAD ref will be used.

For Enterprise GitHub, remote themes must be in the form of http[s]://GITHUBHOST.com/OWNER/REPOSITORY, and must represent a public (non-private repository) GitHub-hosted Jekyll theme. Other than requiring the fully qualified domain name of the enterprise GitHub instance, this works exactly the same as the public usage.

Debugging

Adding --verbose to the build or serve command may provide additional information.

References

benbalter/jekyll-remote-theme: Jekyll plugin for building Jekyll sites with any GitHub-hosted theme