Jekyll Remote Theme

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

Usage

1. Add the following to your Gemfile

   gem "jekyll-remote-theme"

   and run bundle install to install the plugin

2. 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.

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

   remote_theme: benbalter/retlab

   or

   remote_theme: https://github.<Enterprise>.com/benbalter/retlab

   or

   repository: https://github.<Enterprise>.com
   remote_theme: benbalter/retlab

Declaring your theme

Remote themes are specified by the remote_theme key in the site's config. By default, this will use https://github.com as the host. If you would like to specify your own host, either specify the host part of the remote_theme (e.g., https://github.com/benbalter/retlab) or by specifying repository (e.g., https://github.com).

For GitHub, remote themes must be in the form of OWNER/REPOSITORY, and must represent a 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/[email protected] or benbalter/retlab@develop). If you don't specify a Git ref, the master branch will be used.

To use your own host, such as for Enterprise GitHub, you can specify remote_theme providing the full url (e.g., https://GITHUBHOST.com/OWNER/REPOSITORY), and must represent GitHub-hosted Jekyll theme. Alternatively, you can specify repository. This works exactly the same as the GitHub usage.

Private and Internal Themes

If you would like to use a private or internal hosted theme (or have other specific headers needs):

1. Create a Personal Access Token following the Creating a personal access token on GitHub guides

2. Add the remote_header in your _config.yml

   remote_header: 
     Authorization: token <personal autorization token>

   Where the personal autorization token is the token provided by the github repo setting page.

   ⚠️ Storing credentials can lead to security issues - As stated in the Creating a personal access token on GitHub guides Treat your tokens like passwords and keep them secret. When working with the API, use tokens as environment variables instead of hardcoding them into your programs.

Debugging

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