Your first plugin

Plugins allow you to extend Jekyll’s behavior to fit your needs. There are six types of plugins in Jekyll.

Generators

Generators create content on your site. For example:

Converters

Converters change a markup language into another format. For example:

Commands

Commands extend the jekyll executable with subcommands. For example:

Tags

Tags create custom Liquid tags. For example:

Filters

Filters create custom Liquid filters. For example:

Hooks

Hooks give fine-grained control to extend the build process.

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

Best Practices

The guides help you with the specifics of creating plugins. We also have some recommended best practices to help structure your plugin.

We recommend using a gem for your plugin. This will help you manage dependencies, keep separation from your site source code and allow you to share functionality across multiple projects. For tips on creating a gem take a look a the Ruby gems guide or look through the source code of an existing plugin such as jekyll-feed.