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

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 GemfilePermalink

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 groupPermalink

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

Categories: Health, Travel, Life Style