Developer Guide: Building and Customizing Fluid Themes

Fluid themes are built on the Liquid templating language — a proven, widely adopted templating engine — combined with a JSON schema system that powers the visual Page Editor. As a developer, you have full control over markup, styles, logic, and content structure. This guide walks you through the key building blocks of a Fluid theme.

Theme File Structure

A Fluid theme is organized into directories by function. Each directory holds a specific type of file, and Fluid’s template resolver knows where to look for each one.

theme/
├── layouts/
│   └── theme.liquid
├── product/
│   └── default/
│       └── index.liquid
├── page/
│   └── about-us/
│       └── index.liquid
├── shop_page/
├── navbar/
├── footer/
├── sections/
│   └── hero/
│       └── index.liquid
├── blocks/
│   └── heading/
│       └── index.liquid
├── components/
├── assets/
│   └── theme.css
├── locales/
│   └── en.json
├── config/
│   ├── settings_schema.json
│   └── settings_data.json
├── cover.png
└── .fluid-theme.json

config/settings_schema.json declares the theme-wide settings and config/settings_data.json stores their values. See Root theme configuration.
All CSS lives in assets/. Reference it from layouts/theme.liquid or a template with {{ 'theme.css' | asset_url | stylesheet_tag }}, or inline a small file with {{ 'theme.css' | inline_asset_content }}. A per-template styles.css and a theme-root styles.css or global_styles.css are deprecated, and companies on the asset model reject them on push. The template-stylesheet-to-asset-migration skill from fluid theme skills install moves them for you.
cover.png is the theme’s preview image.
.fluid-theme.json is written by the CLI to record which theme and version you last pulled. Don’t edit it by hand.
A storefront Page’s template lives at page/<template-name>/index.liquid.

Layout File

The layouts/theme.liquid file is the outermost shell rendered for every page on your storefront. It contains the <html>, <head>, and <body> tags that wrap all page-specific content. Two special Liquid tags connect the layout to the rest of the theme:

{{ content_for_header }} — Outputs platform-injected metadata, scripts, and stylesheets into the <head>, including the page’s <title> and Open Graph tags. Always include this tag, and don’t add your own <title>.
{{ content_for_layout }} — Outputs the rendered content of the current page template between the <body> tags.

Here is a minimal layout example:

<!DOCTYPE html>
<html lang="{{ localization.language.iso_code }}">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    {{ content_for_header }}
  </head>
  <body>
    {% section 'navbar' %}

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

    {% section 'footer' %}
  </body>
</html>

Choose a layout for a template

Templates use layouts/theme.liquid by default. To use another layout, add the layout tag to the template and pass the layout name without the .liquid extension:

{% layout "custom" %}

<h1>{{ company.name }}</h1>

Fluid renders this template inside layouts/custom.liquid. To render the template without a layout, use none:

{% layout none %}

<!DOCTYPE html>
<html>
  <head>
    {{ content_for_header }}
  </head>
  <body>
    <h1>{{ company.name }}</h1>
  </body>
</html>

When you disable the layout, the template must provide any document structure and global markup it needs.

Template Files

Template files contain the page-specific Liquid markup rendered inside {{ content_for_layout }}. Each template type maps to a page category in Fluid:

Type	Description
`home_page`	Storefront home page
`shop_page`	Main shop listing page
`product`	Individual product detail pages
`collection`	A single collection
`collection_page`	The collections listing
`category`	A single category
`category_page`	The categories listing
`medium`	Media detail pages (videos, articles)
`library`	Playlist (library) pages
`post`	A single blog post
`post_page`	The blog listing
`page`	Storefront Pages created in the admin
`enrollment_pack`	Enrollment pack detail pages
`cart_page`	Shopping cart
`join_page`	Affiliate or member sign-up pages
`error_page`	The 404 and 503 error pages. See Error pages
`mysite`	A member’s MySite page, at `/my/<username>`. Each MySite theme is one `mysite` template with a body, `<head>` markup and a stylesheet. See MySite themes
`navbar`	Global navigation
`library_navbar`	Navigation shown on playlist pages
`footer`	Global footer

Member storefront themes add members_dashboard, members_page, and members_login. See Member page templates. sections/, blocks/, and components/ hold reusable pieces that templates render; they aren’t page types. Each template type can have multiple named templates stored as subdirectories — for example, product/default/ and product/featured/. Only one template per type is published and active at a time, but you can create and preview others before switching.

Add a template for every page type your store uses

Fluid routes each storefront URL to a template type, such as /home/posts/<slug> to post. If your theme has no template of that type, Fluid can’t render the page and shows your home page at that URL instead. It doesn’t return an error, so the page looks like it loaded. Run fluid theme lint to list the page types your theme has no template for. To fix it, add the missing template. Don’t work around it in layouts/theme.liquid with a redirect, a <meta http-equiv="refresh">, or JavaScript. For blog posts, that means two templates:

post/
└── default/
    └── index.liquid      # a single post: /home/posts/<slug> and /<username>/posts/<slug>
post_page/
└── default/
    └── index.liquid      # the blog listing: /home/blog and /<username>/blog

A post template reads the current post from post. See Post template. Open a post in fluid theme dev to check it renders the post rather than your home page, then push the new files with fluid theme push. If the theme already has an active template of that type, pushing another one doesn’t replace it. Edit the existing template instead.

Sections

Sections are the primary building blocks of Fluid pages. Each section is a self-contained Liquid file that pairs markup with a {% schema %} block defining its configurable settings. The schema powers the right panel of the visual Page Editor. Here is an example product header section:

<section class="product-header">
  <h1>{{ section.settings.heading | default: product.title }}</h1>

  {% if section.settings.show_price %}
    <p class="price">{{ product.price }}</p>
  {% endif %}

  {{ section.settings.image | media_tag: width: 800, alt: section.settings.image_alt }}
</section>

{% schema %}
{
  "name": "Product Header",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Custom Heading",
      "info": "Leave blank to use the product title"
    },
    {
      "type": "checkbox",
      "id": "show_price",
      "label": "Show Price",
      "default": true
    },
    {
      "type": "image_picker",
      "id": "image",
      "label": "Override Image"
    }
  ],
  "presets": [
    {
      "name": "Product Header",
      "settings": {
        "show_price": true
      }
    }
  ]
}
{% endschema %}

Blocks

Blocks are repeatable content items defined within a section’s schema. They allow editors to add, remove, and reorder dynamic items — like testimonial cards, feature bullets, or image slides — without touching code. Define blocks in the schema and render them in Liquid using section.blocks:

{
  "name": "Testimonials",
  "blocks": [
    {
      "type": "testimonial",
      "name": "Testimonial",
      "limit": 6,
      "settings": [
        {
          "type": "textarea",
          "id": "quote",
          "label": "Quote"
        },
        {
          "type": "text",
          "id": "author",
          "label": "Author Name"
        }
      ]
    }
  ]
}

<div class="testimonials">
  {% for block in section.blocks %}
    {% if block.type == 'testimonial' %}
      <blockquote {{ block.fluid_attributes }}>
        <div>{{ block.settings.quote }}</div>
        <cite>{{ block.settings.author }}</cite>
      </blockquote>
    {% endif %}
  {% endfor %}
</div>

Output {{ block.fluid_attributes }} on each block’s outer element so the Page Editor can select it. Fluid adds the equivalent attributes to each section’s wrapper for you. For standalone blocks with their own files, see Blocks and components.

Assets

Store images, fonts, stylesheets, and scripts in the assets/ directory. Reference any asset in Liquid using the asset_url filter:

<link rel="stylesheet" href="{{ 'main.css' | asset_url }}" />
<img src="{{ 'logo.png' | asset_url }}" alt="{{ company.name }}" />
<script src="{{ 'storefront.js' | asset_url }}"></script>

Fluid distinguishes between two types of assets:

Binary assets — Images, fonts, and other files served as-is (e.g. .png, .jpg, .woff2)
Non-binary assets — CSS and JavaScript files that can be edited directly in the CLI or Code Mode

All assets are served via Fluid’s CDN, so the asset_url filter always resolves to the correct CDN URL regardless of environment.

Localization

Fluid’s translation system uses JSON locale files stored in locales/. Each file corresponds to a language (e.g. locales/en.json, locales/es.json) and contains a nested key-value structure.

{
  "products": {
    "add_to_cart": "Add to Cart",
    "sold_out": "Sold Out",
    "from_price": "From {{ price }}"
  },
  "general": {
    "learn_more": "Learn More"
  }
}

Reference any locale key in Liquid using the | t filter:

<button>{{ 'products.add_to_cart' | t }}</button>
<a href="{{ product.url }}">{{ 'general.learn_more' | t }}</a>

When a visitor’s language is set, Fluid automatically resolves | t to the correct locale file. If a key is missing in a non-English locale, Fluid falls back to the English value. When no locale file defines a key, t prints “Translation missing” text. Add default: straight after t to show your own text instead, such as {{ 'products.sold_out' | t | default: 'Sold out' }}. Pass values to fill placeholders, such as {{ 'products.from_price' | t: price: product.price }}. A key whose value is an object with one and other entries is pluralized by the count you pass.

Available Liquid Filters

Fluid supports the standard Liquid filters, such as date, truncate, and join, and adds these:

Filter	Purpose
`asset_url`	Resolve a filename in `assets/` to its full CDN URL
`media_tag`	Render an image or video value as responsive markup. See Media tag
`image_url`	Request a resized ImageKit rendition, such as `image_url: width: 600`. See Image transformations
`t`	Look up a translation key in the active locale file
`json`	Serialize a value as JSON, for example inside a `<script>`
`member_price`	Render a product or variant price as a member-aware shell that the member storefront SDK resolves for a signed-in member. See Member-aware sections

Prices such as product.price are already formatted for the visitor’s currency, so output them directly. Fluid has no money filter. For pushing your finished theme to Fluid or setting up a local development workflow, see the Fluid CLI guide. For theme-wide settings, see root theme configuration. When you add navigation, use the canonical patterns in supported storefront paths.

Start here

Building blocks

Storefront features

Advanced

Member storefront

Developer Guide: Building and Customizing Fluid Themes

Theme File Structure

Layout File

Choose a layout for a template

Template Files

Add a template for every page type your store uses

Sections

Blocks

Assets

Localization

Available Liquid Filters

​Theme File Structure

​Layout File

​Choose a layout for a template

​Template Files

​Add a template for every page type your store uses

​Sections

​Blocks

​Assets

​Localization

​Available Liquid Filters

Theme File Structure

Layout File

Choose a layout for a template

Template Files

Add a template for every page type your store uses

Sections

Blocks

Assets

Localization

Available Liquid Filters