Hooks (Advanced)

You can define custom functions that are run before a file is processed by Aurora. You can use this feature to save metadata about a page that can then be consumed by a template.

These functions are called "hooks".

There are three types of hooks, which run:

  1. As a jinja2 filter you can access on all pages (template_filters hook)
  2. Immediately before a page is generated (pre_generation hook)
  3. After your site has built (post_build hook)

To define a hook, you need to:

  1. Write a hook function with the right type signature, and;
  2. Add the hook function to the HOOKS dictionary in your config.py file.

Below are instructions on how to define each type of hook.

Filter Hooks

Filter hooks are registered as a jinja2 filter.

These hooks are useful for manipulating specific values in a template (i.e. formatting dates, changing text).

The type signature of this hook is:


def hook_name(text: str) -> str:
    return text.upper()

You can register this hook in the template_filter hook:


HOOKS = {
    "template_filter": {
        "example": ["hook_name"]
    }
}

This hook can then be used in any template on your website:


<h1> "hello world" | hook_name </h1>

Pre-Generation Hooks

Pre-generation hooks run immediately before a page is generated.

These hooks are useful for adding state to a page for use in rendering (i.e. loading link prveiews from a cache, calculating reading times.)

The type signature of this hook is:


def hook_name(file_name: str, page_state: dict, site_state: dict) -> dict:
    return page_state

You can register this hook in the template_filter hook:


HOOKS = {
    "pre_generation": {
        "example": ["hook_name"]
    }
}

Post-Build Hooks

Post-build hooks run after your site has been built.

These hooks are useful for performing actions after your site has been built (i.e. saving a log of last generation time, invoking CSS/JS minification).

The type signature of this hook is:


def hook_name(site_state: str) -> None:
    pass

You can register this hook in the template_filter hook:


HOOKS = {
    "post_build": {
        "example": ["hook_name"]
    }
}