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 an owner and an event name. 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

# or using the hooks API directly:
Bridgetown::Hooks.register_one :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 hooks API directly.

Bridgetown provides hooks for :site, :resources, :loader, :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 owner 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

Bridgetown::Hooks.register_one :posts, :post_render, priority: :low do |post|
  # Low priority code to call after Bridgetown renders a post
end

Reloadable vs. Non-Reloadable Hooks #

All hooks are cleared during watch mode (aka bridgetown build -w or bridgetown start) 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 #

Owner	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 and all internal data structures are in a pristine state. Not run during SSR (see below).
`:site`	`:after_soft_reset`	When a site is in SSR mode, any file changes result in a "soft" reset for performance reasons. Some state is persisted across resets. You can register a hook to perform additional cleanup/setup after a soft reset.
`: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
`:site`	`:pre_reload`	Just before reloading site plugins and Zeitwerk autoloaders during the watch process or in the console
`:site`	`:post_reload`	After reloading site plugins and Zeitwerk autoloaders during the watch process or in the console
`:resources` `[collection_label]`	`:post_init`	Whenever a resource is initialized
`:resources` `[collection_label]`	`:post_read`	Whenever a resource has read all of its data from the origin model, but before rendering/transformation
`:resources` `[collection_label]`	`:pre_render`	Just before rendering a resource
`:resources` `[collection_label]`	`:post_render`	After rendering a resource, but before writing it to disk
`:resources` `[collection_label]`	`:post_write`	After writing a resource to disk
`:generated_pages`	`:post_init`	Whenever a page is initialized
`:generated_pages`	`:pre_render`	Just before rendering a page
`:generated_pages`	`:post_render`	After rendering a page, but before writing it to disk
`:generated_pages`	`:post_write`	After writing a page to disk
`:loader`	`:pre_setup`	Before initial setup of a Zeitwerk autoloader. The `loader` object and `load_path` are provided as arguments.
`:loader`	`:post_setup`	After initial setup of a Zeitwerk autoloader. The `loader` object and `load_path` are provided as arguments.
`:loader`	`:pre_reload`	Before a Zeitwerk autoloader reloads all code under its supervision. The `loader` object and `load_path` are provided as arguments.
`:loader`	`:post_reload`	After a Zeitwerk autoloader reloads all code under its supervision. The `loader` object and `load_path` are provided as arguments.
`:clean`	`:on_obsolete`	During the cleanup of a site's destination before it is built

Back to Plugins