Cherry.Site (cherry v0.5.0)

A Cherry site: the validated configuration plus its filesystem roots.

Configuration lives in cherry.exs at the site root — a plain keyword list, evaluated at build time so it works identically in project mode and binary mode (ADR 0002). The schema below is the source of truth; it is introspectable because agents ask before they write.

All URL building goes through href/2 and abs_url/2 so every emitted URL respects base_path (the GitHub project-pages case) — no template or stage ever concatenates URL strings itself.

Summary

Types

nav_entry()

t()

Functions

abs_url(site, rel)

Absolute URL for an output-relative location.

href(site, rel)

Site-rooted path for an output-relative location: respects base_path.

load(root, opts \\ [])

Loads and validates cherry.exs from root.

schema()

The site config schema, for introspection and docs.

Types

nav_entry()

@type nav_entry() :: %{label: String.t(), href: String.t(), position: :start | :end}

t()

@type t() :: %Cherry.Site{
  author: String.t(),
  base_path: String.t(),
  custom_css: String.t() | nil,
  description: String.t() | nil,
  icons: Cherry.Site.Icons.t(),
  nav: [nav_entry()],
  output: Path.t(),
  root: Path.t(),
  search: String.t() | nil,
  social_image: String.t() | nil,
  theme: String.t(),
  title: String.t(),
  tokens: [{String.t(), String.t()}],
  url: String.t()
}

Functions

abs_url(site, rel)

@spec abs_url(t(), String.t()) :: String.t()

Absolute URL for an output-relative location.

href(site, rel)

@spec href(t(), String.t()) :: String.t()

Site-rooted path for an output-relative location: respects base_path.

href(site, "blog/")   #=> "/blog/" or "/repo/blog/"
href(site, "")        #=> "/" or "/repo/"

load(root, opts \\ [])

@spec load(
  Path.t(),
  keyword()
) :: {:ok, t()} | {:error, String.t()}

Loads and validates cherry.exs from root.

Options: :output overrides the output directory (default root/_site). Errors are strings that name the file and the offending field.

schema()

@spec schema() :: NimbleOptions.t()

The site config schema, for introspection and docs.