Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

387 lines (326 sloc) 18.579 kb
layout title prev_section next_section

Jekyll has a plugin system with hooks that allow you to create custom generated content specific to your site. You can run custom code for your site without having to modify the Jekyll source itself.

Plugins on GitHub Pages

GitHub Pages are powered by Jekyll, however all Pages sites are generated using the --safe option to disable custom plugins for security reasons. Unfortunately, this means your plugins won’t work if you’re deploying to GitHub Pages.

Installing a plugin

In your site source root, make a _plugins directory. Place your plugins here. Any file ending in *.rb inside this directory will be required when Jekyll generates your site.

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

  1. Generators
  2. Converters
  3. Tags


You can create a generator when you need Jekyll to create additional content based on your own rules. For example, a generator might look like this:

{% highlight ruby %} module Jekyll

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

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

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


class CategoryPageGenerator < Generator safe true

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


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


String output of the content being generated.


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

Remember your YAML front-matter

Jekyll will only convert files that have a YAML header at the top, even for converters you add using a plugin. If there is no YAML header, Jekyll will ignore the file and not send it through the converter.

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

{% highlight ruby %} module Jekyll class UpcaseConverter < Converter safe true priority :low

def matches(ext)
  ext =~ /upcase/i

def output_ext(ext)

def convert(content)

end end {% endhighlight %}

Converters should implement at a minimum 3 methods:

Method Description


Called to determine whether the specific converter will run on the page.


The extension of the outputted file, usually this will be .html


Logic to do the content conversion

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 capitalizing the entire content string. Finally, when it saves the page, it will do so with the .html extension.

Note that converters run on your file before liquid tags are evaluated.


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 custom liquid tag that will output the time the page was rendered:

{% highlight ruby %} module Jekyll class RenderTimeTag < Liquid::Tag

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

def render(context)
  "#{@text} #{}"

end end

Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag) {% endhighlight %}

At a minimum, liquid tags must implement:

Method Description


Outputs the content of the tag.

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

{% highlight ruby %} Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag) {% endhighlight %}

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

{% highlight ruby %}

{{"{% render_time page rendered at: "}}%}

{% endhighlight %}

And we would get something like this on the page:

{% highlight html %}

page rendered at: Tue June 22 23:38:47 –0500 2010

{% endhighlight %}

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.

{% highlight ruby %} module Jekyll module AssetFilter def asset_url(input) "{input}?#{}" end end end

Liquid::Template.register_filter(Jekyll::AssetFilter) {% endhighlight %}

ProTip™: Access the site object using Liquid

Jekyll lets you access the site object through the context.registers feature of liquid. For example, you can access the global configuration file _config.yml using context.registers.config.


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

Flag Description


A boolean flag that allows a plugin to be safely included in Jekyll core for exclusion from use with GitHub Pages. In general, set this to true.


This flag determines what order the plugin is loaded in. Valid values are: :lowest, :low, :normal, :high, and :highest.

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

{% highlight ruby %} module Jekyll class UpcaseConverter < Converter safe true priority :low ... end end {% endhighlight %}

Available Plugins

There are a few useful, prebuilt plugins at the following locations:

Jekyll Plugins Wanted

If you have a Jekyll plugin that you would like to see added to this list, you should read the contributing page to find out how to make that happen.

Jump to Line
Something went wrong with that request. Please try again.