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:

• jekyll-feed creates an Atom feed of blog posts.
• jekyll-archives creates archive pages for blog categories and tags.
• jekyll-sitemap creates a sitemap.

Converters

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

• jekyll-textile-converter converts textile to HTML.
• jekyll-coffeescript converts Coffeescript to JavaScript.
• jekyll-opal converts Ruby to JavaScript.

Commands

Commands extend the jekyll executable with subcommands. For example:

• jekyll-compose adds subcommands for creating a post, page or draft.

Tags

Tags create custom Liquid tags. For example:

• jekyll-youtube embeds a YouTube video.
• jekyll-asset-path-plugin outputs a relative URL for assets.
• jekyll-swfobject embeds a SWF object.

Filters

Filters create custom Liquid filters. For example:

• jekyll-time-ago - The distance between two dates in words.
• jekyll-toc - Generates a table of content.
• jekyll-email-protect - Obfuscates emails to protect them from spam bots.

Hooks

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

• jemoji Display emojis
• jekyll-mentions turns mentions @jekyll into links
• jekyll-spaceship - advanced example. Provides powerful supports for table, mathjax, plantuml, video, etc.

Flags

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

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 at the Ruby gems guide or look through the source code of an existing plugin such as jekyll-feed.