Skip to content

Latest commit

 

History

History
891 lines (789 loc) · 42 KB

plugins.md

File metadata and controls

891 lines (789 loc) · 42 KB
Raw
layout title permalink
docs
Plugins
/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 3 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.

    Then install your plugins using gem install jekyll-test-plugin jekyll-jsonify jekyll-assets

  3. Add the relevant plugins to a Bundler group in your Gemfile. An example:

     group :jekyll_plugins do
   gem "my-jekyll-plugin"
   gem "another-jekyll-plugin"
 end

    Now you need to install all plugins from your Bundler group by running single command bundle install

_plugins, _config.yml and Gemfile can be used simultaneously

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

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

  1. Generators
  2. Converters
  3. Commands
  4. 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]({{ 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 YAML Front Matters 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 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:

{% 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.each_key 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.

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:

{% highlight ruby %} group :jekyll_plugins do gem "my_fancy_jekyll_plugin" end {% endhighlight %}

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

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

Commands should implement this single class method:

Method Description

init_with_program

This method accepts one parameter, the Mercenary::Program instance, which is the Jekyll program itself. Upon the program, commands may be created using the above syntax. For more details, visit the Mercenary repository on GitHub.com.

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

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:

{% highlight ruby %} Jekyll::Hooks.register :posts, :post_render do |post|

code to call after Jekyll renders a post

end {% endhighlight %}

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:

Container Event Called

:site

:after_reset

Just after site reset

:site

:post_read

After site data has been read and loaded from disk

:site

:pre_render

Just before rendering the whole site

:site

:post_render

After rendering the whole site, but before writing any files

:site

:post_write

After writing the whole site to disk

:pages

:post_init

Whenever a page is initialized

:pages

:pre_render

Just before rendering a page

:pages

:post_render

After rendering a page, but before writing it to disk

:pages

:post_write

After writing a page to disk

:posts

:post_init

Whenever a post is initialized

:posts

:pre_render

Just before rendering a post

:posts

:post_render

After rendering a post, but before writing it to disk

:posts

:post_write

After writing a post to disk

:documents

:post_init

Whenever a document is initialized

:documents

:pre_render

Just before rendering a document

:documents

:post_render

After rendering a document, but before writing it to disk

:documents

:post_write

After writing a document to disk

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 id="extended"> tag.
  • i18n_filter: Liquid filter to use I18n localization.
  • Smilify by SaswatPadhi: Convert text emoticons in your content to themeable smiley pics.
  • 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 grammatically-correct amount like “1 minute” or “2 minutes”.
  • 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".
  • Deprecated articles keeper by Kazuya Kobayashi: A simple Jekyll filter which monitor how old an article is.
  • Jekyll-jalali by Mehdi Sadeghi: A simple Gregorian to Jalali date converter filter.
  • Jekyll Thumbnail Filter: Related posts thumbnail filter.
  • Jekyll-Smartify: SmartyPants filter. Make "quotes" “curly”
  • liquid-md5: Returns an MD5 hash. Helpful for generating Gravatars in templates.

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.
  • markdown-writer: An Atom package for Jekyll. It can create new posts/drafts, manage tags/categories, insert link/images and add many useful key mappings.
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.