Sections and blocks

The section { } and block { } grammar belongs to Slurp. See Sections and blocks for the schema, the setting kinds and merge semantics. This page covers the ByteSell layer: default content, global zones, and the conditions under which a merchant’s block renders.

Default content

templates/<page key>.json supplies the content a store starts with when the theme is installed. From then on the merchant owns the content and the file is not consulted again.

site/templates/index.json

{
  "sections": [
    { "id": "hero", "type": "Hero", "settings": { "heading": "My store" } },
    { "id": "grid", "type": "ProductGrid", "settings": { "limit": 8 } },
    { "id": "faq",  "type": "Faq", "disabled": true,
      "blocks": [
        { "id": "q1", "type": "faq_item",
          "settings": { "question": "Do you offer refunds?" } }
      ] }
  ]
}

Key	Required	Notes
`type`	yes	A string matching `sections/<type>.slurp`.
`id`	no	Unique within the page.
`settings`	no	Omitted keys fall back to the schema default.
`disabled`	no	Present but not rendered. The merchant can enable it.
`blocks`	no	Nested block instances, same shape.

A duplicate id within one page fails the publish. The editor addresses a section as (page, id), so a repeat makes both unreachable. The same id on two different pages is permitted.

Global zones

A named group hosts chrome shared across pages. Place it in a layout:

site/layouts/base.slurp

{layout "@layouts/shell"}
  {sections "above_header"}
  {sections "header"}
  <slot />
  {sections "footer"}
{/layout}

Zones are not declared. A zone exists when a defaults file exists: adding templates/groups/header.json creates a zone named header, which {sections "header"} renders.

site/templates/groups/header.json

{
  "sections": [
    { "id": "nav", "type": "Header" }
  ]
}

The page’s own {sections} is stripped on entry to a component or layout, so it resolves only in a page. Named groups are not stripped, so a layout can compose them. Put {sections} in the page and {sections "header"} in the layout.

Merchants can hide a zone per page.

Block rendering rules

Both of the following fail silently.

A section targeting `@theme` must host `{blocks}`

@theme makes the merge accept every theme block type. If the markup then draws children by hand, the merge accepts a type the markup never draws: the merchant’s block persists in the database and the page renders without it.

---
section {
  name: "Links"
  blocks { @theme }
}
---
<ul>
  {blocks}
</ul>

The converse also applies. A section that draws its blocks by hand must not target @theme, or it advertises types it cannot render.

A theme block cannot use `{fetch}`

Publishing rejects any file under blocks/ containing a {fetch} at any depth:

blocks/product.slurp: a theme block cannot use {fetch} - it is evaluated before
the block renders, so it would silently produce nothing. Fetch from the browser
instead.

The fetch pass runs before blocks resolve, so the block renders empty with no diagnostic. Fetch from the browser with the SDK instead.

Files under `blocks/`

The block type is the filename, not the schema’s name. name is the label in the merchant’s palette.
Filenames are restricted to [A-Za-z0-9_-]. blocks/a/b.slurp is ignored: the renderer rejects the /, so the block would be addable but never render.
A file under blocks/ with no block { } schema is ignored rather than rejected, so partials can live there.

Section budgets

A section that exceeds a render budget fails the whole page rather than disappearing from it. A page silently missing one section is diagnosed as a content problem. See Limits.

Get started

Build

Ship

Reference

Default content

Global zones

Block rendering rules

A section targeting `@theme` must host `{blocks}`

A theme block cannot use `{fetch}`

Files under `blocks/`

Section budgets

​Default content

​Global zones

​Block rendering rules

​A section targeting @theme must host {blocks}

​A theme block cannot use {fetch}

​Files under blocks/

​Section budgets

Default content

Global zones

Block rendering rules

A section targeting `@theme` must host `{blocks}`

A theme block cannot use `{fetch}`

Files under `blocks/`

Section budgets