Documentation Configuration 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 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