Blocks

Blocks are the main building components of sites. They are reusable, configurable modules of content that creators add to pages using the site builder. Each block can be customised through settings defined in its schema, allowing creators to control content, layout and design without editing code.

Blocks can be added, removed and reordered on any page, giving creators flexibility to compose unique layouts.

Location

Each block lives in its own folder within the blocks directory and is defined in a block.liquid file. All available blocks must also be registered in the index.json file to be visible in the block library.

blocks
├── hero_block
│   └── block.liquid
├── text_block
│   └── block.liquid
├── image_gallery
│   └── block.liquid
└── index.json

Content

A block file contains three main parts:

Block structure

A block file uses YAML front matter (between --- delimiters) for the schema, followed by the block's markup, styles and scripts.

---
attributes:
  heading:
    type: string
    label: Heading
  background_color:
    type: color
    label: Background colour
    default:
      palette: body-bg
layout:
  - type: tab
    label: Content
    elements:
      - heading
  - type: tab
    label: Design
    elements:
      - background_color
---

<style>
  .{{ block.id }} {
    background-color: {{ background_color.rgba }};
  }
</style>

<section class="{{ block.id }}">
  <h1>{{ heading }}</h1>
</section>

Schema

The schema defines the variables (settings) that a creator can configure in the site builder. It consists of:

• attributes — The configurable variables with their types, labels, defaults and hints.
• layout — How the variables are organised into tabs and accordions in the site builder.

For full schema documentation, see the schema page.

Markup

The markup section contains HTML and Liquid code that renders the block. Schema variables are available directly by name within the block's Liquid code (e.g. {{ heading }}).

Each block instance is assigned a unique ID accessible via block.id. Use this to scope CSS styles to the specific block instance, preventing styles from leaking between blocks on the same page.

Styles

CSS can be included within <style> tags in the block. Styles should be scoped to the block instance using {{ block.id }} as a class selector:

<style>
  .{{ block.id }} {
    color: {{ text_color.rgba }};
  }

  .{{ block.id }} .card__title {
    font-size: 1.5rem;
  }
</style>

Scripts

JavaScript can be included within <script> tags at the bottom of the block. Use js- prefixed classes for JavaScript selectors to separate styling concerns from behaviour.

index.json

The index.json file in the blocks directory registers all available blocks and defines their display name and category. The category is used to group blocks in the site builder, making it easier for creators to find the block they need.

{
  "hero_block": {
    "name": "Hero Block",
    "category": "Hero"
  },
  "text_block": {
    "name": "Text Block",
    "category": "Text"
  }
}

Rendering partials

Blocks can render partials to reuse common components across multiple blocks:

{% render 'button-v1',
  block_id: block.id,
  cta_text: button_text,
  cta_link: button_link.url
%}

This keeps blocks DRY and ensures consistent UI components across the theme.