Skip to content

feat: hook system enhancements (validation, strict mode, required hooks, reference docs) #1026

Description

@davidsneighbour

Umbrella of improvements for the hooks/filters system. Related: #965 (collector dump unreliable).

1. Validate required hook data

Extended hooks should require a hook key. Simple string input is valid; a map without hook (or with an empty hook) should print a clear warning/error, preventing confusing lookups like hooks/<no value>.html.

2. Support custom cache variants

Add a cacheVariant (or cacheKey) option so page-specific cached hooks don't collide:

{{- partials.Include "func/hooks/hook.html" (collections.Dictionary
    "hook" "content-card" "context" . "cache" true "cacheVariant" .RelPermalink) -}}

3. Add a strict mode

[params.ananke.hooks] strict = true — missing optional hooks only log; missing required hooks / invalid config fail the build.

4. Add required hooks

[params.ananke.hooks] required = ["head-end", "site-footer"] — fail/error if a required hook partial does not exist.

5. Document all available hook points

A central reference listing every hook: name, template location, hook vs filter, context passed, cache-safety, example use case.

6. Hook metadata collection output

Expose the collector's gathered info as a debug report (used / unused / missing-required hooks).

7. Consistent terminology

Keep terms stable in docs: hook prints immediately; filter returns output; hook partial is the user partial in layouts/partials/hooks/; hook point is where hook.html/filter.html is called.

Migrated from scratch/hooks.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions