Плагины позволяют добавить дополнительное поведение в сам процесс генерации сайта. Процесс написания плагинов здесь не описывается.

Существует три способа добавить плагин:

  • Добавить его в директорию _plugins как файл на Ruby
  • Добавить его в _config.yml по ключу plugins
  • Добавить его в Gemfile в группу jekyll_plugins и установить через bundler install
group :jekyll_plugins do
  gem "jekyll-gist"
  gem "jekyll-coffeescript"
  gem "jekyll-assets"
  gem "another-jekyll-plugin"
end

Все эти способы можно использовать одновременно. Существует пять типов плагинов:

  • Генераторы
  • Конверторы
  • Команды
  • Теги
  • Приемы

Генераторы

Используются когда необходимо создать дополнительный контент по некоторым правилам. Все генераторы являются наследниками класса Jekyll::Generator, который имеет метод generate(Jekyll::Site site). Метод ничего не возвращает. Пример генератора:

module Jekyll
  class CategoryPage < Page
    def initialize(site, base, dir, category)
      @site = site
      @base = base
      @dir = dir
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
      self.data['category'] = category

      category_title_prefix = site.config['category_title_prefix'] || 'Category: '
      self.data['title'] = "#{category_title_prefix}#{category}"
    end
  end

  class CategoryPageGenerator < Generator
    safe true

    def generate(site)
      if site.layouts.key? 'category_index'
        dir = site.config['category_dir'] || 'categories'
        site.categories.each_key do |category|
          site.pages << CategoryPage.new(site, site.source, File.join(dir, category), category)
        end
      end
    end
  end
end

Конверторы

Используются для новых языков разметки. Пример конвертера

module Jekyll
  class UpcaseConverter < Converter
    safe true
    priority :low

    def matches(ext)
      ext =~ /^\.upcase$/i
    end

    def output_ext(ext)
      ".html"
    end

    def convert(content)
      content.upcase
    end
  end
end

Команды

Используется при запуске Jekyll из командной строки. Пример:

class MyNewCommand < Jekyll::Command
  class << self
    def init_with_program(prog)
      prog.command(:new) do |c|
        c.syntax "new [options]"
        c.description 'Create a new Jekyll site.'

        c.option 'dest', '-d DEST', 'Where the site should go.'

        c.action do |args, options|
          Jekyll::Site.new_site_at(options['dest'])
        end
      end
    end
  end
end

Теги

Используется для создания пользовательских liquid-тегов, или пометки плагинов.

Как теги:

module Jekyll
  class RenderTimeTag < Liquid::Tag

    def initialize(tag_name, text, tokens)
      super
      @text = text
    end

    def render(context)
      "#{@text} #{Time.now}"
    end
  end
end

Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)


<p>{% render_time page rendered at: %}</p>
# => Станет
<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>

Как фильтр:

module Jekyll
  module AssetFilter
    def asset_url(input)
      "http://www.example.com/#{input}?#{Time.now.to_i}"
    end
  end
end

Liquid::Template.register_filter(Jekyll::AssetFilter)

Как флаги:

module Jekyll
  class UpcaseConverter < Converter
    safe true # --safe использует плагин
    priority :low # будет загружен в конце :lowest, :low, :normal, :high, и :highest
  end
end

Приемы

Используются при возникновении событий

Jekyll::Hooks.register :posts, :post_render do |post|
  # code to call after Jekyll renders a post
end

Список событий

  • :site, :after_init
  • :site, :after_reset
  • :site, :post_read
  • :site, :pre_render
  • :site, :post_render
  • :site, :post_write
  • :pages, :post_init
  • :pages, :pre_render
  • :pages, :post_render
  • :pages, :post_write
  • :posts, :post_init
  • :posts, :pre_render
  • :posts, :post_render
  • :posts, :post_write
  • :documents, :post_init
  • :documents, :pre_render
  • :documents, :post_render
  • :documents, :post_write

*_init - вызывается в самом начале, *_pre_render - перед тем как отобразить, *_post_render - сразу после отображение, *_post_write - в самом конце.