Skip to content

Latest commit

 

History

History
384 lines (325 loc) · 18.1 KB

2012-07-01-plugins.md

File metadata and controls

384 lines (325 loc) · 18.1 KB
Raw
layout title prev_section next_section
docs
Plugins
assets
extras

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

Generators

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

String output of the content being generated.

Converters

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

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

output_ext

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

convert

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.

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

{{"{% 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) "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. For example, you can access the global configuration file _config.yml using context.registers.config.

Flags

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

Flag Description

safe

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.

priortiy

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.