104 lines
2.9 KiB
Markdown
104 lines
2.9 KiB
Markdown
---
|
|
title: Generators
|
|
permalink: /docs/plugins/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 front matter 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](/docs/variables/) 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:
|
|
|
|
```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
|
|
```
|
|
|
|
This is a more complex generator that generates new pages:
|
|
|
|
```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
|
|
```
|
|
|
|
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:
|
|
|
|
<div class="mobile-side-scroller">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Method</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<p><code>generate</code></p>
|
|
</td>
|
|
<td>
|
|
<p>Generates content as a side-effect.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|