Плагины

Jekyll имеет встроенную поддержку плагинов для расширения основных возможностей.

В первую очередь, любой файл с расширением .rb, размещённый в каталоге _plugins в корне source сайта, будет автоматически загружен во время сборки.

Это поведение можно настроить следующим образом:

• Каталог _plugins можно изменить напрямую через командную строку или с помощью файла (файлов) конфигурации.
• Плагины из каталога _plugins (или его эквивалента) не будут загружаться, если Jekyll запущен в режиме safe.
• Этот способ нельзя использовать для расширения CLI Jekyll.

Чтобы использовать плагины, упакованные в виде гемов, нужно указать необходимые гемы в файле конфигурации в разделе верхнего уровня с именем plugins. Кроме того, если вы выполняете сборку в режиме safe, гем необходимо указать в разделе верхнего уровня с именем whitelist. Например:

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

Если Gemfile отсутствует, необходимо вручную убедиться, что перечисленные плагины установлены до запуска Jekyll. Например, последние версии гемов из приведённого выше списка можно установить в общесистемный каталог, выполнив команду:

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

Использование Gemfile

Управление различными зависимостями гемов можно значительно упростить, используя Gemfile (обычно в корне исходного кода сайта) совместно с гемом RubyGems под названием bundler. Однако в Gemfile следует перечислить все основные зависимости сайта, включая сам Jekyll, а не только плагины сайта на основе гемов, поскольку Bundler ограничивает набор установленных гемов только зависимостями времени выполнения, определёнными при обработке Gemfile. Например:

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"

Гемы, перечисленные в Gemfile, можно установить все вместе, просто выполнив bundle install.

Группа Gemfile :jekyll_plugins

Jekyll обрабатывает гемы, перечисленные в группе :jekyll_plugins в Gemfile, особым образом. Любой гем из этой группы загружается в самом начале каждого процесса Jekyll независимо от флага CLI --safe или записей в файле (файлах) конфигурации.

Хотя этот способ позволяет расширить CLI Jekyll дополнительными подкомандами и параметрами или избежать необходимости перечислять гемы в файле конфигурации, его недостаток заключается в том, что нужно внимательно следить за тем, какие гемы включены в эту группу. Например:

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

Плагины на GitHub Pages

GitHub Pages работает на базе Jekyll. Из соображений безопасности все сайты GitHub Pages генерируются с параметром --safe, отключающим плагины (за исключением некоторых плагинов из белого списка). К сожалению, это означает, что ваши плагины не будут работать при публикации через GitHub Pages.
Вы всё ещё можете использовать GitHub Pages для публикации сайта, но вам потребуется либо собрать сайт локально и отправить сгенерированные файлы в репозиторий GitHub, либо использовать GitHub Actions, чтобы хранить исходные файлы на GitHub, а сборку и публикацию сайта выполнять с полным контролем через GitHub Pages.

_plugins, _config.yml и Gemfile можно использовать одновременно

При желании вы можете одновременно использовать на одном сайте любой из описанных выше способов подключения плагинов. Использование одного способа не ограничивает применение остальных.