Themes
Theme structure
The folders, templates, sections, blocks, settings, translations and assets of a biticaret theme, and how it is uploaded, checked, previewed and published.
A theme is a folder of Liquid, JSON, CSS and JavaScript files. The theme renders the storefront, while customer account pages and checkout are owned by the platform. This page explains how a theme is structured and how it is uploaded to a store.
The examples come from the skeleton theme (biticaret theme init).
Folders
layout/ theme.liquid wraps every page; password.liquid wraps the password page
templates/ one template per page type (JSON or Liquid)
sections/ sections and section groups (header-group.json, footer-group.json)
blocks/ theme blocks
snippets/ partials rendered with {% render %}
assets/ CSS, JavaScript, images, fonts
config/ settings_schema.json and settings_data.json
locales/ translations and *.schema.json filesA theme consists solely of these eight folders. Subfolders are allowed only under templates/customers and templates/metaobject.
Upload and check a theme
You upload a theme as a ZIP archive, which arrives as an unpublished theme. Its name comes from the theme_info entry in config/settings_schema.json, or from the ZIP filename if missing. biticaret theme check runs the same checks locally:
- Limits: the ZIP can be at most 50 MB (200 MB unpacked), and a store can hold up to 20 themes. Files outside the eight theme folders, absolute paths,
..segments and symbolic links are rejected. A single top-level wrapper folder inside the ZIP is accepted. - Required files: a missing layout/theme.liquid or a missing
index,product,collection,cart,page,searchor404template is an error. Missinglist-collectionsorpasswordtemplates, config/settings_schema.json or the default locale file produces a warning. - JSON: every JSON file must parse cleanly.
- Liquid: syntax errors are reported with file and line. Unknown tags or unknown filters are errors. Malformed Liquid that can still render produces a warning.
- Other: an unparseable
visible_ifcondition or a Sass file (assets/*.scss.liquid) is an error.
Errors block the upload; warnings do not. --strict treats warnings as errors.
You can preview an uploaded theme through its preview link before publishing. biticaret theme list --store <handle> lists a development store's themes and preview URLs (CLI).
Layout
layout/theme.liquid wraps every page. Two objects are required: content_for_header (inside <head>, injecting window.biticaret and compiled asset links) and content_for_layout (the template output).
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
<head>
<title>{{ page_title }}{% unless page_title contains shop.name %} | {{ shop.name }}{% endunless %}</title>
<link rel="canonical" href="{{ canonical_url }}">
{{ content_for_header }}
{{ 'base.css' | asset_url | stylesheet_tag }}
</head>
<body class="template-{{ template.name }}">
{% sections 'header-group' %}
<main id="main" class="page-width">
{{ content_for_layout }}
</main>
{% sections 'footer-group' %}
</body>
</html>A Liquid template can select an alternative layout with {% layout 'name' %}.
Templates
Each page type has a corresponding template. The storefront renders these templates:
| Template | Page |
|---|---|
index |
Home page |
product |
Product |
collection |
Collection |
list-collections |
List of collections |
cart |
Cart |
page |
Content page |
search |
Search |
404 |
Page not found |
password |
Storefront login page for a password-protected store |
gift_card |
Gift card page |
blog |
Blog (/blogs/<blog>) and tag-filtered blog (/blogs/<blog>/tagged/<tag>) |
article |
Blog post (/blogs/<blog>/<post>) |
metaobject/<type> |
Entry page for a metaobject type with web pages enabled (/pages/<type handle>/<entry handle>); returns 404 without a template |
You can add alternate templates for the same type using names such as product.<suffix>.json. The template is resolved from the ?view=<suffix> query parameter first, then the resource's template_suffix, and otherwise the default template. If a suffix does not exist in the theme, the default template is used.
If there is no password template, the platform renders a built-in password form. Policy pages (/policies/<name>) are generated by the platform and rendered inside the theme's layout.
Customer account pages (sign in, account, order details, addresses, profile and personal data requests) are rendered by the platform inside the theme's layout. templates/customers/* files may exist in a theme, but they are not used. Layouts can tell these pages apart via request.page_type (customers/login, customers/account, customers/order, customers/addresses, customers/profile). Customers sign in using a one-time email code; /account/register and /account/recover redirect to the sign-in page. Blog comments are not supported: comment fields are always empty.
A JSON template lists the page's sections and their display order:
{
"sections": {
"featured-collection": {
"type": "featured-collection",
"settings": {}
}
},
"order": [
"featured-collection"
]
}type is the filename under sections/, and settings holds that section's setting values.
A section's blocks are configured in blocks and block_order:
{
"sections": {
"featured-collection": {
"type": "featured-collection",
"settings": { "heading": "Featured" },
"blocks": {
"promo": {
"type": "promo",
"settings": { "text": "Free shipping" }
},
"note": {
"type": "promo",
"disabled": true,
"settings": { "text": "Hidden note" }
}
},
"block_order": ["promo", "note"]
}
},
"order": ["featured-collection"]
}blocks maps each block ID to its configuration. type refers either to a block type declared in the section schema's blocks list or to a theme block under blocks/, and settings holds the block's values. Blocks render in block_order (or object key order if block_order is omitted). A block with "disabled": true is skipped. A block with "static": true is excluded from the dynamic list and rendered explicitly by ID ({% content_for 'block', type: 'promo', id: 'note' %}, reading settings from the matching entry in blocks). A theme block can define its own nested blocks and block_order.
Sections
A section is a Liquid file under sections/: its markup followed by its settings schema inside {% schema %}:
<section class="featured-collection">
<h2>{{ section.settings.heading | escape }}</h2>
<ul class="grid">
{%- for product in featured.products limit: section.settings.limit -%}
<li>{% render 'product-card', product: product %}</li>
{%- else -%}
<li>{{ 'collections.general.empty' | t }}</li>
{%- endfor -%}
</ul>
</section>
{% schema %}
{
"name": "t:sections.featured-collection.name",
"settings": [
{
"type": "text",
"id": "heading",
"label": "t:sections.featured-collection.settings.heading.label",
"default": "Featured"
},
{
"type": "collection",
"id": "collection",
"label": "t:sections.featured-collection.settings.collection.label"
}
],
"presets": [
{
"name": "t:sections.featured-collection.name"
}
]
}
{% endschema %}Each section is wrapped in <div id="biticaret-section-<id>" class="biticaret-section">. Setting tag in the schema changes the wrapper element (article, aside, div, footer, header or section), and class appends CSS classes. Inside the section, access its data via section.id, section.settings and section.blocks.
Section groups are lists of sections invoked from the layout ({% sections 'header-group' %}). They follow the same format as JSON templates and are wrapped with class biticaret-section-group-<group>:
{
"type": "header",
"name": "t:sections.header-group.name",
"sections": {
"header": {
"type": "header",
"settings": {}
}
},
"order": [
"header"
]
}{% section 'name' %} renders a single static section directly.
Blocks
A section schema declares which block types it accepts in blocks, and the section loops over section.blocks to render them. Theme blocks under blocks/ are rendered with {% content_for 'blocks' %}, each wrapped in <div id="biticaret-block-<id>" class="biticaret-block …">.
Include {{ block.biticaret_attributes }} on each block's root element so the theme editor can identify and select it; outside the editor, this outputs nothing.
A section whose schema includes {"type": "@app"} in blocks accepts app blocks. App blocks are wrapped in <div id="biticaret-block-<id>" class="biticaret-app-block">. In JSON templates, their type has the form biticaret://apps/<app>/blocks/<name>/<uuid>. If the app is uninstalled, the block produces no output.
App embeds (app blocks injected page-wide) are stored under current.blocks in config/settings_data.json. Enabled embeds are injected before </head> or </body>. Store owners toggle them in the theme editor.
Settings
config/settings_schema.json defines global theme settings. Its first entry, theme_info, declares the theme's name and version:
[
{
"name": "theme_info",
"theme_name": "Skeleton",
"theme_version": "1.0.0",
"theme_author": "biticaret"
},
{
"name": "t:settings_schema.colors.name",
"settings": [
{
"type": "color",
"id": "color_background",
"label": "t:settings_schema.colors.settings.background.label",
"default": "#ffffff"
}
]
}
]config/settings_data.json stores active values under current, which Liquid accesses as settings.<id>:
{
"current": {
"color_background": "#ffffff",
"page_width": 1200
}
}Store owners edit these values in the admin settings form or in the theme editor; both update settings_data.json.
Setting types:
| Type | Value |
|---|---|
text, textarea, html, richtext, inline_richtext |
Text |
select, radio, text_alignment |
Selected option |
checkbox |
Boolean (true or false) |
number, range |
Number |
color, color_background |
Color |
color_scheme, color_scheme_group |
Color scheme and scheme definitions (1 to 50 schemes) |
font_picker |
A font from biticaret's font catalogue or a system font |
image_picker, video, video_url |
Image, uploaded video, or YouTube/Vimeo URL |
url, link_list |
URL or menu |
product, collection, page, product_list, collection_list |
Store resources |
blog, article |
Blog or blog post (blog/post handle); exposed in Liquid as blog and article objects |
metaobject, metaobject_list |
One metaobject entry or a list of entries; schema sets metaobject_type. Exposed in Liquid as metaobject entry objects |
liquid |
Liquid snippet (up to 50,000 bytes) |
Resource setting values are validated against the store's records on save; missing resources resolve to empty values.
A url setting accepts relative paths, #, http(s), mailto:, tel: and biticaret:// references. When a setting's visible_if condition evaluates to false, the editor hides the setting while preserving its saved value; the storefront still exposes every value.
Translations
locales/ holds one JSON file per language, with .default on the default language file (tr.default.json). Every buyer-facing string is resolved from these files using the t filter:
{
"general": {
"skip_to_content": "Skip to content"
}
}<a class="skip-link" href="#main">{{ 'general.skip_to_content' | t }}</a>*.schema.json files store labels displayed in the theme settings form; schemas reference them with t: keys (e.g. "label": "t:settings_schema.colors.settings.background.label").
Assets
Link to files under assets/ with asset_url. The generated URL includes a content-derived ?v= query parameter so caches bust automatically when the file changes:
{{ 'base.css' | asset_url | stylesheet_tag }}Do not hard-code CDN or store URLs: always use asset_url, file_url and routes. Sass is not supported. To use theme settings inside a stylesheet, name it assets/<name>.css.liquid: the platform renders it with your settings and you reference it as '<name>.css' | asset_url.
Contents of section {% stylesheet %} and {% javascript %} blocks are compiled into a single bundle for the theme and included by content_for_header.
Theme boundaries: cart and checkout
The theme renders the cart page (templates/cart) and add-to-cart UI, updating the cart via /cart/*.js endpoints (Endpoints a theme calls). The checkout (/checkouts/<cart token>) is owned by the platform: themes cannot render or customize checkout templates. Totals, shipping methods, payment methods and consent checkboxes are rendered by the platform's own interface. Apps customize checkout through extensions (checkout functions and UI extensions: App configuration files); themes play no part in checkout.
Preview and publish
In the admin, Online Mağaza > Temalar (Online store > Themes) shows the published theme and the theme library. Every uploaded or duplicated theme starts unpublished with its own Önizle (Preview) link, which appends ?preview_theme_id=<theme id> to the store URL. The storefront stores the ID in a signed cookie and redirects to the clean URL so the browser stays in preview mode; passing an empty ID clears the preview. Anyone with the link can preview the theme, though password-protected stores still require the storefront password.
When ready, clicking Yayınla (Publish) makes the theme live for visitors. Kopyala (Duplicate) creates an unpublished copy so you can iterate without affecting the published theme. A store can hold up to 20 themes. There is no theme store yet: themes are uploaded as ZIP files and remain scoped to the store they are uploaded to.
Endpoints a theme calls
- Cart: /cart.js, /cart/add.js, /cart/change.js, /cart/update.js, /cart/clear.js (also with
.json). Cart mutation requests can passsectionsto receive updated HTML undersections, rendered in the context ofsections_url(or the referring page). - Cart and
localizationform submissions are accepted only from the store's own pages: requests from external origins receive403and are ignored. - Product:
/products/<product>.jsreturns the product with all its variants as JSON. - Section rendering:
?sections=<id,…>(up to five sections) and?section_id=<id>. - Search suggestions: /search/suggest.json. Product recommendations: /recommendations/products.
- Blog feed:
/blogs/<blog>.atom.
Names and JavaScript
- In HTML, CSS and JavaScript:
biticaret-section-<id>,biticaret-section,biticaret-block-<id>,biticaret-app-block. window.biticaret:shop,locale,currency,country,theme,routes.rootanddesignMode.window.biticaret.customerPrivacyexposes cookie consent APIs:analyticsProcessingAllowed(),marketingAllowed(),preferencesProcessingAllowed(),shouldShowBanner(),showPreferences(),setTrackingConsent({ analytics, marketing, preferences }, callback)andcurrentVisitorConsent(). Any hidden link or button withdata-biticaret-privacy-preferencesis shown automatically while the cookie banner is active and reopens preferences on click.window.biticaret.analytics.publish(name, data)sends a custom event to installed web pixels (Web pixels).- The theme editor dispatches these DOM events on section and block elements:
biticaret:section:load,biticaret:section:unload,biticaret:section:select,biticaret:section:deselect,biticaret:section:reorder,biticaret:block:select,biticaret:block:deselect. Inside the editor,request.design_modeistrue.