Improve this page

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 plugins and the values of the gem names of the plugins you’d like to use. An example:

    # This will require each of these plugins automatically.
plugins:
  - jekyll-gist
  - jekyll-coffeescript
  - jekyll-assets
  - another-jekyll-plugin

    Then install your plugins using gem install jekyll-gist jekyll-coffeescript jekyll-assets another-jekyll-plugin

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

     group :jekyll_plugins do
   gem "jekyll-gist"
   gem "jekyll-coffeescript"
   gem "jekyll-assets"
   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.

The jekyll_plugins group

Jekyll gives this particular group of gems in your Gemfile a different treatment. Any gem included in this group is loaded before Jekyll starts processing the rest of your source directory.

A gem included here will be activated even if its not explicitly listed under the plugins: key in your site’s config file.

Gems included in the :jekyll-plugins group are activated regardless of the --safe mode setting. Be aware of what gems are included under this group!

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

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

See the bottom of the page for a list of available plugins

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:

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:

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:

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:

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:

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:

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:

Method Description

render

Outputs the content of the tag.

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

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

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. However, all :pre_render hooks and the:site, :post_render hook will also provide a payload hash as a second parameter. In the case of :pre_render, the payload gives you full control over the variables that are available while rendering. In the case of :site, :post_render, the payload contains final values after rendering all the site (useful for sitemaps, feeds, etc).

The complete list of available hooks is below:

Container Event Called

:site

:after_init

Just after the site initializes, but before setup & render. Good for modifying the configuration of the site.

: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.
  • 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-toc: A liquid filter plugin for Jekyll which generates a table of contents.
  • 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.
  • liquid-md5: Returns an MD5 hash. Helpful for generating Gravatars in templates.
  • jekyll-roman: A liquid filter for Jekyll that converts numbers into Roman numerals.
  • jekyll-typogrify: A Jekyll plugin that brings the functions of typogruby.
  • Jekyll Email Protect: Email protection liquid filter for Jekyll
  • Jekyll Uglify Filter: A Liquid filter that runs your JavaScript through UglifyJS.
  • match_regex: A Liquid filter to perform regex match.
  • replace_regex: A Liquid filter to perform regex replace.
  • Jekyll Money: A Jekyll plugin for dealing with money. Because we all have to at some point.

Tags

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

Collections

  • Jekyll Plugins by Recursive Design: Plugins to generate Project pages from GitHub readmes, a Category page, and a Sitemap generator.
  • Company website and blog plugins by Flatterline, a Ruby on Rails development company: Portfolio/project page generator, team/individual page generator, an author bio liquid tag for use on posts, and a few other smaller plugins.
  • Jekyll plugins by Aucor: Plugins for trimming unwanted newlines/whitespace and sorting pages by weight attribute.

Other

  • Analytics for Jekyll by Hendrik Schneider: An effortless way to add various trackers like Google Analytics, Piwik, etc. to your site
  • ditaa-ditaa by Tom Thorogood: a drastic revision of jekyll-ditaa that renders diagrams drawn using ASCII art into PNG images.
  • Pygments Cache Path by Raimonds Simanovskis: Plugin to cache syntax-highlighted code from Pygments.
  • Draft/Publish Plugin by Michael Ivey: Save posts as drafts.
  • Growl Notification Generator by Tate Johnson: Send Jekyll notifications to Growl.
  • Growl Notification Hook by Tate Johnson: Better alternative to the above, but requires his “hook” fork.
  • Related Posts by Lawrence Woodman: Overrides site.related_posts to use categories to assess relationship.
  • jekyll-tagging-related_posts: Jekyll related_posts function based on tags (works on Jekyll3).
  • Tiered Archives by Eli Naeher: Create tiered template variable that allows you to group archives by year and month.
  • Jekyll-localization: Jekyll plugin that adds localization features to the rendering engine.
  • Jekyll-rendering: Jekyll plugin to provide alternative rendering engines.
  • Jekyll-pagination: Jekyll plugin to extend the pagination generator.
  • Jekyll-tagging: Jekyll plugin to automatically generate a tag cloud and tag pages.
  • Jekyll-scholar: Jekyll extensions for the blogging scholar.
  • Jekyll-assets by ixti: Rails-alike assets pipeline (write assets in CoffeeScript, Sass, LESS etc; specify dependencies for automatic bundling using simple declarative comments in assets; minify and compress; use JST templates; cache bust; and many-many more).
  • JAPR: Jekyll Asset Pipeline Reborn - Powerful asset pipeline for Jekyll that collects, converts and compresses JavaScript and CSS assets.
  • File compressor by mytharcher: Compress HTML and JavaScript files on site build.
  • Jekyll-minibundle: Asset bundling and cache busting using external minification tool of your choice. No gem dependencies.
  • Singlepage-jekyll by JCB-K: Turns Jekyll into a dynamic one-page website.
  • generator-jekyllrb: A generator that wraps Jekyll in Yeoman, a tool collection and workflow for building modern web apps.
  • grunt-jekyll: A straightforward Grunt plugin for Jekyll.
  • jekyll-postfiles: Add _postfiles directory and {{ postfile }} tag so the files a post refers to will always be right there inside your repo.
  • A layout that compresses HTML: GitHub Pages compatible, configurable way to compress HTML files on site build.
  • Jekyll CO₂: Generates HTML showing the monthly change in atmospheric CO₂ at the Mauna Loa observatory in Hawaii.
  • remote-include: Includes files using remote URLs
  • jekyll-minifier: Minifies HTML, XML, CSS, and Javascript both inline and as separate files utilising yui-compressor and htmlcompressor.
  • Jekyll views router: Simple router between generator plugins and templates.
  • Jekyll Language Plugin: Jekyll 3.0-compatible multi-language plugin for posts, pages and includes.
  • Jekyll Deploy: Adds a deploy sub-command to Jekyll.
  • Official Contentful Jekyll Plugin: Adds a contentful sub-command to Jekyll to import data from Contentful.
  • jekyll-paspagon: Sell your posts in various formats for cryptocurrencies.
  • Hawkins: Adds a liveserve sub-command to Jekyll that incorporates LiveReload into your pages while you preview them. No more hitting the refresh button in your browser!
  • Jekyll Autoprefixer: Autoprefixer integration for Jekyll
  • Jekyll-breadcrumbs: Creates breadcrumbs for Jekyll 3.x, includes features like SEO optimization, optional breadcrumb item translation and more.
  • generator-jekyllized: A Yeoman generator for rapidly developing sites with Gulp. Live reload your site, automatically minify and optimize your assets and much more.
  • Jekyll-Spotify: Easily output Spotify Embed Player for jekyll
  • jekyll-menus: Hugo style menus for your Jekyll site… recursive menus included.
  • jekyll-data: Read data files within Jekyll Theme Gems.
  • jekyll-pinboard: Access your Pinboard bookmarks within your Jekyll theme.
  • jekyll-migrate-permalink: Adds a migrate-permalink sub-command to help deal with side effects of changing your permalink.
  • Jekyll-Post: A CLI tool to easily draft, edit, and publish Jekyll posts.
  • jekyll-numbered-headings: Adds ordered number to headings.
  • jekyll-pre-commit: A framework for running checks against your posts using a git pre-commit hook before you publish them.
  • jekyll-pwa-plugin: A plugin provides PWA support for Jekyll. It generates a service worker in Jekyll build process and makes precache and runtime cache available in the runtime with Google Workbox.
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.