Генераторы

Вы можете создать генератор, если хотите, чтобы Jekyll создавал дополнительное содержимое по вашим собственным правилам.

Генератор — это подкласс Jekyll::Generator, в котором определён метод generate, получающий экземпляр Jekyll::Site. Возвращаемое значение generate игнорируется.

Генераторы запускаются после того, как Jekyll составит опись существующего содержимого, и до генерации сайта. Страницы с front matter сохраняются как экземпляры Jekyll::Page и доступны через site.pages. Статические файлы становятся экземплярами Jekyll::StaticFile и доступны через site.static_files. Подробности см. на странице документации по переменным и в Jekyll::Site.

В следующем примере генератор добавляет значения, вычисляемые во время сборки, для переменных шаблона. Шаблон с именем reading.html содержит две неопределённые переменные ongoing и done, которым будет задано значение при запуске генератора:

module Reading
  class Generator < Jekyll::Generator
    def generate(site)
      book_data = site.data['books']
      ongoing = book_data.select { |book| book['status'] == 'ongoing' }
      done = book_data.select { |book| book['status'] == 'finished' }

      # get template
      reading = site.pages.find { |page| page.name == 'reading.html'}

      # inject data into template
      reading.data['ongoing'] = ongoing
      reading.data['done'] = done
    end
  end
end

В следующем примере показан более сложный генератор, создающий новые страницы.

В этом примере задача генератора — создать страницу для каждой категории, зарегистрированной в site. Страницы создаются во время выполнения, поэтому их содержимое, front matter и другие атрибуты должен задавать сам плагин.

• Предполагается, что на этих страницах будет отображаться список всех документов в заданной категории. Поэтому для сгенерированного файла лучше использовать базовое имя index.html.
• Возможность настраивать страницы с помощью значений front matter по умолчанию была бы очень полезна! Поэтому этим страницам стоит назначить определённый type.

module SamplePlugin
  class CategoryPageGenerator < Jekyll::Generator
    safe true

    def generate(site)
      site.categories.each do |category, posts|
        site.pages << CategoryPage.new(site, category, posts)
      end
    end
  end

  # Subclass of `Jekyll::Page` with custom method definitions.
  class CategoryPage < Jekyll::Page
    def initialize(site, category, posts)
      @site = site             # the current site instance.
      @base = site.source      # path to the source directory.
      @dir  = category         # the directory the page will reside in.

      # All pages have the same filename, so define attributes straight away.
      @basename = 'index'      # filename without the extension.
      @ext      = '.html'      # the extension.
      @name     = 'index.html' # basically @basename + @ext.

      # Initialize data hash with a key pointing to all posts under current category.
      # This allows accessing the list in a template via `page.linked_docs`.
      @data = {
        'linked_docs' => posts
      }

      # Look up front matter defaults scoped to type `categories`, if given key
      # doesn't exist in the `data` hash.
      data.default_proc = proc do |_, key|
        site.frontmatter_defaults.find(relative_path, :categories, key)
      end
    end

    # Placeholders that are used in constructing page URL.
    def url_placeholders
      {
        :path       => @dir,
        :category   => @dir,
        :basename   => basename,
        :output_ext => output_ext,
      }
    end
  end
end

Теперь для сгенерированных страниц можно задать определённый макет или путь вывода в целевом каталоге — всё это с помощью файла конфигурации и значений front matter по умолчанию. Например:

# _config.yml

defaults:
  - scope:
      type: categories  # select all category pages
    values:
      layout: category_page
      permalink: categories/:category/

Технические аспекты

Генераторам достаточно реализовать только один метод:

Если генератор содержится в одном файле, его можно назвать как угодно, но у него должно быть расширение .rb. Если генератор состоит из нескольких файлов, его следует упаковать в Rubygem и опубликовать на https://rubygems.org/. В этом случае имя гем-пакета зависит от того, доступно ли оно на этом сайте, поскольку два гема не могут иметь одинаковое имя.

По умолчанию Jekyll ищет генераторы в каталоге _plugins. Однако вы можете изменить каталог по умолчанию, присвоив желаемое имя ключу plugins_dir в файле конфигурации.