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, :documents and :clean. In all cases, Jekyll calls your hooks with the container object as the first callback parameter. All :pre_render hooks and the:site, :post_render hook will also provide a payload hash as a second parameter. In the case of :pre_render, the payload gives you full control over the variables that are available while rendering. In the case of :site, :post_render, the payload contains final values after rendering all the site (useful for sitemaps, feeds, etc).

The complete list of available hooks is below:

Container Event Called

:site

:after_init

Just after the site initializes, but before setup & render. Good for modifying the configuration of the site.

: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

:clean

:on_obsolete

During the cleanup of a site's destination before it is built