Themes (beta)

Theme authoring (beta)

Beta: theme zip layout, placeholders, settings schemas, JS policy, and the downloadable reference theme.

Beta. Sites theme packages are in beta. Markup helpers and validation rules may expand before general availability.

Build installable looks and layouts for Sites (*.styrar.site) using a structured folder layout. Markup uses JSON + HTML placeholders (not Liquid). Install is always copy-on-install into a draft version.

Download the reference theme (beta): styrar-reference-theme.zip (multi-page starter with custom blocks, snippets, and local FAQ JS). Package shape may change before general availability.

API reference: Theme packages. Sites product overview: Sites.

Plan requirement: API access requires Team or Agency. See pricing.

Package zip layout

Plain text

theme.json                 # id, name, pages, pageMeta, chrome blocks, metadata
config/theme.json          # token defaults
templates/
  index.json               # { "path": "/", "title": "Home", "sections": [...] }
  about.json
sections/                  # optional custom section kinds
  my_section/
    definition.json
    template.html
blocks/
  theme.feature_card/
    definition.json        # settings schema
    template.html          # placeholders
    template.css
    template.js            # optional local interactivity
snippets/
  eyebrow.html
assets/                    # optional images

You can also POST a single JSON package body to POST /v1/sites/theme-packages/workspace.

Markup (placeholders)

HTML

<article class="bio-block">
  <h3>{{ settings.title }}</h3>
  <div>{{{ settings.body }}}</div>
  <a href="{{ settings.cta_url }}">{{ settings.cta_label }}</a>
  {{#blocks}}{{/blocks}}
  {{ include "eyebrow" }}
</article>

Syntax	Behavior
`{{ settings.id }}`	Escaped text from live `config`
`{{{ settings.id }}}`	Sanitized rich HTML (`richtext`)
`{{#blocks}}{{/blocks}}`	Nested child blocks
`{{ include "name" }}`	Expand `snippets/name.html`

Optional HTML `<template>`

Use a native <template> when local template.js needs template.content.cloneNode(true) for lists or interactive rows. SSR still fills placeholders for the first paint. The reference theme includes an example on the FAQ block.

Settings schema

Each block or section definition.json includes a settings array:

Types: text, textarea, richtext, url, image, color, select, checkbox, number, header
Defaults seed config on install
The Sites inspector builds fields from settings (not raw HTML)

Put customer-editable copy in settings. Hardcoded strings in HTML are chrome only.

Multi-page

Declare pages and matching pageMeta entries (or use templates/*.json).
Chrome blocks[].pagePath must be listed in pages.
Max 20 pages per package.

JavaScript policy

Content	Runtime
Local / inline JS (`template.js`)	Runs on the published page
External script URLs / CDN imports	Sandboxed iframe

Upload and install

Sites editor → Theme → Upload theme zip, or POST /v1/sites/theme-packages/workspace.
Apply tokens only, or Install layout / install-theme-package with mode: "full".
Export a draft anytime with POST /v1/sites/:id/versions/:versionId/export-theme-package.

CLI and GitHub

Local DX with the Styrar CLI (styrar theme validate|pack|push|pull|status). Push uploads the workspace package and can install into a site draft; add --publish to go live.

From the Theme tab, Theme source (GitHub) links a repo. Pushes to the linked branch sync into the draft. Turn on Auto-publish this branch only when you want pushes to publish live. Details: developer guide for Sites theme authoring (CLI + GitHub App env vars).

Theme packages - catalog, install modes, CSS variables
Sites API - full route table
Sites overview - product guide