Hyde Press

Simple • Static • Blog-aware

Jekyll Plugin Developer's Guide (Book Edition)

by Tom Preston-Werner, Nick Quaranto, Parker Moore, et al

Contents

Preface

Note: The book edition is still an early release and a work-in-progess.

This is the (official) documentation for the Jekyll static site builder / generator reformatted in a single-page book edition.

See the source repo for how the book gets auto-built with "plain" Jekyll - of course - and hosted on GitHub Pages.

Questions? Comments? Send them to the Jekyll Talk forum post titled Jekyll Docu Reformatted as a Single-Page in Black 'n' White (Book Version) - Why? Why Not?.

Onwards.

Acknowledgments

Thanks to all Jekyll contributors for making it all possible.

Part 1 - Development

Chapter 1.1 - Plugins

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

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

Chapter 1.2 - Generators

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.

Chapter 1.3 - Converters

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.

Chapter 1.4 - Commands

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.

Chapter 1.5 - Tags 'n' Filters

Tags ‘n’ Filters

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.

Chapter 1.6 - Hooks

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. 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

Chapter 1.7 - Custom Markdown Processors

Custom Markdown Processors

If you’re interested in creating a custom markdown processor, you’re in luck! Create a new class in the Jekyll::Converters::Markdown namespace:

class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'
    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'
    STDERR.puts '  $ [sudo] gem install funky_markdown'
    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end

Once you’ve created your class and have it properly set up either as a plugin in the _plugins folder or as a gem, specify it in your _config.yml:

markdown: MyCustomProcessor

Chapter 1.8 - Tips 'n' Tricks

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