Theme Structure

How a Quill theme is organised, with folders for layouts, sections, snippets, and assets.

A theme is the collection of files that control how a storefront looks. It contains templates, sections, snippets, stylesheets, scripts, and static assets. Understanding the folder structure helps you find files quickly and add new ones in the right place.

Directory layout

theme/
  layout/
    theme.liquid          Main layout wrapper
  templates/
    index.liquid          Homepage
    product.liquid        Product pages
    collection.liquid     Collection pages
    cart.liquid           Cart page
    page.liquid           Static pages
    customers/
      login.liquid        Login page
      register.liquid     Registration page
      account.liquid      Account dashboard
      order.liquid        Order detail page
  sections/
    header.liquid         Site header
    footer.liquid         Site footer
    hero-banner.liquid    Hero banner section
    featured-collection.liquid
    ...
  snippets/
    product-card.liquid   Reusable product card
    price.liquid          Price display fragment
    pagination.liquid     Pagination controls
    ...
  assets/
    theme.css             Main stylesheet
    theme.js              Main script
    logo.png              Static images
    ...
  config/
    settings_schema.json  Theme-level settings definition
    settings_data.json    Current theme settings values
  locales/
    en.json               English translations
    fr.json               French translations
    ...

What each folder does

layout

The layout wraps every page. It contains the <html>, <head>, and <body> tags, plus the header and footer sections. Most themes have one layout file called theme.liquid.

templates

Templates define the content area of each page type. The layout renders the header and footer. The template fills in everything between them.

Each template file maps to a URL pattern. When a visitor goes to /products/classic-ring, the platform loads templates/product.liquid and passes it the matching product object.

sections

Sections are the building blocks of a page. They are self-contained blocks with their own HTML, CSS, JavaScript, and schema. Merchants can add and rearrange dynamic sections through the visual editor.

snippets

Snippets are reusable template fragments. They cannot be added to a page on their own. Instead, you include them with the render tag. Use snippets to avoid repeating the same code across multiple sections or templates.

assets

Static files like stylesheets, scripts, images, and fonts. Access them in templates using the asset_url filter.

config

Theme settings configuration. The settings_schema.json file defines the settings form in the visual editor. The settings_data.json file stores the merchant's current values.

locales

Translation files for each language. Each file is a JSON object that maps keys to translated strings. The t filter reads from these files at render time.

How pages are built

When a visitor requests a page, the platform assembles the final HTML in this order:

Load the layout file (usually theme.liquid)
Load the matching template for the page type
The template renders its sections (both static and dynamic)
Each section renders its template, pulling in snippets as needed
Asset URLs are resolved through the CDN
The final HTML is cached until the next revalidation

The layout uses {{ content_for_layout }} as a placeholder. The rendered template output replaces this tag.

<!DOCTYPE html>
<html>
<head>
  <title>{{ page_title }} – {{ store.name }}</title>
  {{ content_for_header }}
  <link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
</head>
<body>
  {% section 'header' %}

  <main>
    {{ content_for_layout }}
  </main>

  {% section 'footer' %}

  <script src="{{ 'theme.js' | asset_url }}"></script>
</body>
</html>

On this page