Theme architecture
A Zone theme is a set of files placed in fixed folders. The folder, template and page type lists on this page are generated from the engine's registries.
Folders
Theme files may only live in the folders below. Template files use the .zone extension; JSON files keep theirs. Paths that climb to a parent directory or are absolute are rejected.
| Folder | Description |
|---|---|
assets/ | Assets: stylesheet and script files. |
blocks/ | Theme blocks: reusable blocks rendered inside a section with the content_for tag. |
config/ | The theme settings schema (settings_schema.json). |
layout/ | Layout. The HTML shell around every page; the body is placed with content_for_layout. |
locales/ | Translation files. |
sections/ | Sections: pieces with a schema and settings that can be added and reordered in the editor. Section groups live here too. |
snippets/ | Snippets: small reusable templates called with the render tag. |
templates/ | One template per page type. Either JSON (a list of sections) or .zone (code). |
Limits: 512 KB per file, 2000 files per theme.
Layout
The default layout is layout/theme.zone. A template can pick another layout with the layout tag; the value none renders the page without a layout. If the chosen layout file is missing the page fails instead of printing a bare body.
<!doctype html>
<html lang="tr">
<head>
<meta charset="utf-8">
<title>{{ page_title }}</title>
{{ 'tema.css' | asset_url | stylesheet_tag }}
</head>
<body style="--vurgu: {{ settings.vurgu_rengi }}">
<main>{{ content_for_layout }}</main>
<footer>{{ 'genel.telif' | t: magaza: shop.name }}</footer>
</body>
</html>
Templates
A template comes in two forms. A JSON template only orders sections and carries their settings; this is what the visual editor writes. A .zone template is code. If both exist under the same name, the JSON one is used.
In a JSON template, sections maps section ids to definitions and order gives the render order. Each section's type is a file name in the sections/ folder.
{
"sections": {
"karsilama-1": {
"type": "karsilama",
"settings": { "baslik": "İlk Zone temam" },
"blocks": {
"madde-1": { "type": "madde", "settings": { "metin": "Hızlı kargo" } },
"madde-2": { "type": "madde", "settings": { "metin": "Güvenli ödeme" } }
},
"block_order": ["madde-1", "madde-2"]
}
},
"order": ["karsilama-1"]
}
Template names known to the engine:
404articleblogcartcollectioncustomers/accountcustomers/addressescustomers/logincustomers/ordercustomers/recovercustomers/registercustomers/reset_passwordindexlist-collectionspageproductsearch
Visitors never request the following templates directly; if the theme ships the file the engine switches to it on the matching page, otherwise it renders with the generic template:
articlebloglist-collections
These template names are not supported:
agents.mdgift_cardllms.txtpasswordrobots.txt
Page types and URL paths
Visitor paths resolve to page types as follows. Turkish and English paths are equivalent. Any other single-segment path is treated as a content page; if no page exists the theme's 404 template is rendered.
| Path | Page type |
|---|---|
/ | index |
/products/{handle} | product |
/collections | collection |
/collections/{handle} | collection |
/koleksiyon/{handle} | collection |
/cart | cart |
/sepet | cart |
/search | search |
/arama | search |
/search/suggest | search |
/arama/oneri | search |
/account | customers/account |
/hesabim | customers/account |
/account/login | customers/login |
/hesabim/giris | customers/login |
/account/register | customers/register |
/hesabim/kayit | customers/register |
/account/recover | customers/recover |
/hesabim/sifremi-unuttum | customers/recover |
/account/reset | customers/reset_password |
/hesabim/sifre-sifirla | customers/reset_password |
/account/addresses | customers/addresses |
/hesabim/adreslerim | customers/addresses |
/account/orders/{id} | customers/order |
/hesabim/siparis/{id} | customers/order |
/{handle} | page |
These pages require a customer session; without one the visitor is redirected to /account/login?return_to=...:
customers/accountcustomers/addressescustomers/order
Section groups
Areas repeated on every page, such as the header and footer, are section groups. A group file lives at sections/NAME.json and has the same shape as a JSON template (sections and order), plus a type (header, footer, aside or custom.NAME) and a name. It is rendered in the layout with the sections tag. A group holds at most 25 sections and a section at most 50 blocks.
{% sections 'header-group' %}