Theme structure

A theme is a directory of layouts, templates, partials, config, and assets, identified by a theme.json manifest. The details below are generated from the platform's importer rules and the reference theme, so they match exactly what the platform accepts.

The manifest — theme.json

Every theme carries a theme.json in the theme root identifying it (slug, name, semver version, optional description and changelog) — see Stayblox CLI → manifest. The contract is the same whether you publish with the CLI or upload a .zip to your own site: the platform always reads the theme's identity from the manifest.

Files are stored by their path within the theme. Every package — CLI publish or private zip upload — carries the same theme.json manifest; the theme's slug, name, and version are always read from it. Beyond the manifest, what's required depends on the publishing path:

• Marketplace (CLI) — layouts/app.twig and pages.twig must exist. Config files (config/settings_schema.json, config/blocks.json, config/templates.json, config/menu.json) must be valid JSON when present; missing ones are warnings.
• Private zip upload — only a layouts/ directory is required; there is no review step.

Reference layout

The cove theme shipped in the platform is a complete, minimal example:

cove/
  assets/css/iziToast.min.css
  assets/css/iziToast_custom.css
  assets/css/theme.css
  assets/js/app.js
  assets/js/card.js
  assets/js/iziToast.min.js
  assets/preview.jpg
  assets/thumbnail.jpg
  blocks/blog_posts.twig
  blocks/email_signup.twig
  blocks/faq.twig
  blocks/featured_units.twig
  blocks/gallery.twig
  blocks/hero.twig
  blocks/highlights.twig
  blocks/location.twig
  blocks/rich_text.twig
  blocks/stats.twig
  blocks/testimonials.twig
  checkout.twig
  config/blocks.json
  config/menu.json
  config/settings_schema.json
  config/templates.json
  confirmation.twig
  lang/bg.admin.json
  lang/bg.json
  lang/en.admin.json
  lang/en.json
  layouts/app-style_lib.twig
  layouts/app.twig
  layouts/frontend.twig
  layouts/master.twig
  maintenance.twig
  pages.twig
  partials/blog_post_card.twig
  partials/booking_history_table.twig
  partials/footer.twig
  partials/header.twig
  partials/notify.twig
  partials/page_blocks.twig
  partials/seo.twig
  partials/sidenav.twig
  partials/unit_card.twig
  partials/verification_code.twig
  policy.twig
  policy_content.twig
  sections.json
  sections/hero.twig
  templates/contact.twig
  templates/default_blog.twig
  templates/default_blog_post.twig
  templates/default_page.twig
  templates/index.twig
  theme.json
  unit/details.twig
  unit/types.twig
  user/auth/login.twig
  user/auth/passwords/code_verify.twig
  user/auth/passwords/email.twig
  user/auth/passwords/reset.twig
  user/auth/register.twig
  user/booking/all.twig
  user/booking/details.twig
  user/booking/request.twig
  user/dashboard.twig
  user/deposit_history.twig
  user/password.twig
  user/payment/Checkout.twig
  user/payment/Flutterwave.twig
  user/payment/StripeJs.twig
  user/profile_setting.twig
  user/transactions.twig
  user/user_data.twig

Top-level directories

Directory	Purpose
assets/	CSS, JS, images, and fonts (assets/css/, assets/js/, …) plus the listing thumbnail/preview images — served via theme_asset() by their inner path, e.g. theme_asset('css/app.css').
blocks/	Theme files, stored by path.
config/	settings_schema.json (host settings), menu.json (navigation), templates.json (page templates).
lang/	Theme files, stored by path.
layouts/	Twig layouts that templates {% extends %}. Required — the importer rejects a theme without it.
partials/	Reusable Twig partials included by layouts and templates.
sections/	Theme files, stored by path.
templates/	Page templates, one per page type.
unit/	Theme files, stored by path.
user/	Theme files, stored by path.

A layouts/ directory is mandatory; importing a .zip without one fails.

How files are stored

Text files with these extensions are imported as editable theme files (editable later in the code editor):

Files whose top-level directory is one of are stored under an assets/ prefix, so reference them with theme_asset('css/app.css') etc.

Binary files with these extensions are copied to the theme's public asset folder rather than stored as source:

How files resolve at render time

When a host installs your theme, its files are copied into site-level, editable copies. At render time the active theme's files are looked up by path, falling back to the installed theme version for any file the host hasn't overridden — so a host can customise just a few files without forking the whole theme.

See Publishing for versioning and how updates flow to installed sites.