# cherry v0.5.0 - Table of Contents

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

## Pages

- [README](readme.md)
- [Changelog](changelog.md)

## Modules

- [Cherry.Check.Diagnostic](Cherry.Check.Diagnostic.md): 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.
- [Cherry.Search.Index](Cherry.Search.Index.md): Builds the search index emitted for `search: "cherry"` — the built-in
engine that needs no Node, no npm, and no network (DESIGN.md §7).
- [Cherry.Site.Icons](Cherry.Site.Icons.md): The site's icon set, detected by convention from `static/` — no config
key to fall out of sync with the files on disk.

- Core API
  - [Cherry](Cherry.md): A static site generator for hackers — a modern take on Octopress.
  - [Cherry.Build](Cherry.Build.md): 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.
  - [Cherry.Build.Options](Cherry.Build.Options.md): Build-time selection options.
  - [Cherry.Check](Cherry.Check.md): The verifier (DESIGN.md §6): runs every rule against a finished build
token and returns structured diagnostics.
  - [Cherry.Site](Cherry.Site.md): A Cherry site: the validated configuration plus its filesystem roots.

- Content
  - [Cherry.Collections](Cherry.Collections.md): The built-in content collections and their lookup.
  - [Cherry.Collections.Collection](Cherry.Collections.Collection.md): Behaviour for a content collection: directory + schema + routing (ADR 0003).
  - [Cherry.Collections.Pages](Cherry.Collections.Pages.md): Freeform pages: `content/pages/**`.
  - [Cherry.Collections.Portfolio](Cherry.Collections.Portfolio.md): 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.
  - [Cherry.Collections.Portfolio.Education](Cherry.Collections.Portfolio.Education.md): Education: `content/portfolio/education/*.md`.
  - [Cherry.Collections.Portfolio.Oss](Cherry.Collections.Portfolio.Oss.md): Open source: `content/portfolio/oss/*.md`.
  - [Cherry.Collections.Portfolio.Positions](Cherry.Collections.Portfolio.Positions.md): Employment positions: `content/portfolio/positions/*.md`.
  - [Cherry.Collections.Portfolio.Projects](Cherry.Collections.Portfolio.Projects.md): Projects: `content/portfolio/projects/*.md`.
  - [Cherry.Collections.Portfolio.Talks](Cherry.Collections.Portfolio.Talks.md): Talks: `content/portfolio/talks/*.md`.
  - [Cherry.Collections.Posts](Cherry.Collections.Posts.md): Dated blog posts: `content/posts/YYYY-MM-DD-slug.md`.
  - [Cherry.Collections.Schema](Cherry.Collections.Schema.md): Validates frontmatter against a collection schema and introspects schemas
for humans and agents.
  - [Cherry.Collections.Types](Cherry.Collections.Types.md): Shared NimbleOptions custom validators for collection schemas.
  - [Cherry.Content.Asset](Cherry.Content.Asset.md): A static file copied verbatim into the output tree.
  - [Cherry.Content.Components](Cherry.Content.Components.md): 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).
  - [Cherry.Content.Document](Cherry.Content.Document.md): A content file travelling through the pipeline: parsed, not yet emitted.
  - [Cherry.Content.Frontmatter](Cherry.Content.Frontmatter.md): Splits and parses YAML frontmatter fenced by `---` lines.
  - [Cherry.Content.Page](Cherry.Content.Page.md): A page travelling through the build pipeline.
  - [Cherry.Content.Slug](Cherry.Content.Slug.md): Turns titles into URL slugs the same way everywhere: lowercase ASCII-ish,
hyphen-separated, nothing else.

- Portfolio &amp; CV
  - [Cherry.CV](Cherry.CV.md): The CV: the employer-shaped projection of the portfolio (DESIGN.md §4).
  - [Cherry.CV.JsonResume](Cherry.CV.JsonResume.md): `/cv.json` in the JSON Resume standard schema — ATS tools and agents
consume it; the same projection as the web CV, machine-shaped.

  - [Cherry.CV.Settings](Cherry.CV.Settings.md): CV publication settings from `portfolio.yaml` (DESIGN.md §4).
  - [Cherry.CV.Skill](Cherry.CV.Skill.md): 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.

  - [Cherry.Portfolio](Cherry.Portfolio.md): The developer story as typed data: the profile plus every portfolio
entry, materialised from a finished build token.
  - [Cherry.Portfolio.Curation](Cherry.Portfolio.Curation.md): 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.

  - [Cherry.Portfolio.Education](Cherry.Portfolio.Education.md): A qualification: degree, certification, or formal course.
  - [Cherry.Portfolio.Link](Cherry.Portfolio.Link.md): A labelled URL: profile links and project links.
  - [Cherry.Portfolio.OpenSource](Cherry.Portfolio.OpenSource.md): An open-source involvement: repository plus named role.
  - [Cherry.Portfolio.Position](Cherry.Portfolio.Position.md): An employment position on the timeline; open `ended` means current.
  - [Cherry.Portfolio.Profile](Cherry.Portfolio.Profile.md): The person behind the portfolio: `portfolio.yaml` at the site root.
  - [Cherry.Portfolio.Project](Cherry.Portfolio.Project.md): A project entry: something built, with links and a status.
  - [Cherry.Portfolio.Talk](Cherry.Portfolio.Talk.md): A talk given at an event, with the recording and slides.
  - [Cherry.Portfolio.Timeline](Cherry.Portfolio.Timeline.md): The chronological view of the developer story: dated entries mixed
across collections, newest first, grouped by year.
  - [Cherry.Portfolio.Timeline.Item](Cherry.Portfolio.Timeline.Item.md): One dated timeline entry with its kind made explicit.

- Themes
  - [Cherry.Theme](Cherry.Theme.md): A theme: a directory carrying a `theme.exs` manifest (ADR 0004).
  - [Cherry.Theme.ComponentLoader](Cherry.Theme.ComponentLoader.md): 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 …>`.
  - [Cherry.Theme.Drift](Cherry.Theme.Drift.md): 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.
  - [Cherry.Theme.Drift.Entry](Cherry.Theme.Drift.Entry.md): One overlay's drift status against the installed theme.
  - [Cherry.Theme.Helpers](Cherry.Theme.Helpers.md): Functions available to theme templates.
  - [Cherry.Theme.NavItem](Cherry.Theme.NavItem.md): One entry in the site's header navigation.
  - [Cherry.Theme.Provenance](Cherry.Theme.Provenance.md): The lineage header written by `theme.eject` and read back to detect
staleness (ADR 0004).
  - [Cherry.Theme.RenderContext](Cherry.Theme.RenderContext.md): 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.
  - [Cherry.Theme.Renderer](Cherry.Theme.Renderer.md): 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`.
  - [Cherry.Theme.Resolver](Cherry.Theme.Resolver.md): The three-level template lookup: site overlay → theme → framework.
  - [Cherry.Theme.TemplateSpec](Cherry.Theme.TemplateSpec.md): 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.

- SEO &amp; Machine Surface
  - [Cherry.Machine](Cherry.Machine.md): 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.
  - [Cherry.Machine.Mirror](Cherry.Machine.Mirror.md): 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.
  - [Cherry.SEO.Feed](Cherry.SEO.Feed.md): The Atom feed (`feed.xml`).
  - [Cherry.SEO.Head](Cherry.SEO.Head.md): 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.
  - [Cherry.SEO.JsonFeed](Cherry.SEO.JsonFeed.md): The JSON Feed (`feed.json`), per the [jsonfeed.org](https://jsonfeed.org)
1.1 spec — the Atom feed's twin for JSON-native readers and agents
(DESIGN.md §6).
  - [Cherry.SEO.Person](Cherry.SEO.Person.md): JSON-LD `Person` derived from the portfolio (DESIGN.md §4): the
portfolio *is* the structured data. Emitted on the timeline page.

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

- Pipeline
  - [Cherry.Pipeline](Cherry.Pipeline.md): Runs a build token through an ordered list of stages.
  - [Cherry.Pipeline.Stage](Cherry.Pipeline.Stage.md): Behaviour for a pipeline stage: token in, token out.
  - [Cherry.Pipeline.Stages.Emit](Cherry.Pipeline.Stages.Emit.md): Writes the token to disk: pages as files, assets copied verbatim.
  - [Cherry.Pipeline.Stages.Feeds](Cherry.Pipeline.Stages.Feeds.md): Emits the machine-readable surface: `feed.xml` (Atom), `feed.json`
(JSON Feed), `sitemap.xml`, and `robots.txt` — default-on, zero
config (DESIGN.md §7).
  - [Cherry.Pipeline.Stages.Layout](Cherry.Pipeline.Stages.Layout.md): 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/`).
  - [Cherry.Pipeline.Stages.Load](Cherry.Pipeline.Stages.Load.md): Reads content and static files from the site root into the token.
  - [Cherry.Pipeline.Stages.Machine](Cherry.Pipeline.Stages.Machine.md): Appends the machine surface (DESIGN.md §6): markdown mirrors and
`llms.txt`.
  - [Cherry.Pipeline.Stages.Post](Cherry.Pipeline.Stages.Post.md): Post-build enhancements (DESIGN.md pipeline: "post — search index,
fingerprints — optional").
  - [Cherry.Pipeline.Stages.Search](Cherry.Pipeline.Stages.Search.md): Emits the runtime for `search: "cherry"`, Cherry's built-in search
engine: `search/index.json` and the `search/search.js` island.
  - [Cherry.Pipeline.Stages.Transform](Cherry.Pipeline.Stages.Transform.md): Renders markdown bodies to HTML with MDEx (GFM extensions on).
  - [Cherry.Pipeline.Stages.Validate](Cherry.Pipeline.Stages.Validate.md): Validates every document against its collection schema, assigns routes,
and applies draft/future selection.

- CLI &amp; Commands
  - [Cherry.CLI](Cherry.CLI.md): The single seam behind every Cherry frontend (ADR 0006).
  - [Cherry.CLI.Command](Cherry.CLI.Command.md): Behaviour every Cherry command implements.
  - [Cherry.CLI.Context](Cherry.CLI.Context.md): Parsed invocation state handed to every command.

  - [Cherry.CLI.Error](Cherry.CLI.Error.md): A structured command failure.
  - [Cherry.CLI.Help](Cherry.CLI.Help.md): Renders help text for the base CLI and for individual verbs.
  - [Cherry.CLI.Registry](Cherry.CLI.Registry.md): Maps CLI verbs to their `Cherry.CLI.Command` modules.
  - [Cherry.Commands.Build](Cherry.Commands.Build.md): Builds the site into `_site/`.
  - [Cherry.Commands.Check](Cherry.Commands.Check.md): Verifies the site: builds it in memory and runs every check rule.
  - [Cherry.Commands.Config](Cherry.Commands.Config.md): Reads and writes `cherry.exs`, so a site can be configured without an
editor.
  - [Cherry.Commands.GenAction](Cherry.Commands.GenAction.md): Generates a deploy pipeline for this site.
  - [Cherry.Commands.GenPost](Cherry.Commands.GenPost.md): Creates a new draft post with valid frontmatter.
  - [Cherry.Commands.GenProject](Cherry.Commands.GenProject.md): Creates a new portfolio project entry with valid frontmatter.
  - [Cherry.Commands.GenTalk](Cherry.Commands.GenTalk.md): Creates a new portfolio talk entry with valid frontmatter.
  - [Cherry.Commands.GenTheme](Cherry.Commands.GenTheme.md): Scaffolds a site-local theme from an official one.
  - [Cherry.Commands.New](Cherry.Commands.New.md): Scaffolds a new Cherry site: content directories, config, a first
post, `AGENTS.md` documenting the agent workflow, and a `.claude`
publish skill.
  - [Cherry.Commands.PortfolioScaffold](Cherry.Commands.PortfolioScaffold.md): Shared engine for the portfolio `gen.*` commands: title → slug →
a frontmatter scaffold in the collection's directory, refusing to
clobber existing entries.

  - [Cherry.Commands.Publish](Cherry.Commands.Publish.md): Publishes a draft: flips `draft: true` off and re-dates the post to today.
  - [Cherry.Commands.Schema](Cherry.Commands.Schema.md): Prints a collection's frontmatter schema.
  - [Cherry.Commands.Serve](Cherry.Commands.Serve.md): Builds the site and serves it locally with live reload.
  - [Cherry.Commands.ThemeDiff](Cherry.Commands.ThemeDiff.md): Reports drift between the site's theme overlays and the installed theme.
  - [Cherry.Commands.ThemeEject](Cherry.Commands.ThemeEject.md): Copies a theme template into the site's per-theme overlay with a
recorded provenance header (theme, version, content hash).
  - [Cherry.Commands.ThemeList](Cherry.Commands.ThemeList.md): 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).
  - [Cherry.Commands.ThemeTokens](Cherry.Commands.ThemeTokens.md): 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.
  - [Cherry.Commands.ThemeWhich](Cherry.Commands.ThemeWhich.md): Prints the full resolution chain for one template: site overlay →
theme → framework. Three levels, never more; the arrow marks the file
that will render.
  - [Cherry.Commands.Upgrade](Cherry.Commands.Upgrade.md): Upgrades the standalone `cherry` binary in place (ADR 0007).
  - [Cherry.Commands.Version](Cherry.Commands.Version.md): Prints the Cherry version.
  - [Cherry.Skill](Cherry.Skill.md): 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.

- Serve &amp; Upgrade
  - [Cherry.Binary](Cherry.Binary.md): 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.
  - [Cherry.Serve](Cherry.Serve.md): The dev server: Bandit serving the built `_site/`, a file watcher that
rebuilds on change, and live reload over server-sent events.
  - [Cherry.Serve.Names](Cherry.Serve.Names.md): Optional named local URLs for serve, via a running
[cherrypicker](https://github.com/holsee/cherrypicker) daemon:
`cherry serve --name mysite` registers the bound port and the site
answers at `http://mysite.localhost[:proxy port]`.
  - [Cherry.Serve.Plug](Cherry.Serve.Plug.md): 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.

  - [Cherry.Serve.Reloader](Cherry.Serve.Reloader.md): Live-reload fanout: SSE connections register here; the watcher broadcasts
after every rebuild. A duplicate-key Registry is the whole pubsub.

  - [Cherry.Serve.Watcher](Cherry.Serve.Watcher.md): Watches the site's inputs and rebuilds on change, debounced.
  - [Cherry.Upgrade](Cherry.Upgrade.md): 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.
  - [Cherry.Upgrade.HTTP](Cherry.Upgrade.HTTP.md): 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.
  - [Cherry.Upgrade.Plan](Cherry.Upgrade.Plan.md): 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.

  - [Cherry.Upgrade.Release](Cherry.Upgrade.Release.md): 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`).

## Mix Tasks

- [mix cherry.build](Mix.Tasks.Cherry.Build.md): Builds the site into `_site/`.
- [mix cherry.check](Mix.Tasks.Cherry.Check.md): Verifies the site: builds it in memory and runs every check rule.
- [mix cherry.config](Mix.Tasks.Cherry.Config.md): Reads and writes `cherry.exs`, so a site can be configured without an
editor.
- [mix cherry.gen.action](Mix.Tasks.Cherry.Gen.Action.md): Generates a deploy pipeline for this site.
- [mix cherry.gen.post](Mix.Tasks.Cherry.Gen.Post.md): Creates a new draft post with valid frontmatter.
- [mix cherry.gen.project](Mix.Tasks.Cherry.Gen.Project.md): Creates a new portfolio project entry with valid frontmatter.
- [mix cherry.gen.talk](Mix.Tasks.Cherry.Gen.Talk.md): Creates a new portfolio talk entry with valid frontmatter.
- [mix cherry.gen.theme](Mix.Tasks.Cherry.Gen.Theme.md): Scaffolds a site-local theme from an official one.
- [mix cherry.publish](Mix.Tasks.Cherry.Publish.md): Publishes a draft: flips `draft: true` off and re-dates the post to today.
- [mix cherry.schema](Mix.Tasks.Cherry.Schema.md): Prints a collection's frontmatter schema.
- [mix cherry.serve](Mix.Tasks.Cherry.Serve.md): Builds the site and serves it locally with live reload.
- [mix cherry.theme.diff](Mix.Tasks.Cherry.Theme.Diff.md): Reports drift between the site's theme overlays and the installed theme.
- [mix cherry.theme.eject](Mix.Tasks.Cherry.Theme.Eject.md): Copies a theme template into the site's per-theme overlay with a
recorded provenance header (theme, version, content hash).
- [mix cherry.theme.list](Mix.Tasks.Cherry.Theme.List.md): 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).
- [mix cherry.theme.tokens](Mix.Tasks.Cherry.Theme.Tokens.md): 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.
- [mix cherry.theme.which](Mix.Tasks.Cherry.Theme.Which.md): Prints the full resolution chain for one template: site overlay →
theme → framework. Three levels, never more; the arrow marks the file
that will render.
- [mix cherry.upgrade](Mix.Tasks.Cherry.Upgrade.md): Upgrades the standalone `cherry` binary in place (ADR 0007).
- [mix cherry.version](Mix.Tasks.Cherry.Version.md): Prints the Cherry version.

