Liquid Theme System

Liquid Theme System

Cartly supports a Liquid-based theme engine that gives developers full control over storefront HTML rendering. Unlike the Visual Editor — which uses a drag-and-drop interface and React components — Liquid themes are code-first: you write template files using the Liquid templating language, and Cartly renders them on the server before sending HTML to the browser.

Liquid Themes vs. Visual Editor

• Visual Editor — No-code, drag-and-drop blocks, ideal for merchants who want quick customization without touching code.
• Liquid Themes — Full control over markup and logic, ideal for developers and agencies who need pixel-perfect designs or advanced dynamic content.

Both approaches can coexist. If a Liquid template file exists for a given page, Cartly renders it through the Liquid engine. If no Liquid file is found, the platform falls back to the React component rendered by the Visual Editor.

Installing a Theme from the Marketplace

1. Navigate to Admin → Online Store → Themes.
2. Click Explore Themes to open the theme marketplace.
3. Browse or search for a theme, then click Install.
4. The theme appears in your theme library, ready to preview or publish.

Publishing a Theme

In the theme library, find the theme you want to make live and click the Publish button. The published theme is immediately applied to your storefront. You can only have one published theme at a time; the previously published theme is moved back to draft status.

Theme File Structure

Every Liquid theme follows a standard directory layout:

my-theme/
├── layouts/
│   └── theme.liquid          # Main layout wrapper (header, footer, {content_for_layout})
├── templates/
│   ├── index.liquid           # Homepage
│   ├── product.liquid         # Product detail page
│   ├── collection.liquid      # Collection page
│   ├── cart.liquid            # Cart page
│   ├── page.liquid            # CMS pages
│   ├── blog.liquid            # Blog listing
│   └── article.liquid         # Single blog post
├── sections/
│   ├── header.liquid          # Header section
│   ├── footer.liquid          # Footer section
│   ├── hero.liquid            # Hero banner section
│   └── featured-products.liquid
├── snippets/
│   ├── price.liquid           # Reusable price formatting
│   ├── product-card.liquid    # Product card partial
│   └── image.liquid           # Responsive image helper
├── assets/
│   ├── theme.css              # Stylesheets
│   └── theme.js               # Client-side JavaScript
└── config/
    ├── settings_schema.json   # Theme-level settings definition
    └── settings_data.json     # Current settings values

How Rendering Works

When a storefront page is requested, Cartly follows this process:

1. Determine the page type (product, collection, index, etc.).
2. Check if the published theme contains a matching Liquid template in templates/.
3. If a Liquid file exists, render it through the Liquid engine with the relevant data context (product, collection, cart, etc.).
4. Wrap the output in the layouts/theme.liquid layout.
5. If no Liquid file is found for the requested page, fall back to the default React component rendering pipeline.

This hybrid approach means you can incrementally adopt Liquid — override only the pages you need, and let the platform handle the rest.