Chapter 1.1 - Plugins

In general, plugins you make will fall into one of four categories:

1. Generators
2. Converters
3. Commands
4. Tags

Chapter 1.2 - 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. 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 and are available via site.pages. Static files become instances of Jekyll::StaticFile and are available via site.static_files. See the Variables documentation page and Jekyll::Site 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:

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:

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:

Chapter 1.3 - Converters

Converters

If you have a new markup language you’d like to use with your site, you can include it by implementing your own converter. Both the Markdown and Textile markup languages are implemented using this method.

Below is a converter that will take all posts ending in .upcase and process them using the UpcaseConverter:

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

Converters should implement at a minimum 3 methods:

In our example, UpcaseConverter#matches checks if our filename extension is .upcase, and will render using the converter if it is. It will call UpcaseConverter#convert to process the content. In our simple converter we’re simply uppercasing the entire content string. Finally, when it saves the page, it will do so with a .html extension.

Chapter 1.4 - Commands

Commands

As of version 2.5.0, Jekyll can be extended with plugins which provide subcommands for the jekyll executable. This is possible by including the relevant plugins in a Gemfile group called :jekyll_plugins:

group :jekyll_plugins do
  gem "my_fancy_jekyll_plugin"
end

Each Command must be a subclass of the Jekyll::Command class and must contain one class method: init_with_program. An example:

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

Commands should implement this single class method:

Chapter 1.5 - Tags 'n' Filters

Tags ‘n’ Filters

If you’d like to include custom liquid tags in your site, you can do so by hooking into the tagging system. Built-in examples added by Jekyll include the highlight and include tags. Below is an example of a custom liquid tag that will output the time the page was rendered:

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)

At a minimum, liquid tags must implement:

You must also register the custom tag with the Liquid template engine as follows:

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

In the example above, we can place the following tag anywhere in one of our pages:

<p>{% render_time page rendered at: %}</p>

And we would get something like this on the page:

<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>

Liquid filters

You can add your own filters to the Liquid template system much like you can add tags above. Filters are simply modules that export their methods to liquid. All methods will have to take at least one parameter which represents the input of the filter. The return value will be the output of the filter.

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)

Chapter 1.6 - Hooks

Hooks

Using hooks, your plugin can exercise fine-grained control over various aspects of the build process. If your plugin defines any hooks, Jekyll will call them at pre-defined points.

Hooks are registered to a container and an event name. To register one, you call Jekyll::Hooks.register, and pass the container, event name, and code to call whenever the hook is triggered. For example, if you want to execute some custom functionality every time Jekyll renders a post, you could register a hook like this:

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

end

Jekyll provides hooks for :site, :pages, :posts, and :documents. In all cases, Jekyll calls your hooks with the container object as the first callback parameter. But in the case of :pre_render, your hook will also receive a payload hash as a second parameter which allows you full control over the variables that are available while rendering.

The complete list of available hooks is below:

Chapter 1.7 - Custom Markdown Processors

Custom Markdown Processors

If you’re interested in creating a custom markdown processor, you’re in luck! Create a new class in the Jekyll::Converters::Markdown namespace:

class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'
    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'
    STDERR.puts '  $ [sudo] gem install funky_markdown'
    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end

Once you’ve created your class and have it properly set up either as a plugin in the _plugins folder or as a gem, specify it in your _config.yml:

markdown: MyCustomProcessor

Chapter 1.8 - Tips 'n' Tricks

Flags

There are two flags to be aware of when writing a plugin:

To use one of the example plugins above as an illustration, here is how you’d specify these two flags:

module Jekyll
  class UpcaseConverter < Converter
    safe true
    priority :low
    ...
  end
end