# Theme code (Liquid sections)

> Write custom sections, blocks, and snippets for a Repzo online store in a Liquid-style template language, with settings store owners edit in the builder.

Theme code lets developers and agencies add their own **sections**, **blocks**, and **snippets** to an online store theme. You write them in a Liquid-style template language, and store owners then use them in the [store builder](https://workstation.repzo.com/docs/online-store/store-builder) like built-in sections, with the settings your `{% schema %}` declares.

Most developers work from the [`repzo` CLI](https://workstation.repzo.com/docs/developers/online-store/cli) with an AI tool: `repzo store pull` downloads the theme as a folder, and you edit it in your own editor. Quick fixes can also be made in the builder's [Code view](https://workstation.repzo.com/docs/online-store/edit-code).

> **Liquid-style, not Shopify**
>
> Data names follow Shopify where they can, so `{{ product.title }}`, `{% for %}` and `| money` work as you expect. A Shopify theme will not run as it is, though, and **theme code can't run JavaScript**. Use the [ready-made behaviours](#ready-made-behaviours) instead.

The full list of objects, filters, and tags is in the [theme code reference](https://workstation.repzo.com/docs/developers/online-store/theme-code-reference).

## The theme folder

`repzo store pull` writes one theme of a site as a folder:

| Path | Holds |
|---|---|
| `AGENTS.md` | The theme code guide: format, objects, filters, tags, behaviours, limits, and examples. AI tools read it before writing code. |
| `sections/<name>.liquid` | A custom section: template, optional `{% stylesheet %}`, and `{% schema %}`. Its type is `custom:<name>`. |
| `blocks/<name>.liquid` | A custom block with the same parts. Its type is `custom:<name>`, used inside sections whose schema accepts it. |
| `snippets/<name>.liquid` | A reusable piece of template, drawn with `{% render '<name>' %}`. No schema. |
| `templates/<page>.json` | One page each: `index.json` (home), `product.json`, `collection.json`, `page.about.json`, and so on. |
| `sections/header-group.json`, `sections/footer-group.json` | The header and footer that every page shares: `{ "sections": [...] }`. |
| `config/settings.json` | Theme settings (colors, color schemes, fonts, logo, social links), read in templates as `settings.<id>`. |
| `config/theme.json` | The theme's other parts: `customCss` and `embeds` (WhatsApp button, chat, pixels). |
| `locales/<lang>.json` | The store's built-in words, one file per language (`{"add_to_cart": "Add to bag"}`). Read them with `{{ 'add_to_cart' \| t }}`. |
| `.repzo-store.json` | The site, the theme, and the revision you pulled. Don't edit it. |

Code file names use lowercase `a-z`, `0-9`, `-`, and `_` (up to 60 characters) and end in `.liquid`. The code files are stored inside the theme, so they are versioned and published with it.

A page template looks like this:

```json
{
  "kind": "page",
  "handle": "about",
  "title": { "en": "About us", "ar": "من نحن" },
  "document": { "sections": [] }
}
```

## Workflow

```bash
repzo store pull SITE_ID --dir store        # download the theme as a folder
repzo store dev --dir store                 # watch: check and push every save, print a preview link
repzo store push --dir store --dry-run      # check everything and see the diff
repzo store push --dir store --yes          # save to the draft
repzo store publish SITE_ID --data '{"revision": 12}' --yes   # go live
```

Pushing changes the theme's draft only. Shoppers see nothing until the theme is published from the builder, the CLI, or the API. See [Build a store from the CLI](https://workstation.repzo.com/docs/developers/online-store/cli) for every command.

## Use a custom section on a page

Add the section to a template's `document.sections`, or to a header or footer group, by its type. Settings are keyed by id:

```json
{ "type": "custom:staff-picks", "settings": { "heading": { "en": "Staff picks", "ar": "اختياراتنا" }, "visible": 4 } }
```

Leave `id` out for new sections and blocks, and the server gives them one. Keep the ids of existing ones.

You can also add it with `repzo store sections add SITE_ID --data '{"type":"custom:staff-picks"}' --yes`. In the builder, store owners find it under **Add section → Custom**, built from the section's `presets`.

## A section file

A section file has three parts: the template, an optional `{% stylesheet %}`, and one `{% schema %}`.

```liquid
<div class="banner">
  {% if section.settings.image %}{{ section.settings.image | image_tag: class: 'banner__image', loading: 'eager' }}{% endif %}
  <div class="banner__text">
    <h2>{{ section.settings.heading }}</h2>
    {% if section.settings.link != blank %}<a class="banner__button" href="{{ section.settings.link }}">{{ section.settings.button_label }}</a>{% endif %}
  </div>
  <div class="banner__features">{% content_for 'blocks' %}</div>
</div>

{% stylesheet %}
.banner { position: relative; display: grid; gap: 2rem; padding: 4rem 1.5rem; text-align: center; }
.banner__image { width: 100%; max-height: 32rem; object-fit: cover; border-radius: var(--sf-card-radius); }
.banner h2 { font-family: var(--sf-font-heading); font-size: calc(2.5rem * var(--sf-heading-scale)); }
.banner__button { display: inline-block; margin-top: 1rem; padding: .75rem 1.5rem; border-radius: var(--sf-button-radius); background: var(--sf-btn); color: var(--sf-btn-fg); }
.banner__features { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr)); }
{% endstylesheet %}

{% schema %}
{
  "name": "Banner",
  "settings": [
    { "type": "image_picker", "id": "image", "label": "Image" },
    { "type": "text", "id": "heading", "label": "Heading", "default": "Made for you" },
    { "type": "text", "id": "button_label", "label": "Button label", "default": "Shop now" },
    { "type": "url", "id": "link", "label": "Button link", "default": "/collections/all" }
  ],
  "blocks": [{ "type": "@theme" }],
  "max_blocks": 6,
  "presets": [{ "name": "Banner" }]
}
{% endschema %}
```

- **Template**: HTML with `{{ output }}` and `{% tags %}`. The section's own values are `section.settings.<id>`, and its blocks are `section.blocks`.
- **`{% stylesheet %}`**: CSS scoped to this section, up to 16 KB. Snippets can't have one.
- **`{% schema %}`**: JSON describing the settings, blocks, and presets. See below.

### Theme variables

Inside `{% stylesheet %}`, use the theme's CSS variables so your section follows the store's look:

| Variable | Holds |
|---|---|
| `--sf-bg`, `--sf-fg`, `--sf-accent` | The section's color scheme: background, text, accent |
| `--sf-btn`, `--sf-btn-fg` | Button background and text |
| `--sf-font-heading`, `--sf-font-body` | The theme's fonts |
| `--sf-card-radius`, `--sf-button-radius` | Corner radius of cards and buttons |
| `--sf-heading-scale` | Heading size multiplier |
| `--sf-page-width` | The page width |

Arabic pages are right-to-left. Use logical CSS such as `margin-inline-start`, `text-align: start`, and `inset-inline-end` instead of left and right.

## The schema

`{% schema %}` holds one JSON object per file:

| Key | Meaning |
|---|---|
| `name` | Shown in the builder. Text, or `{"en": "…", "ar": "…"}`. |
| `settings` | Up to 60 settings: `{ "type", "id", "label", "default"?, "info"?, … }`. Ids use letters, digits, `_`, or `-`. |
| `blocks` | What the section accepts (see [Blocks](#blocks)). |
| `max_blocks` | How many blocks at most (up to 50). |
| `presets` | `[{ "name", "settings"?, "blocks"? }]`: what **Add section** inserts. Without presets, a section can still be added by type. |
| `enabled_on`, `disabled_on` | Where it can be used: `{ "templates": ["product", "collection"], "groups": ["header", "footer"] }`. |
| `tag`, `class` | The wrapper element and its extra classes. |

Template names in `enabled_on` and `disabled_on` follow Shopify: `index`, `product`, `collection`, `list-collections`, `cart`, `search`, `404`, `password`, `blog`, `article`, `page`, `gift_card`, and `metaobject` (content entry pages).

Text defaults can have one value per language: `"default": {"en": "Shop now", "ar": "تسوق الآن"}`. When the store has English and Arabic, give every text setting both values, and give fixed words in templates an Arabic version with `| t: ar: '…'`.

### Setting types

| Type | In the builder | What the template gets |
|---|---|---|
| `text` | One line of text (English + Arabic). | Text in the page's language. |
| `textarea` | Several lines (English + Arabic). | Text in the page's language (use `newline_to_br`). |
| `richtext` | Paragraphs (English + Arabic). | HTML paragraphs (`<p>…</p>`). |
| `inline_richtext` | One line of text. | Text. |
| `html` | Merchant HTML (sanitized when drawn). | HTML. |
| `image_picker` | An image from the media library (also `image`). | Image object (`url`, `alt`; prints its URL) or nil. |
| `url` | A link (site path, https, mailto, tel). | Text. |
| `video_url` | A video link. | Text. |
| `color` | A color (`#rrggbb`). | Text. |
| `range` | A slider: `min`, `max`, `step`, `unit`, and a required `default`. | Number. |
| `number` | A number (`min`, `max`, `step` optional). | Number. |
| `select` | A dropdown: `options: [{ value, label }]`. | The chosen value. |
| `radio` | Buttons: `options: [{ value, label }]`. | The chosen value. |
| `text_alignment` | left / center / right. | The chosen value. |
| `checkbox` | On / off. | `true` or `false`. |
| `product` | One product. | Product object or nil. |
| `product_list` | Products (limit up to 12). | List of product objects. |
| `collection` | One collection. | Collection object with its first 24 products, or nil. |
| `collection_list` | Collections (limit up to 12). | List of collection objects (without products). |
| `blog` | A blog. | `{ title, handle, articles }` with its latest 12 posts. |
| `link_list` | A navigation menu. | Menu object (`title`, `links`) or nil. |
| `datetime` | A date and time (also `date`). | ISO text (use `date`, or `data-sf-countdown`). |
| `color_scheme` | One of the theme's color schemes. When the setting id is `color_scheme`, the section's background and text follow it. | Scheme id (`scheme-1`…). |
| `phone` | A phone number (E.164). | Text. |
| `header` | A heading in the settings panel. | — |
| `paragraph` | A note in the settings panel. | — |

## Blocks

A section's `blocks` list says what it accepts:

| Entry | Accepts |
|---|---|
| `{ "type": "@theme" }` | Every block file in the theme, and every builder block: heading, text, button, image, product card, buy buttons, group, and more. |
| `{ "type": "feature" }` | The block file `blocks/feature.liquid`. |
| `{ "type": "heading" }` | One builder block type. |
| `{ "type": "quote", "name": "Quote", "settings": [...] }` | An inline block that the section's own template draws. |

### Block files

A block file has its own template, CSS, and schema. The section draws its blocks with `{% content_for 'blocks' %}` (all of them, in order) or with `{% render_block block %}` inside a loop.

```liquid
<div class="feature">
  {% if block.settings.icon %}{{ block.settings.icon | image_tag: class: 'feature__icon' }}{% endif %}
  <h3>{{ block.settings.title }}</h3>
  <p>{{ block.settings.text | newline_to_br }}</p>
</div>

{% stylesheet %}
.feature { padding: 1.25rem; border-radius: var(--sf-card-radius); background: color-mix(in srgb, var(--sf-fg) 5%, transparent); }
.feature__icon { width: 2.5rem; height: 2.5rem; object-fit: contain; }
.feature h3 { margin: .5rem 0 .25rem; font-family: var(--sf-font-heading); }
{% endstylesheet %}

{% schema %}
{
  "name": "Feature",
  "settings": [
    { "type": "image_picker", "id": "icon", "label": "Icon" },
    { "type": "text", "id": "title", "label": "Title", "default": { "en": "Fast delivery", "ar": "توصيل سريع" } },
    { "type": "textarea", "id": "text", "label": "Text" }
  ],
  "presets": [{ "name": "Feature" }]
}
{% endschema %}
```

Your block files also go into the store's own sections that accept any block, such as **Section** and **Group**.

### Inline blocks

An inline block is declared in the section's schema and drawn by the section's own template. Put `{{ block.sf_attributes }}` on its outer element so store owners can select it in the builder:

```liquid
<div class="quotes" data-sf-carousel data-sf-autoplay="{{ section.settings.autoplay_ms }}">
  <div class="quotes__track" data-sf-track>
    {% for block in section.blocks %}
      {% case block.type %}
        {% when 'quote' %}
          <figure class="quotes__slide" data-sf-slide {{ block.sf_attributes }}>
            <blockquote>{{ block.settings.text }}</blockquote>
            <figcaption>{{ block.settings.author }}</figcaption>
          </figure>
      {% endcase %}
    {% endfor %}
  </div>
  <button data-sf-prev aria-label="{{ 'Previous' | t: ar: 'السابق' }}">‹</button>
  <button data-sf-next aria-label="{{ 'Next' | t: ar: 'التالي' }}">›</button>
  <div data-sf-dots></div>
</div>

{% schema %}
{
  "name": "Customer quotes",
  "settings": [
    { "type": "range", "id": "autoplay_ms", "label": "Autoplay (ms, 0 = off)", "min": 0, "max": 10000, "step": 500, "default": 5000 }
  ],
  "blocks": [
    {
      "type": "quote",
      "name": "Quote",
      "settings": [
        { "type": "textarea", "id": "text", "label": "Quote" },
        { "type": "text", "id": "author", "label": "Author" }
      ]
    }
  ],
  "max_blocks": 8,
  "presets": [
    {
      "name": "Customer quotes",
      "blocks": [
        { "type": "quote", "settings": { "text": "Lovely quality, fast delivery.", "author": "Sara" } },
        { "type": "quote", "settings": { "text": "My new favourite store.", "author": "Omar" } }
      ]
    }
  ]
}
{% endschema %}
```

### Builder blocks

Builder blocks (heading, text, button, image, product card, buy buttons, variant picker, group, and others) go into a section that accepts `"@theme"` or names their type. Place them like block files, with `{% content_for 'blocks' %}` or `{% render_block block %}`, and the store draws them exactly as in its own sections. `block.builder` is `true` for them.

Product blocks show the product picked in the section's `product` setting, or the page's product when there isn't one.

## Snippets

A snippet is a reusable piece of template with no schema. Pass it the variables it needs; it can't see the caller's other variables.

```liquid
{% render 'product-card', product: product %}
```

```liquid
<a class="card" href="{{ product.url }}">
  {% if product.featured_image %}{{ product.featured_image | image_tag: class: 'card__image' }}{% endif %}
  <span class="card__title">{{ product.title }}</span>
  <span class="card__price">
    {{ product.price | money }}
    {% if product.on_sale %}<s>{{ product.compare_at_price | money }}</s>{% endif %}
  </span>
  {% unless product.available %}<span class="card__badge">{{ 'sold_out' | t }}</span>{% endunless %}
</a>
```

## Pages of products

`{% paginate %}` shows a list one page at a time. The URL's `?page=` picks the page, and `{{ paginate | default_pagination }}` draws the page links. You can also build your own pager from `paginate.parts`, `paginate.previous.url`, and `paginate.next.url`.

```liquid
{% paginate collection.products by 12 %}
  {% for product in collection.products %}
    {% render 'product-card', product: product %}
  {% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}
```

It works for `collection.products` on collection pages, `section.settings.<collection>.products`, and `search.results` on the search page, with up to 48 items a page. Without `{% paginate %}`, a collection gives its first 24 products.

## Forms

A theme can't write its own `<form>` element; it is removed. Use the `{% form %}` tag instead, and the store sends the form for you:

| Form | Sends to | Fields |
|---|---|---|
| `{% form 'contact' %}` | The store's inbox and contacts, like the built-in Contact form | `email`, `name`, `phone`, `message` (or `contact[email]`…), plus any other named fields |
| `{% form 'newsletter' %}` | The store's contacts, like the built-in Email signup | `email` |
| `{% form 'product', product %}` | The cart | `variant_id` (defaults to the first available variant) and `quantity` |

Mark what to show afterwards with `data-sf-form-success` and `data-sf-form-error`:

```liquid
{% form 'newsletter' %}
  <input type="email" name="email" required>
  <button>{{ 'Join' | t: ar: 'اشترك' }}</button>
  <p data-sf-form-success>{{ 'Thanks!' | t: ar: 'شكراً!' }}</p>
  <p data-sf-form-error></p>
{% endform %}
```

While it's being sent, the form carries `data-state` = `sending`, `success`, or `error` for your CSS. Forms need the store's own script, so they don't post without JavaScript in the shopper's browser.

## Ready-made behaviours

Theme code can't run JavaScript. Instead, add these `data-sf-*` attributes and the store makes them work, in the builder preview too:

| Behaviour | Attributes | What it does |
|---|---|---|
| Tabs | `data-sf-tabs`, `data-sf-tab`, `data-sf-panel` | A wrapper with buttons `data-sf-tab="k"` and panels `data-sf-panel="k"`. The first panel is open. |
| Accordion | `data-sf-accordion`, `data-sf-trigger`, `data-sf-content`, `data-sf-open` | A button `data-sf-trigger="k"` opens and closes `data-sf-content="k"`. `data-sf-accordion="single"` keeps one open; `data-sf-open` starts one open. |
| Slider | `data-sf-carousel`, `data-sf-track`, `data-sf-slide`, `data-sf-prev`, `data-sf-next`, `data-sf-dots`, `data-sf-autoplay` | A horizontally scrolling track of slides with arrows, dots, and autoplay in milliseconds (off for reduced motion). |
| Countdown | `data-sf-countdown`, `data-sf-days`, `data-sf-hours`, `data-sf-minutes`, `data-sf-seconds` | Counts down to an ISO date, such as a `datetime` setting. Optional children receive the numbers. |
| Pop-up | `data-sf-modal`, `data-sf-modal-open`, `data-sf-modal-close`, `data-sf-modal-delay` | A modal opened by `data-sf-modal-open="k"` buttons and closed by `data-sf-modal-close`, Escape, or a click outside. `data-sf-modal-delay="3000"` opens it once per visit after a delay. |
| Show more | `data-sf-show-more`, `data-sf-show-more-button` | Shows the first N children of a list (`data-sf-show-more="N"`) and the rest when the button is pressed. |
| Copy | `data-sf-copy` | A button that copies text, such as a discount code. |
| Reveal | `data-sf-reveal` | Animates in on scroll: `fade`, `fade-up`, `fade-down`, `zoom`, `slide-start`, `slide-end`. |
| Lightbox | `data-sf-lightbox` | Opens a picture full screen. `data-sf-lightbox="g"` groups pictures with arrows. |
| Form status | `data-sf-form-success`, `data-sf-form-error` | Inside `{% form %}`: shown after the form was sent, or when it failed. |
| Cart | `data-sf-cart` | Shows the shopper's live cart: `data-sf-cart="count"` (items) or `"total"` (formatted total). |

For example, a pop-up:

```html
<button data-sf-modal-open="news">Join</button>
<div data-sf-modal="news" class="modal">
  <div class="modal__box">… <button data-sf-modal-close>Close</button></div>
</div>
```

Pixels and chat widgets come from the store's own integrations, not from theme code.

## Checks and errors

The server checks every file each time it is saved, pushed, or validated, and reports problems as `file:line:column message`:

```text
sections/promo.liquid:3:1 <script> isn't allowed: theme code can't run JavaScript. Use the data-sf-* behaviours instead.
sections/staff-picks.liquid:7:9 Snippet "product-card" doesn't exist: add snippets/product-card.liquid.
snippets/card.liquid:8:3 warning: data-sf-zoom isn't one of the data-sf-* behaviours; it is removed when drawn.
```

**Errors** stop `repzo store push` and block publishing everywhere: in the builder, the CLI, the API, and a scheduled publish. Errors include broken Liquid, invalid schema JSON, unknown filters, tags, or setting types, missing snippets or block files, `<script>`, and size limits. **Warnings**, such as a removed tag or an unknown `data-sf-*` attribute, don't stop anything.

Files saved one at a time (in the builder's Code view or with `repzo store code put`) are kept even when they have errors, because they are only a draft. A section with errors draws nothing on the live store, and the builder shows its problem in its place.

Common fixes:

| Problem | Fix |
|---|---|
| `Unknown filter` | Use a filter from the [reference](https://workstation.repzo.com/docs/developers/online-store/theme-code-reference#filters) (`\| money`, not `\| format_money`). |
| `{% schema %} isn't valid JSON` | No trailing commas or comments. Keys and strings use double quotes. |
| Unknown setting type | Use a type from the [setting types](#setting-types) table (`image_picker`, not `image_upload`). |
| Missing snippet | `{% render 'name' %}` needs `snippets/name.liquid`. |
| `<script>` or `onclick` | Remove it and use a [ready-made behaviour](#ready-made-behaviours). |
| A setting id used in the template but not in the schema | Add it to `settings`, or fix the spelling. |
| The section isn't in **Add section** | Give it `presets`. |
| The page shows nothing for a product or collection | `product` and `collection` are only set on their own pages. Elsewhere, use a `product` or `collection` setting. |

## Limits and safety

- **No JavaScript.** `<script>`, `on*=` attributes (`onclick`…), `javascript:` links, and `{% javascript %}` are errors. `<iframe>`, `<object>`, `<embed>`, `<form>`, and `<style>` are removed when drawn. CSS goes in `{% stylesheet %}`.
- Output is sanitized like the builder's AI blocks, and CSS is scoped to its section or block (no `@import`, no `url(javascript:…)`).
- Templates only read data. `{% render %}` only finds this theme's snippets. `{% include %}`, `{% layout %}`, `{% section %}`, and `{% sections %}` aren't available.
- Values aren't escaped automatically. Use `| escape` for text you print inside attributes.
- `cart` is always empty when the page is drawn, because pages are cached for every shopper. Show the live cart with `data-sf-cart`.
- Up to 60 code files per theme, 48 KB per file, and 512 KB in all. `{% stylesheet %}` is cut at 16 KB.
- Each section gets 250 ms of render time and 256 KB of HTML, and loops are memory-capped.

## Related pages

- [Theme code reference](https://workstation.repzo.com/docs/developers/online-store/theme-code-reference)
- [Build a store from the CLI](https://workstation.repzo.com/docs/developers/online-store/cli)
- [Online store API](https://workstation.repzo.com/docs/developers/online-store/commerce-api)
- [Edit code in the builder](https://workstation.repzo.com/docs/online-store/edit-code)
- [The store builder](https://workstation.repzo.com/docs/online-store/store-builder)
- [Themes](https://workstation.repzo.com/docs/online-store/themes)
