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.

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