API Reference cherry v#0.5.0

A static site generator for hackers — a modern take on Octopress.

Entrypoint for the standalone cherry binary (ADR 0007): argv → Cherry.CLI.run/1 → exit code. The binary is a thin dispatcher over the same seam every mix task uses, so the two can never drift.

The build token: the single value every pipeline stage takes and returns (Tableau's proven shape). Stages are pure token -> token transformations; only load and emit touch the filesystem.

Build-time selection options.

The single seam behind every Cherry frontend (ADR 0006).

Behaviour every Cherry command implements.

Parsed invocation state handed to every command.

A structured command failure.

Renders help text for the base CLI and for individual verbs.

Maps CLI verbs to their Cherry.CLI.Command modules.

The CV: the employer-shaped projection of the portfolio (DESIGN.md §4).

/cv.json in the JSON Resume standard schema — ATS tools and agents consume it; the same projection as the web CV, machine-shaped.

CV publication settings from portfolio.yaml (DESIGN.md §4).

A derived skill: a tag aggregated across CV positions and projects, weighted by duration and recency. The differentiator — each skill links to its story page, where the claim becomes evidence.

The verifier (DESIGN.md §6): runs every rule against a finished build token and returns structured diagnostics.

One structured finding from cherry.check (DESIGN.md §6): the file it came from, the rule that fired, what is wrong, and how bad it is.

The built-in content collections and their lookup.

Behaviour for a content collection: directory + schema + routing (ADR 0003).

Freeform pages: content/pages/**.

Shared shape of the portfolio collections (DESIGN.md §4): typed entries under content/portfolio/, slug from the filename, no page of their own — the timeline, story, and CV views render them.

Education: content/portfolio/education/*.md.

Open source: content/portfolio/oss/*.md.

Employment positions: content/portfolio/positions/*.md.

Projects: content/portfolio/projects/*.md.

Talks: content/portfolio/talks/*.md.

Dated blog posts: content/posts/YYYY-MM-DD-slug.md.

Validates frontmatter against a collection schema and introspects schemas for humans and agents.

Shared NimbleOptions custom validators for collection schemas.

Builds the site into _site/.

Verifies the site: builds it in memory and runs every check rule.

Reads and writes cherry.exs, so a site can be configured without an editor.

Generates a deploy pipeline for this site.

Creates a new draft post with valid frontmatter.

Creates a new portfolio project entry with valid frontmatter.

Creates a new portfolio talk entry with valid frontmatter.

Scaffolds a site-local theme from an official one.

Scaffolds a new Cherry site: content directories, config, a first post, AGENTS.md documenting the agent workflow, and a .claude publish skill.

Shared engine for the portfolio gen.* commands: title → slug → a frontmatter scaffold in the collection's directory, refusing to clobber existing entries.

Publishes a draft: flips draft: true off and re-dates the post to today.

Prints a collection's frontmatter schema.

Builds the site and serves it locally with live reload.

Reports drift between the site's theme overlays and the installed theme.

Copies a theme template into the site's per-theme overlay with a recorded provenance header (theme, version, content hash).

Shows the active theme: contract, template inventory with where each template resolves from, token manifest, and the state of any site overlays (fresh / stale / untracked).

Shows the active theme's styling API: every token the theme declares, its default, what it does, and any site override from tokens: in cherry.exs — the merged view a restyle works against.

Prints the full resolution chain for one template: site overlay → theme → framework. Three levels, never more; the arrow marks the file that will render.

Upgrades the standalone cherry binary in place (ADR 0007).

Prints the Cherry version.

A static file copied verbatim into the output tree.

Content components: a small, framework-level set of directives that work in any theme, so content never accumulates theme-specific markup (DESIGN.md — that is precisely why Jekyll theme swaps break).

A content file travelling through the pipeline: parsed, not yet emitted.

Splits and parses YAML frontmatter fenced by --- lines.

A page travelling through the build pipeline.

Turns titles into URL slugs the same way everywhere: lowercase ASCII-ish, hyphen-separated, nothing else.

The machine-readable half of the published site (DESIGN.md §6): markdown mirrors — every content route carries index.md alongside index.html — and /llms.txt, the llmstxt.org index agents start from.

One markdown mirror: the index.md twin a route directory carries alongside its index.html (DESIGN.md §6), so agents read content without scraping HTML.

Runs a build token through an ordered list of stages.

Behaviour for a pipeline stage: token in, token out.

Writes the token to disk: pages as files, assets copied verbatim.

Emits the machine-readable surface: feed.xml (Atom), feed.json (JSON Feed), sitemap.xml, and robots.txt — default-on, zero config (DESIGN.md §7).

Renders documents through the active theme into emit-ready pages, and generates the synthetic pages the contract owes every site: the post index (/blog/), one page per tag (/blog/tags/:tag/), 404.html, and — when the site carries a portfolio — the timeline (/portfolio/) and one story page per portfolio tag (/story/:tag/).

Reads content and static files from the site root into the token.

Appends the machine surface (DESIGN.md §6): markdown mirrors and llms.txt.

Post-build enhancements (DESIGN.md pipeline: "post — search index, fingerprints — optional").

Emits the runtime for search: "cherry", Cherry's built-in search engine: search/index.json and the search/search.js island.

Renders markdown bodies to HTML with MDEx (GFM extensions on).

Validates every document against its collection schema, assigns routes, and applies draft/future selection.

The developer story as typed data: the profile plus every portfolio entry, materialised from a finished build token.

The cv: curation block on a portfolio entry (DESIGN.md §4): whether the entry appears on the CV, how prominently, and with which punchy bullets — while the markdown body stays the long-form story.

A qualification: degree, certification, or formal course.

A labelled URL: profile links and project links.

An open-source involvement: repository plus named role.

An employment position on the timeline; open ended means current.

The person behind the portfolio: portfolio.yaml at the site root.

A project entry: something built, with links and a status.

A talk given at an event, with the recording and slides.

The chronological view of the developer story: dated entries mixed across collections, newest first, grouped by year.

One dated timeline entry with its kind made explicit.

The Atom feed (feed.xml).

Builds the SEO <head> block every page carries: canonical link, feed discovery, icon links (detected from static/ — Cherry.Site.Icons), meta description, Open Graph / Twitter cards, and JSON-LD BlogPosting for posts.

The JSON Feed (feed.json), per the jsonfeed.org 1.1 spec — the Atom feed's twin for JSON-native readers and agents (DESIGN.md §6).

JSON-LD Person derived from the portfolio (DESIGN.md §4): the portfolio is the structured data. Emitted on the timeline page.

Builds the search index emitted for search: "cherry" — the built-in engine that needs no Node, no npm, and no network (DESIGN.md §7).

The dev server: Bandit serving the built _site/, a file watcher that rebuilds on change, and live reload over server-sent events.

Optional named local URLs for serve, via a running cherrypicker daemon: cherry serve --name mysite registers the bound port and the site answers at http://mysite.localhost[:proxy port].

Serves the built output directory in dev, with two additions production never sees: a live-reload client injected into every HTML page and the /__cherry/reload SSE endpoint that drives it.

Live-reload fanout: SSE connections register here; the watcher broadcasts after every rebuild. A duplicate-key Registry is the whole pubsub.

Watches the site's inputs and rebuilds on change, debounced.

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

The site's icon set, detected by convention from static/ — no config key to fall out of sync with the files on disk.

Renders the generated half of the agent skill (skills/cherry/): a complete per-verb command reference sourced from the CLI registry and each command's single-sourced doc text, so the skill can never drift from the real verb surface.

Byte-deterministic JSON for emitted output (ADR 0005): object keys are written in sorted order.

A theme: a directory carrying a theme.exs manifest (ADR 0004).

Loads a theme's components.exs: an optional file at the theme root defining function-component modules (use Phoenix.Component) that every HEEx template in that theme can call as <.name …>.

Managed drift (DESIGN.md, "the piece nobody ships"): because theme.eject recorded provenance, a theme upgrade is a mechanical three-way comparison — the base you ejected from, the installed upstream, and your copy.

One overlay's drift status against the installed theme.

Functions available to theme templates.

One entry in the site's header navigation.

The lineage header written by theme.eject and read back to detect staleness (ADR 0004).

Everything the layout wrap needs beyond the inner template's own assigns: the site, the active theme, the page title, the framework-owned SEO head block, and the navigation.

Renders theme templates: runtime-evaluated, so themes work identically in project mode and binary mode (ADR 0002/0004). The file extension picks the language — .html.eex is classic EEx, .html.heex is HEEx with HTML-aware escaping, function components, and :for/:if.

The three-level template lookup: site overlay → theme → framework.

One entry in a theme's template inventory: the template's name, the assigns it receives, and what it is for. Fixed names and fixed assigns are the contract that makes theme swapping real.

Self-update for the standalone binary (ADR 0007), rustup/deno style: resolve a release from the GitHub Releases API, download this platform's asset, verify it against the release's SHA256SUMS, and swap the running executable in place.

The one HTTP client in Cherry: plain :httpc (no runtime deps), TLS verification against the OS trust store, redirects followed — GitHub serves release assets through a redirect to its CDN.

The answer to "what would cherry upgrade do right now?": the running version, the resolved target release, the platform asset that would be installed, and whether an upgrade is actually due.

A published Cherry release as the GitHub Releases API describes it: the tag, whether it is a prerelease, and a name → download-URL map of its assets (binaries plus SHA256SUMS).

Builds the site into _site/.

Verifies the site: builds it in memory and runs every check rule.

Reads and writes cherry.exs, so a site can be configured without an editor.

Generates a deploy pipeline for this site.

Creates a new draft post with valid frontmatter.

Creates a new portfolio project entry with valid frontmatter.

Creates a new portfolio talk entry with valid frontmatter.

Scaffolds a site-local theme from an official one.

Publishes a draft: flips draft: true off and re-dates the post to today.

Prints a collection's frontmatter schema.

Builds the site and serves it locally with live reload.

Reports drift between the site's theme overlays and the installed theme.

Copies a theme template into the site's per-theme overlay with a recorded provenance header (theme, version, content hash).

Shows the active theme: contract, template inventory with where each template resolves from, token manifest, and the state of any site overlays (fresh / stale / untracked).

Shows the active theme's styling API: every token the theme declares, its default, what it does, and any site override from tokens: in cherry.exs — the merged view a restyle works against.

Prints the full resolution chain for one template: site overlay → theme → framework. Three levels, never more; the arrow marks the file that will render.

Upgrades the standalone cherry binary in place (ADR 0007).

Prints the Cherry version.