site/docs/plugins

layout: docs
title: Plugins
prev_section: pagination
next_section: extras

permalink: /docs/plugins/

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 is 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.

You can still use GitHub Pages to publish your site, but you’ll need to convert the site locally and push the generated static files to your GitHub repository instead of the Jekyll source files.

Installing a plugin

You have 2 options for installing plugins:

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

  2. In your _config.yml file, add a new array with the key gems and the values
    of the gem names of the plugins you’d like to use. An example:

    gems: [jekyll-test-plugin, jekyll-jsonify, jekyll-assets]
    # This will require each of these gems automatically.

_plugins and gems can be used simultaneously

You may use both of the aforementioned plugin options simultaneously in the same site if you so choose. Use of one does not restrict the use of the other

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

  1. Generators
  2. Converters
  3. Tags

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.

Generation is triggered for its side-effects, the return value of generate is
ignored. Jekyll does not assume any particular side-effect to happen, it just
runs the method.

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:

{% 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.keys.each 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.

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.

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.

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
end

def output_ext(ext)
“.html”
end

def convert(content)
content.upcase
end
end
end
{% endhighlight %}

Converters should implement at a minimum 3 methods:

Method Description

matches

Does the given extension match this converter’s list of acceptable extensions? Takes one argument: the file’s extension (including the dot). Must return true if it matches, false otherwise.

output_ext

The extension to be given to the output file (including the dot). Usually this will be ".html".

convert

Logic to do the content conversion. Takes one argument: the raw content of the file (without YAML front matter). Must return a String.

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.

Tags

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:

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

At a minimum, liquid tags must implement:

Method Description

render

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 %}
{% raw %}

{% render_time page rendered at: %}

{% endraw %}
{% 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)
“http://www.example.com/#{input}?#{Time.now.to_i}”
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 at context.registers[:site]. For example, you can access the global configuration file _config.yml using context.registers[:site].config.

Flags

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

Flag Description

safe

A boolean flag that informs Jekyll whether this plugin may be safely executed in an environment where arbitrary code execution is not allowed. This is used by GitHub Pages to determine which core plugins may be used, and which are unsafe to run. If your plugin does not allow for arbitrary code, execution, set this to true. GitHub Pages still won’t load your plugin, but if you submit it for inclusion in core, it’s best for this to be correct!

priority

This flag determines what order the plugin is loaded in. Valid values are: :lowest, :low, :normal, :high, and :highest. Highest priority matches are applied first, lowest priority are applied last.

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

You can find a few useful plugins at the following locations:

Generators

Converters

Filters

  • Truncate HTML by Matt Hall: A Jekyll filter that truncates HTML while preserving markup structure.
  • Domain Name Filter by Lawrence Woodman: Filters the input text so that just the domain name is left.
  • Summarize Filter by Mathieu Arnold: Remove markup after a <div> tag.
  • URL encoding by James An: Percent encoding for URIs.
  • JSON Filter by joelverhagen: Filter that takes input text and outputs it as JSON. Great for rendering JavaScript.
  • i18n_filter: Liquid filter to use I18n localization.
  • Smilify by SaswatPadhi: Convert text emoticons in your content to themeable smiley pics (Demo).
  • Read in X Minutes by zachleat: Estimates the reading time of a string (for blog post content).
  • Jekyll-timeago: Converts a time value to the time ago in words.
  • pluralize: Easily combine a number and a word into a gramatically-correct amount like “1 minute” or “2 minute*s*”.
  • reading_time: Count words and estimate reading time for a piece of text, ignoring HTML elements that are unlikely to contain running text.
  • Table of Content Generator: Generate the HTML code containing a table of content (TOC), the TOC can be customized in many way, for example you can decide which pages can be without TOC.
  • jekyll-humanize: This is a port of the Django app humanize which adds a “human touch” to data. Each method represents a Fluid type filter that can be used in your Jekyll site templates. Given that Jekyll produces static sites, some of the original methods do not make logical sense to port (e.g. naturaltime).
  • Jekyll-Ordinal: Jekyll liquid filter to output a date ordinal such as “st”, “nd”, “rd”, or “th”.

Tags

Collections

Other

Editors

  • sublime-jekyll: A Sublime Text package for Jekyll static sites. This package should help creating Jekyll sites and posts easier by providing access to key template tags and filters, as well as common completions and a current date/datetime command (for dating posts). You can install this package manually via GitHub, or via Package Control.
  • vim-jekyll: A vim plugin to generate new posts and run jekyll build all without leaving vim.
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.