> ## Documentation Index
> Fetch the complete documentation index at: https://help.eaglecart.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eaglecart Themes: Storefront Liquid Templating Guide

> Learn Eaglecart's Liquid theme system: directory layout, template objects, and the built-in code editor you need to build and customise your storefront.

Eaglecart themes use a Liquid-based template language to render your storefront. Developers can create fully custom themes from scratch or extend existing ones by editing templates, sections, and snippets directly in the admin code editor or locally with the Theme CLI. Every visual layer of your storefront — product pages, collections, the cart, checkout fragments — is controlled by theme files you own and can modify freely.

> [!NOTE]
>
> The theme code editor is accessible at **Online Store → Themes → \[your theme] → Edit code**. Changes saved here take effect immediately on the live theme, so always work on a duplicate unless you intend to publish right away.

***

## Theme Structure

A theme is a directory of Liquid templates, assets, configuration files, and locale strings. The layout below shows every top-level folder and its purpose:

```
my-theme/
├── templates/          # Page-level templates
│   ├── product.liquid
│   ├── collection.liquid
│   ├── cart.liquid
│   ├── index.liquid
│   ├── page.liquid
│   └── 404.liquid
├── sections/           # Reusable, merchant-customisable content sections
│   ├── header.liquid
│   ├── footer.liquid
│   └── featured-collection.liquid
├── snippets/           # Small Liquid partials included via {% render %}
│   ├── product-card.liquid
│   └── icon-cart.liquid
├── assets/             # Static files: CSS, JS, fonts, and images
│   ├── main.css
│   ├── theme.js
│   └── logo.png
├── config/             # Theme settings schema and saved data
│   ├── settings_schema.json
│   └── settings_data.json
└── locales/            # Translation strings
    ├── en.json
    └── fr.json
```

### `/templates/`

Page templates determine what renders when a visitor navigates to a specific route. Each file corresponds to a URL pattern — `product.liquid` renders at `/products/:handle`, `collection.liquid` at `/collections/:handle`, and so on.

### `/sections/`

Sections are reusable content blocks that merchants can add, remove, and reorder in the Theme Editor without writing code. Each section file contains Liquid markup and an optional `{% schema %}` block that defines its configurable settings.

### `/snippets/`

Snippets are small, focused Liquid partials. Include them anywhere in a template or section using `{% render 'snippet-name' %}`. Unlike sections, snippets have no schema block and are not merchant-configurable.

### `/assets/`

Place all CSS, JavaScript, image, and font files here. Eaglecart serves them from a CDN-backed URL. Reference any asset in Liquid using the `asset_url` filter (see the [Customization guide](https://help.eaglecart.com/developers/themes/customization)).

### `/config/`

`settings_schema.json` defines the settings that appear in the Theme Editor. `settings_data.json` stores the merchant's saved values. Commit `settings_schema.json` to version control; treat `settings_data.json` as environment-specific data.

### `/locales/`

Each file contains a nested JSON object of translation keys for a specific locale. The `en.json` file is the default fallback. Add a new locale file (e.g. `de.json`) and Eaglecart automatically offers it when the storefront language is set to German.

***

## Theme Objects

Eaglecart exposes a set of Liquid objects in every template context. Use these objects to access store data and render it dynamically.

| Object | Available in | Description |
| - | - | - |
| `shop` | All templates | Global store information — name, email, currency, money format, metafields |
| `product` | `product.liquid` and product-scoped sections | The current product, including variants, images, and metafields |
| `collection` | `collection.liquid` | The current collection, including its products, filters, and sort options |
| `cart` | All templates | The current visitor's cart — items, subtotal, and applied discounts |
| `customer` | All templates | The currently logged-in customer, or `nil` if the visitor is a guest |
| `settings` | All templates | Merged theme settings from `settings_schema.json` and the saved merchant data |

### Examples

```liquid Accessing theme objects in Liquid theme={null}
{% comment %}Display the store name{% endcomment %}
<p>Welcome to {{ shop.name }}!</p>

{% comment %}Show the product title and price{% endcomment %}
<h1>{{ product.title }}</h1>
<p>{{ product.selected_or_first_available_variant.price | money }}</p>

{% comment %}Iterate over items in the cart{% endcomment %}
{% for item in cart.items %}
  <li>{{ item.title }} &times; {{ item.quantity }}</li>
{% endfor %}

{% comment %}Greet a logged-in customer{% endcomment %}
{% if customer %}
  <p>Hello, {{ customer.first_name }}!</p>
{% endif %}

{% comment %}Use a merchant-configured setting{% endcomment %}
<body style="background-color: {{ settings.background_color }}">
```

***

## Next Steps

> [card] [Theme Customization](https://help.eaglecart.com/developers/themes/customization)
>
> Learn how to define theme settings, build custom sections, use the asset pipeline, and add translations to your Eaglecart theme.

> [card] [Webhook Overview](https://help.eaglecart.com/developers/webhooks/overview)
>
> Connect your storefront to external services by sending real-time event notifications with Eaglecart webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.