Improve this page

Plugins

Jekyll has built-in support for using plugins to extend the core functionality.

Primarily, any file with extension .rb placed within a _plugins directory at the root of the site’s source, will be automatically loaded during a build session.

This behavior can be configured as follows:

  • The _plugins directory may be changed either directly via the command-line or via the configuration file(s).
  • Plugins in the _plugins directory (or its equivalent(s)) will not be loaded when Jekyll is running in safe mode.
  • This route cannot be used to extend the Jekyll CLI.

To work with plugins packaged as gems, one has to list the desired gems in the configuration file under a top-level key named plugins. Additionally, if you’re building in safe mode, the gem needs to be listed under a top-level key named whitelist. For example:

plugins:
  - jekyll-gist
  - jekyll-coffeescript
  - jekyll-seo-tag
  - some-other-jekyll-plugin

# Enable safe mode
safe: true

# Whitelist plugins under safe mode.
# Note that `some-other-jekyll-plugin` is not listed here. Therefore,
# it will not be loaded under safe mode.
whitelist:
  - jekyll-gist
  - jekyll-coffeescript
  - jekyll-seo-tag

In the absence of a Gemfile, one must manually ensure that listed plugins have been installed prior to invoking Jekyll. For example, the latest versions of gems in the above list may be installed to a system-wide location by running:

gem install jekyll-gist jekyll-coffeescript jekyll-remote-theme some-other-jekyll-plugin

Using a Gemfile

The maintenance of various gem dependencies may be greatly simplified by using a Gemfile (usually at the root of the site’s source) in conjunction with a Rubygem named bundler. The Gemfile however should list all the primary dependencies of your site, including Jekyll itself, not just gem-based plugins of the site because Bundler narrows the scope of installed gems to just runtime dependencies resolved by evaluating the Gemfile. For example:

source "https://rubygems.org"

# Use the latest version.
gem "jekyll"

# The theme of current site, locked to a certain version.
gem "minima", "2.4.1"

# Plugins of this site loaded during a build with proper
# site configuration.
gem "jekyll-gist"
gem "jekyll-coffeescript"
gem "jekyll-seo-tag", "~> 1.5"
gem "some-other-jekyll-plugin"

# A dependency of a custom-plugin inside `_plugins` directory.
gem "nokogiri", "~> 1.11"

The gems listed in the Gemfile can be collectively installed by simply running bundle install.

The :jekyll_plugins Gemfile group

Jekyll gives a special treatment to gems listed as part of the :jekyll_plugins group in a Gemfile. Any gem under this group is loaded at the very beginning of any Jekyll process, irrespective of the --safe CLI flag or entries in the configuration file(s).

While this route allows one to enhance Jekyll’s CLI with additional subcommands and options, or avoid having to list gems in the configuration file, the downside is the necessity to be mindful of what gems are included in the group. For example:

source "https://rubygems.org"

# Use the latest version.
gem "jekyll"

# The theme of current site, locked to a certain version.
gem "minima", "2.4.1"

# Plugins of this site loaded only if configured correctly.
gem "jekyll-gist"
gem "jekyll-coffeescript"

# Gems loaded irrespective of site configuration.
group :jekyll_plugins do
  gem "jekyll-cli-plus"
  gem "jekyll-seo-tag", "~> 1.5"
  gem "some-other-jekyll-plugin"
end
Plugins on GitHub Pages

GitHub Pages is powered by Jekyll. All GitHub Pages sites are generated using the --safe option to disable plugins (with the exception of some whitelisted plugins) for security reasons. Unfortunately, this means your plugins won't work if you’re deploying via GitHub Pages.

You can still use GitHub Pages to publish your site, but you'll need to either build the site locally and push the generated files to your GitHub repository or use GitHub Actions to host source files on GitHub yet build and deploy with full control on GitHub Pages.

_plugins, _config.yml and Gemfile can be used simultaneously

You may use any of the aforementioned plugin routes simultaneously in the same site if you so choose. Use of one does not restrict the use of the others.