Hyde Press

Jekyll Plugin Developer's Guide (Book Edition)

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

Development Plugins Generators Converters Commands Tags 'n' Filters Hooks Custom Markdown Processors Tips 'n' Tricks

Contents

Preface

Simple • Static • Blog-aware

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: Generators Converters Commands 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 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