W3cubDocs

/Jekyll 4

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 an owner and an event name. To register one, you call Jekyll::Hooks.register, and pass the hook owner, 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 page, you could register a hook like this:

Jekyll::Hooks.register :pages, :post_render do |page|
  # code to call after Jekyll renders a page
end

Note: The :post_convert events mentioned hereafter is a feature introduced in v4.2.0.

Out of the box, Jekyll has pre-defined hook points for owners :site, :pages, :documents and :clean. Additionally, the hook points defined for :documents can be utilized for individual collections only by invoking the collection type instead. i.e. :posts for documents in collection _posts and :movies for documents in collection _movies. In all cases, Jekyll calls your hooks with the owner object as the first callback parameter.

Every registered hook owner supports the following events — :post_init, :pre_render, :post_convert, :post_render, :post_write — however, the :site owner is set up to respond to special event names. Refer to the subsequent section for details.

All :pre_render hooks and the :site, :post_render hook will also provide a payload hash as a second parameter. While in the case of :pre_render events, the payload gives you full control over the variables that are available during rendering, with the :site, :post_render event, the payload contains final values after rendering all the site (useful for sitemaps, feeds, etc).

Built-in Hook Owners and Events

The complete list of available hooks:

Owner	Event	Triggered at
`:site` Encompasses the entire site	`:after_init`	Just after the site initializes. Good for modifying the configuration of the site. Triggered once per build / serve session
	`:after_reset`	Just after the site resets during regeneration
	`:post_read`	After all source files have been read and loaded from disk
	`:pre_render`	Just before rendering the whole site
	`:post_render`	After rendering the whole site, but before writing any files
	`:post_write`	After writing all of the rendered files to disk
`:pages` Allows fine-grained control over all pages in the site	`:post_init`	Whenever a page is initialized
	`:pre_render`	Just before rendering a page
	`:post_convert`	After converting the page content, but before rendering the page layout
	`:post_render`	After rendering a page, but before writing it to disk
	`:post_write`	After writing a page to disk
`:documents` Allows fine-grained control over all documents in the site including posts and documents in user-defined collections	`:post_init`	Whenever any document is initialized
	`:pre_render`	Just before rendering a document
	`:post_convert`	After converting the document content, but before rendering the document layout
	`:post_render`	After rendering a document, but before writing it to disk
	`:post_write`	After writing a document to disk
`:posts` Allows fine-grained control over all posts in the site without affecting documents in user-defined collections	`:post_init`	Whenever a post is initialized
	`:pre_render`	Just before rendering a post
	`:post_convert`	After converting the post content, but before rendering the postlayout
	`:post_render`	After rendering a post, but before writing it to disk
	`:post_write`	After writing a post to disk
`:clean` Fine-grained control on the list of obsolete files determined to be deleted during the site's cleanup phase.	`:on_obsolete`	During the cleanup of a site's destination before it is built

Hooks for custom Jekyll objects

You can also register and trigger hooks for Jekyll objects introduced by your plugin. All it takes is placing trigger calls under a suitable owner name, at positons desired within your custom class and registering the owner by your plugin.

To illustrate, consider the following plugin that implements custom functionality for every custom Excerpt object initialized:

module Foobar
  class HookedExcerpt < Jekyll::Excerpt
    def initialize(doc)
      super
      trigger_hooks(:post_init)
    end

    def output
      @output ||= trigger_hooks(:post_render, renderer.run)
    end

    def renderer
      @renderer ||= Jekyll::Renderer.new(
        doc.site, self, site.site_payload
      )
    end

    def trigger_hooks(hook_name, *args)
      Jekyll::Hooks.trigger :excerpts, hook_name, self, *args
    end
  end
end

Jekyll::Hooks.register :excerpts, :post_init do |excerpt|
  Jekyll.logger.debug "Initialized:",
                      "Hooked Excerpt for #{excerpt.doc.inspect}"
end

Jekyll::Hooks.register :excerpts, :post_render do |excerpt, output|
  return output unless excerpt.doc.type == :posts
  Foobar.transform(output)
end