Theme Authoring

Getting Started

A theme controls how your site looks. Tovu ships several, and you can author your own without a build step.

What is a theme

A folder with a theme.json manifest, a token set, a stylesheet, and either templates or plain HTML pages. Nothing is compiled — every byte is editable.

Theme tiers

Five tiers: declarative, templated, handlebars, static, and code. Static themes are plain HTML/CSS/JS and are the easiest place to start.

Authoring

Everything a theme declares about itself lives in one manifest file.

theme.json

Declares id, name, version, tier, fonts, pages, slots, color modes, and any post templates the theme offers.

Design tokens

tokens.json becomes CSS custom properties on :root. An optional tokens.light.json supplies light-mode overrides.

Slots and partials

A data-tovu-slot marker pulls in a shared partial such as the nav or footer, so every page stays in sync.

Color modes

Declare modes and a defaultMode, and the engine stamps data-theme onto the page. Your own toggle script flips it from there.

Menus

Menus are content, not theme code. A theme marks where a menu goes; the menu itself is edited in the admin.

Menu embeds

A data-embed-type="menu" marker names a menu by its slug. If no such menu exists, the marker keeps whatever the theme authored as a fallback.

Nested menus

Adding data-embed-variant="tree" renders the menu as a nested list with is-current and is-active hooks — which is what this sidebar is using right now.