Architecture

A theme defines how a Zid storefront looks, works, and stays organized.
Themes are built with Jinja templates plus JSON schema files for editable settings, all arranged in a consistent folder structure.

Directory Structure

All Zid themes must follow this structure:

├── locale/ar/LC_MESSAGES/messages.po
├── assets/
├── sections/
│   ├── slider.jinja
│   └── slider.schema.json
├── components/
│   └── pagination.jinja
└── templates/
│   ├── home.jinja
│   ├── cart.jinja
│   └── product.jinja
├── layout.jinja
├── layout.schema.json
├── footer.jinja
├── footer.schema.json
├── header.jinja
└── header.schema.json

Theme Hierarchy

The storefront is assembled in layers, starting from the layout and breaking down into reusable parts.

Layout
Defines base HTML wrappers which inject shared <head> tags, header/footer, and global scripts. Templates extend these layouts. Needs to include vitrin tags.

Section
Contains the main page blocks, each split into a .jinja markup file and a companion .json schema. The schema surfaces settings in the Theme Editor, and the section can render multiple components to build complex layouts.

Component
Reusable modules of content that are consumed by sections. Every component has its own .jinja markup and .json schema so that it can be customized by merchants.

Assets

Stored in assets/

Includes CSS, JS, images, and fonts.

All assets are fingerprinted and served via Zid CDN.

Reference any file with the asset_url filter to output its cache‑busted CDN URL:

Templates

Map storefront routes to actual pages.

Example routes:

/ → home.jinja

/p/{product} → product.jinja

/cart → cart.jinja

Each template references a layout and one or more sections.

👉 Read more: Templates Overview

Gettext Localization

Stored in locale/{locale}/LC_MESSAGES/messages.po

Plain-text file storing translations: msgid → msgstr.

Natural language keys.

Compiled into .mo files (machine-readable) for performance.

localization msgid

make sure that the msgid is unique in the .po translation file, otherwise file won't be compiled properly

👉 Read more: Localization

Directory Structure#

Theme Hierarchy#

Assets#

Templates#

Gettext Localization#

Directory Structure

Theme Hierarchy

Assets

Templates

Gettext Localization