generators.md

title
Generators

Generators

You can create a generator when you need Jekyll to create additional content based on your own rules.

A generator is a subclass of Jekyll::Generator that defines a generate method, which receives an instance of [Jekyll::Site]({{ site.repository }}/blob/master/lib/jekyll/site.rb). The return value of generate is ignored.

Generators run after Jekyll has made an inventory of the existing content, and before the site is generated. Pages with YAML Front Matters are stored as instances of [Jekyll::Page]({{ site.repository }}/blob/master/lib/jekyll/page.rb) and are available via site.pages. Static files become instances of [Jekyll::StaticFile]({{ site.repository }}/blob/master/lib/jekyll/static_file.rb) and are available via site.static_files. See the Variables documentation page and [Jekyll::Site]({{ site.repository }}/blob/master/lib/jekyll/site.rb) for more details.

For instance, a generator can inject values computed at build time for template variables. In the following example the template reading.html has two variables ongoing and done that we fill in the generator:

{% highlight ruby %} module Reading class Generator < Jekyll::Generator def generate(site) ongoing, done = Book.all.partition(&:ongoing?)

  reading = site.pages.detect {|page| page.name == 'reading.html'}
  reading.data['ongoing'] = ongoing
  reading.data['done'] = done
end

end end {% endhighlight %}

This is a more complex generator that generates new pages:

{% highlight ruby %} 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 {% endhighlight %}

In this example, our generator will create a series of files under the categories directory for each category, listing the posts in each category using the category_index.html layout.

Generators are only required to implement one method:

Method	Description
generate	Generates content as a side-effect.