Architecture

Yoshi is a pipeline that turns structured data into a static site. The design has a few load-bearing ideas worth understanding before you read the code.

The egg

Internally, a site-in-progress is an egg. You seed it (a few facts, or a URL), it fills with the business's real assets, and it hatches into a deployed site. The metaphor is also the brand: the dot in yoshi·site is an egg — YOSHI › 🥚 › SITE (input → egg → output).

Two halves: the deterministic FASTCAR + the generative RACECAR

  ① CORE   ② IMAGES   ③ CARDS   ④ VISION   ⓪ INTAKE-SPINE
   ───────────── the deterministic FASTCAR ─────────────▶   (same blueprint → same site)
                          +
   copy · translate · enrich · uniqueness  ── the generative RACECAR ──▶   (per-business voice)

The FASTCAR is deterministic: given a blueprint, it emits the same site every time. The RACECAR is the generative half — writing per-business copy, translating it, individuating the design — that grows a richer blueprint before the FASTCAR renders it.

The skeleton is embedded, not a directory

The Next.js project Yoshi emits is built from an embedded skeleton — include_dir! compiles the skeleton files into the binary. There's no external template directory to ship or drift. A MANIFEST.toml maps each skeleton source file to its output path; .j2 files render through MiniJinja with the blueprint config, everything else is copied verbatim.

Gotcha: because the skeleton is embedded at compile time, editing a skeleton file requires a cargo build (touch lib.rs to force the include_dir! re-embed). And a skeleton file only ships if it's registered in its MANIFEST.toml — verify the generated artifact, not the build log.

Static-edge output

Sites build with output: 'export' — pure static HTML/CSS/JS in out/, deployed to a CDN. No per-request server, no SSR, no "worker exceeded resource limits." Headers live in public/_headers; images are pre-sized and served unoptimised. This is what makes 1,800-page sites cheap and unbreakable.

The base/type split (the raw skeleton)

The skeleton is split into a shared core and swappable type layers, so Yoshi can generate more than one kind of site from one substrate. This is the most important recent change — it has its own page: see Site Types.