Astral.Plugin behaviour (Astral v0.1.5)

Behaviour for Astral site plugins.

Plugins participate in site configuration, discovery, page rendering, and build lifecycle events. All callbacks except name/0 are optional.

Plugins may be configured as modules or {module, opts} tuples. When a plugin defines a callback with one extra arity, Astral passes tuple opts as the final argument.

Plugins can opt into Vite/Volt-style ordering with enforce/0 or enforce/1: :pre plugins run before normal plugins, and :post plugins run after them.

Summary

Types

plugin()

route_body()

route_headers()

Callbacks

build_done(result)

Run after a successful static build.

build_done(result, opts)

build_start(config)

Run before a static build starts.

build_start(config, opts)

config(config)

Transform the normalized site config before discovery/build/dev use.

config config, opts

enforce()

Return :pre, :post, or nil to control plugin ordering.

enforce(opts)

name()

Plugin name for identification and error messages.

render_page(html, page, site)

Transform rendered page HTML.

render_page(html, page, site, opts)

render_route(route, site)

Render a plugin-owned generated route.

render_route(route, site, opts)

routes(site)

Return generated routes such as feeds, sitemaps, tag pages, or pagination pages.

routes(site, opts)

site_discovered(site)

Transform a discovered site before rendering.

site_discovered(site, opts)

Types

plugin()

@type plugin() :: module() | {module(), keyword()}

route_body()

@type route_body() :: iodata()

route_headers()

@type route_headers() :: [{String.t(), String.t()}]

Callbacks

build_done(result)

(optional)

@callback build_done(result :: Astral.BuildResult.t()) :: :ok | {:error, term()}

Run after a successful static build.

build_done(result, opts)

(optional)

@callback build_done(result :: Astral.BuildResult.t(), opts :: keyword()) ::
  :ok | {:error, term()}

build_start(config)

(optional)

@callback build_start(config :: Astral.Config.t()) :: :ok | {:error, term()}

Run before a static build starts.

build_start(config, opts)

(optional)

@callback build_start(config :: Astral.Config.t(), opts :: keyword()) ::
  :ok | {:error, term()}

config(config)

(optional)

@callback config(config :: Astral.Config.t()) :: Astral.Config.t()

Transform the normalized site config before discovery/build/dev use.

config config, opts

(optional)

@callback config(config :: Astral.Config.t(), opts :: keyword()) :: Astral.Config.t()

enforce()

(optional)

@callback enforce() :: :pre | :post | nil

Return :pre, :post, or nil to control plugin ordering.

enforce(opts)

(optional)

@callback enforce(opts :: keyword()) :: :pre | :post | nil

name()

@callback name() :: String.t()

Plugin name for identification and error messages.

render_page(html, page, site)

(optional)

@callback render_page(
  html :: String.t(),
  page :: Astral.Page.t(),
  site :: Astral.Site.t()
) ::
  {:ok, String.t()} | nil

Transform rendered page HTML.

render_page(html, page, site, opts)

(optional)

@callback render_page(
  html :: String.t(),
  page :: Astral.Page.t(),
  site :: Astral.Site.t(),
  opts :: keyword()
) :: {:ok, String.t()} | nil

render_route(route, site)

(optional)

@callback render_route(route :: Astral.Route.t(), site :: Astral.Site.t()) ::
  {:ok, route_body()}
  | {:ok, route_body(), String.t()}
  | {:ok, route_body(), String.t(), route_headers()}
  | {:error, term()}
  | nil

Render a plugin-owned generated route.

render_route(route, site, opts)

(optional)

@callback render_route(
  route :: Astral.Route.t(),
  site :: Astral.Site.t(),
  opts :: keyword()
) ::
  {:ok, route_body()}
  | {:ok, route_body(), String.t()}
  | {:ok, route_body(), String.t(), route_headers()}
  | {:error, term()}
  | nil

routes(site)

(optional)

@callback routes(site :: Astral.Site.t()) :: [Astral.Route.t()]

Return generated routes such as feeds, sitemaps, tag pages, or pagination pages.

routes(site, opts)

(optional)

@callback routes(site :: Astral.Site.t(), opts :: keyword()) :: [Astral.Route.t()]

site_discovered(site)

(optional)

@callback site_discovered(site :: Astral.Site.t()) :: Astral.Site.t()

Transform a discovered site before rendering.

site_discovered(site, opts)

(optional)

@callback site_discovered(site :: Astral.Site.t(), opts :: keyword()) :: Astral.Site.t()