# 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 files
```

A 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`, `search` or `404` template is an error. Missing `list-collections` or `password` templates, `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_if` condition 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](../cli.md#list-store-themes)).

## 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).

```liquid
<!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:

```json
{
  "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`:

```json
{
  "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 %}`:

```liquid
<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>`:

```json
{
  "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:

```json
[
  {
    "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>`:

```json
{
  "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:

```json
{
  "general": {
    "skip_to_content": "Skip to content"
  }
}
```

```liquid
<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:

```liquid
{{ '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](#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](../apps/configuration.md)); 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 pass `sections` to receive updated HTML under `sections`, rendered in the context of `sections_url` (or the referring page).
- Cart and `localization` form submissions are accepted only from the store's own pages: requests from external origins receive `403` and are ignored.
- Product: `/products/<product>.js` returns 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.root` and `designMode`.
- `window.biticaret.customerPrivacy` exposes cookie consent APIs: `analyticsProcessingAllowed()`, `marketingAllowed()`, `preferencesProcessingAllowed()`, `shouldShowBanner()`, `showPreferences()`, `setTrackingConsent({ analytics, marketing, preferences }, callback)` and `currentVisitorConsent()`. Any hidden link or button with `data-biticaret-privacy-preferences` is 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](../apps/storefront-and-admin.md#add-a-web-pixel)).
- 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_mode` is `true`.

## Reference

- [Objects](objects.md)
- [Tags](tags.md)
- [Filters](filters.md)
