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:
- 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. -
In your
_config.yml
file, add a new array with the keygems
and the values of the gem names of the plugins you’d like to use. An example:gems: [jekyll-coffeescript, jekyll-watch, jekyll-assets] # This will require each of these gems automatically.
Then install your plugins using
gem install jekyll-coffeescript jekyll-watch jekyll-assets
-
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:
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:
This is a more complex generator that generates new pages:
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 |
---|---|
|
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
:
Converters should implement at a minimum 3 methods:
Method | Description |
---|---|
|
Does the given extension match this converter’s list of acceptable
extensions? Takes one argument: the file’s extension (including the
dot). Must return |
|
The extension to be given to the output file (including the dot).
Usually this will be |
|
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
:
Each Command
must be a subclass of the Jekyll::Command
class and must
contain one class method: init_with_program
. An example:
Commands should implement this single class method:
Method | Description |
---|---|
|
This method accepts one parameter, the
|
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:
At a minimum, liquid tags must implement:
Method | Description |
---|---|
|
Outputs the content of the tag. |
You must also register the custom tag with the Liquid template engine as follows:
In the example above, we can place the following tag anywhere in one of our pages:
And we would get something like this on the page:
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.
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 |
---|---|
|
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 |
|
This flag determines what order the plugin is loaded in. Valid values
are: |
To use one of the example plugins above as an illustration, here is how you’d specify these two flags:
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 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 |
---|---|---|
|
|
Just after site reset |
|
|
After site data has been read and loaded from disk |
|
|
Just before rendering the whole site |
|
|
After rendering the whole site, but before writing any files |
|
|
After writing the whole site to disk |
|
|
Whenever a page is initialized |
|
|
Just before rendering a page |
|
|
After rendering a page, but before writing it to disk |
|
|
After writing a page to disk |
|
|
Whenever a post is initialized |
|
|
Just before rendering a post |
|
|
After rendering a post, but before writing it to disk |
|
|
After writing a post to disk |
|
|
Whenever a document is initialized |
|
|
Just before rendering a document |
|
|
After rendering a document, but before writing it to disk |
|
|
After writing a document to disk |
Available Plugins
You can find a few useful plugins at the following locations:
Generators
- ArchiveGenerator by Ilkka Laukkanen: Uses this archive page to generate archives.
- LESS.js Generator by Andy Fowler: Renders LESS.js files during generation.
- Version Reporter by Blake Smith: Creates a version.html file containing the Jekyll version.
- Sitemap.xml Generator by Michael Levin: Generates a sitemap.xml file by traversing all of the available posts and pages.
- Full-text search by Pascal Widdershoven: Adds full-text search to your Jekyll site with a plugin and a bit of JavaScript.
- AliasGenerator by Thomas Mango: Generates redirect pages for posts when an alias is specified in the YAML Front Matter.
- Pageless Redirect Generator by Nick Quinlan: Generates redirects based on files in the Jekyll root, with support for htaccess style redirects.
- RssGenerator by Assaf Gelber: Automatically creates an RSS 2.0 feed from your posts.
- Monthly archive generator by Shigeya Suzuki: Generator and template which renders monthly archive like MovableType style, based on the work by Ilkka Laukkanen and others above.
- Category archive generator by Shigeya Suzuki: Generator and template which renders category archive like MovableType style, based on Monthly archive generator.
- Emoji for Jekyll: Seamlessly enable emoji for all posts and pages.
- Compass integration for Jekyll: Easily integrate Compass and Sass with your Jekyll website.
- Pages Directory by Ben Baker-Smith: Defines a
_pages
directory for page files which routes its output relative to the project root. - Page Collections by Jeff Kolesky: Generates collections of pages with functionality that resembles posts.
- Windows 8.1 Live Tile Generation by Matt Sheehan: Generates Internet Explorer 11 config.xml file and Tile Templates for pinning your site to Windows 8.1.
- Typescript Generator by Matt Sheehan: Generate Javascript on build from your Typescript.
- Jekyll::AutolinkEmail by Ivan Tse: Autolink your emails.
- Jekyll::GitMetadata by Ivan Tse: Expose Git metadata for your templates.
- Jekyll Http Basic Auth Plugin: Plugin to manage http basic auth for jekyll generated pages and directories.
- Jekyll Auto Image by Merlos: Gets the first image of a post. Useful to list your posts with images or to add twitter cards to your site.
- Jekyll Portfolio Generator by Shannon Babincsak: Generates project pages and computes related projects out of project data files.
- Jekyll-Umlauts by Arne Gockeln: This generator replaces all german umlauts (äöüß) case sensitive with html.
- Jekyll Flickr Plugin by Lawrence Murray: Generates posts for photos uploaded to a Flickr photostream.
- Jekyll::Paginate::Category: Pagination Generator for Jekyll Category.
Converters
- Textile converter: Convert
.textile
files into HTML. Also includes thetextilize
Liquid filter. - Slim plugin: Slim converter and includes for Jekyll with support for Liquid tags.
- Jade plugin by John Papandriopoulos: Jade converter for Jekyll.
- HAML plugin by Sam Z: HAML converter for Jekyll.
- HAML-Sass Converter by Adam Pearson: Simple HAML-Sass converter for Jekyll. Fork by Sam X.
- Sass SCSS Converter by Mark Wolfe: Sass converter which uses the new CSS compatible syntax, based Sam X’s fork above.
- LESS Converter by Jason Graham: Convert LESS files to CSS.
- LESS Converter by Josh Brown: Simple LESS converter.
- Upcase Converter by Blake Smith: An example Jekyll converter.
- CoffeeScript Converter by phaer: A CoffeeScript to Javascript converter.
- Markdown References by Olov Lassus: Keep all your markdown reference-style link definitions in one _references.md file.
- Stylus Converter: Convert .styl to .css.
- ReStructuredText Converter: Converts ReST documents to HTML with Pygments syntax highlighting.
- Jekyll-pandoc-plugin: Use pandoc for rendering markdown.
- Jekyll-pandoc-multiple-formats by edsl: Use pandoc to generate your site in multiple formats. Supports pandoc’s markdown extensions.
- Transform Layouts: Allows HAML layouts (you need a HAML Converter plugin for this to work).
- Org-mode Converter: Org-mode converter for Jekyll.
- Customized Kramdown Converter: Enable Pygments syntax highlighting for Kramdown-parsed fenced code blocks.
- Bigfootnotes Plugin: Enables big footnotes for Kramdown.
- AsciiDoc Plugin: AsciiDoc convertor for Jekyll using Asciidoctor.
- Lazy Tweet Embedding: Automatically convert tweet urls into twitter cards.
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.
- 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
Tags
- Asset Path Tag by Sam Rayner: Allows organisation of assets into subdirectories by outputting a path for a given file relative to the current post or page.
- Delicious Plugin by Christian Hellsten: Fetches and renders bookmarks from delicious.com.
- Ultraviolet Plugin by Steve Alex: Jekyll tag for the Ultraviolet code highligher.
- Tag Cloud Plugin by Ilkka Laukkanen: Generate a tag cloud that links to tag pages.
- GIT Tag by Alexandre Girard: Add Git activity inside a list.
- MathJax Liquid Tags by Jessy Cowan-Sharp: Simple liquid tags for Jekyll that convert inline math and block equations to the appropriate MathJax script tags.
- Non-JS Gist Tag by Brandon Tilley A Liquid tag that embeds Gists and shows code for non-JavaScript enabled browsers and readers.
- Render Time Tag by Blake Smith: Displays the time a Jekyll page was generated.
- Status.net/OStatus Tag by phaer: Displays the notices in a given status.net/ostatus feed.
- Embed.ly client by Robert Böhnke: Autogenerate embeds from URLs using oEmbed.
- Logarithmic Tag Cloud: Flexible. Logarithmic distribution. Documentation inline.
- oEmbed Tag by Tammo van Lessen: Enables easy content embedding (e.g. from YouTube, Flickr, Slideshare) via oEmbed.
- FlickrSetTag by Thomas Mango: Generates image galleries from Flickr sets.
- Tweet Tag by Scott W. Bradley: Liquid tag for Embedded Tweets using Twitter’s shortcodes.
- Jekyll Twitter Plugin: A Liquid tag plugin that renders Tweets from Twitter API. Currently supports the oEmbed API.
- Jekyll-contentblocks: Lets you use Rails-like content_for tags in your templates, for passing content from your posts up to your layouts.
- Generate YouTube Embed by joelverhagen: Jekyll plugin which allows you to embed a YouTube video in your page with the YouTube ID. Optionally specify width and height dimensions. Like “oEmbed Tag” but just for YouTube.
- Jekyll-beastiepress: FreeBSD utility tags for Jekyll sites.
- Jsonball: Reads json files and produces maps for use in Jekyll files.
- Bibjekyll: Render BibTeX-formatted bibliographies/citations included in posts and pages using bibtex2html.
- Jekyll-citation: Render BibTeX-formatted bibliographies/citations included in posts and pages (pure Ruby).
- Jekyll Dribbble Set Tag: Builds Dribbble image galleries from any user.
- Debbugs: Allows posting links to Debian BTS easily.
- Refheap_tag: Liquid tag that allows embedding pastes from refheap.
- Jekyll-devonly_tag: A block tag for including markup only during development.
- JekyllGalleryTag by redwallhp: Generates thumbnails from a directory of images and displays them in a grid.
- Youku and Tudou Embed: Liquid plugin for embedding Youku and Tudou videos.
- Jekyll-swfobject: Liquid plugin for embedding Adobe Flash files (.swf) using SWFObject.
- Jekyll Picture Tag: Easy responsive images for Jekyll. Based on the proposed
<picture>
element, polyfilled with Scott Jehl’s Picturefill. - Jekyll Image Tag: Better images for Jekyll. Save image presets, generate resized images, and add classes, alt text, and other attributes.
- Jekyll Responsive Image: Responsive images for Jekyll. Automatically resizes images, supports all responsive methods (
<picture>
,srcset
, Imager.js, etc), super-flexible configuration. - Ditaa Tag by matze: Renders ASCII diagram art into PNG images and inserts a figure tag.
- Jekyll Suggested Tweet by David Ensinger: A Liquid tag for Jekyll that allows for the embedding of suggested tweets via Twitter’s Web Intents API.
- Jekyll Date Chart by GSI: Block that renders date line charts based on textile-formatted tables.
- Jekyll Image Encode by GSI: Tag that renders base64 codes of images fetched from the web.
- Jekyll Quick Man by GSI: Tag that renders pretty links to man page sources on the internet.
- jekyll-font-awesome: Quickly and easily add Font Awesome icons to your posts.
- Lychee Gallery Tag by tobru: Include Lychee albums into a post. For an introduction, see Jekyll meets Lychee - A Liquid Tag plugin
- Image Set/Gallery Tag by callmeed: Renders HTML for an image gallery from a folder in your Jekyll site. Just pass it a folder name and class/tag options.
- jekyll_figure: Generate figures and captions with links to the figure in a variety of formats
- Jekyll Github Sample Tag: A liquid tag to include a sample of a github repo file in your Jekyll site.
- Jekyll Project Version Tag: A Liquid tag plugin that renders a version identifier for your Jekyll site sourced from the git repository containing your code.
- Piwigo Gallery by Alessandro Lorenzi: Jekyll plugin to generate thumbnails from a Piwigo gallery and display them with a Liquid tag
- mathml.rb by Tom Thorogood: A plugin to convert TeX mathematics into MathML for display.
- webmention_io.rb by Aaron Gustafson: A plugin to enable webmention integration using Webmention.io. Includes an optional JavaScript for updating webmentions automatically between publishes and, if available, in realtime using WebSockets.
- Jekyll 500px Embed by Luke Korth. A Liquid tag plugin that embeds 500px photos.
- inline_highlight: A tag for inline syntax highlighting.
- jekyll-mermaid: Simplify the creation of mermaid diagrams and flowcharts in your posts and pages.
- twa: Twemoji Awesome plugin for Jekyll. Liquid tag allowing you to use twitter emoji in your jekyll pages.
- jekyll-files by Zhi-Wei Cai: Output relative path strings and other info regarding specific assets.
- Fetch remote file content by Dimitri König: Using
remote_file_content
tag you can fetch the content of a remote file and include it as if you would put the content right into your markdown file yourself. Very useful for including code from github repo’s to always have a current repo version. - jekyll-asciinema: A tag for embedding asciicasts recorded with asciinema in your Jekyll pages.
- Jekyll-Youtube A Liquid tag that embeds Youtube videos. The default emded markup is responsive but you can also specify your own by using an include/partial.
- Jekyll Flickr Plugin by Lawrence Murray: Embeds Flickr photosets (albums) as a gallery of thumbnails, with lightbox links to larger images.
- jekyll-figure: A liquid tag for Jekyll that generates
<figure>
elements.
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
- 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. - 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-asset_bundler: Bundles and minifies JavaScript and CSS.
- 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 builing 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.
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.