Back to Plugins

Hooks

Using hooks, your plugin can exercise fine-grained control over various aspects of the build process. If your plugin defines any hooks, Bridgetown will call them at pre-defined points.

Hooks are registered to a container and an event name. To register one, you call Bridgetown::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 Bridgetown renders a post, you could register a hook like this:

# Builder API
def build
  hook :posts, :post_render do |post|
    # code to call after Bridgetown renders a post
  end
end
# Legacy API
Bridgetown::Hooks.register :posts, :post_render do |post|
  # code to call after Bridgetown renders a post
end

Be aware that the build method of the Builder API is called during the pre_read site event, so you won’t be able to write a hook for any earlier events (after_init for example). In those cases, you will still need to use the Legacy API.

Bridgetown provides hooks for :site, :pages, :documents, :clean, and :[collection_label] (aka every collection gets a unique hook, such as posts or countries or episodes, etc.).

In all cases, Bridgetown 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).

Post-Write Hook for Performing Special Operations

The :site, :post_write hook is particularly useful in that you can use it to kick off additional operations which need to happen after the site has been completely built and everything has been saved to the destination folder.

For example, there might be certain files you want to compress, or maybe you need to notify an external web service about new updates, or perhaps you’d like to run tests against the final output.

Priorities

Hooks can be registered with a priority of high, normal, or low, and are run according to that order. The default priority is normal. To register with a different priority other than normal:

# Builder API
def build
  hook :posts, :post_render, priority: :high do |post|
    # High priority code to call after Bridgetown renders a post
  end
end
# Legacy API
Bridgetown::Hooks.register :posts, :post_render, priority: :low do |post|
  # Low priority code to call after Bridgetown renders a post
end

Reloadable vs. Non-Reloadable Hooks

Starting with Bridgetown 0.14, all hooks are cleared during watch mode (aka bridgetown build -w or bridgetown serve) whenever plugin or content files are updated. This makes sense for plugins that are part of the site repository and are therefore reloaded automatically.

However, for gem-based plugins, you will want to make sure you define your hooks as non-reloadable, otherwise your hooks will vanish any time the site is updated during watch mode.

def build
  hook :site, :post_read, reloadable: false do |post|
    # do something with site data after it's read from disk
  end
end

Complete List of Hooks

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 (all internal data structures are in a pristine state)

:site

:pre_read

After site reset/setup when all custom plugins, generators, etc. have loaded

: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
:[collection_label]

:post_init

Whenever a post is initialized

:posts
:[collection_label]

:pre_render

Just before rendering a post

:posts
:[collection_label]

:post_render

After rendering a post, but before writing it to disk

:posts
:[collection_label]

:post_write

After writing a post to disk

:documents

:post_init

Whenever a document (in any collection) 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

Back to Plugins