HTML + Liquid reference

A site is plain HTML files with Liquid for data. Every write is linted (errors come back with a source range: fix them in place), sanitized and stored as a new draft version. Nothing is live until publish_site.

Files

theme.css variables

Editor attributes

The editor's own attributes. All are stripped from the published page.

Editing rules

• Read a file before editing it, and change the smallest span (edit_site_file with an exact oldText). Keep every data-edit-* attribute you didn't mean to remove: they are the element ids history and comments use.
• Liquid in an attribute value is fine, tags too (as on Shopify): class="tab {% if on %}tab-on{% endif %}". Never in the attribute list: wrap the whole element in the {% if %} instead.
• Well-formed HTML only: close every element you open.
• Output is escaped. | raw only after a filter that returns trusted HTML (icon, image_tag) or a rich-text field.
• Follow the site's existing conventions: read a neighbouring page or partial first and reuse its classes and structure.
• Behaviour is native HTML or a runtime attribute below first. When those don't cover it, a site may carry its own JavaScript and nothing is stripped: see Site JavaScript.

Gated actions

The one exception (the editor's "only fire when"): ONE {% if <condition> %}…{% endif %} in the open tag, so the action exists only while the condition holds.

• Inside it only data-* and the native action attributes (href, target, rel, command, commandfor, action, download).
• No {% else %} / {% elsif %}, other Liquid tag, class, data-edit-* or javascript:.

<button class="btn" {% if customer %}data-cart="add" data-cart-id="tee-1"{% endif %}>Buy</button>

Styling

On a Tailwind + DaisyUI site (the default). select_site and list_site_files print the site's Styling: line: on tailwind DaisyUI classes such as btn and card have no CSS, on own-css reuse the classes the site's own CSS defines.

• Colours: palette tokens only (bg-primary, text-base-content, bg-base-200).
• Spacing: spatial tokens (py-space-lg, gap-space-sm, px-container-x, scale 3xs…4xl). They scale with the screen, so no md:py-*.
• Width, type: max-w-page for page width, font-heading / font-body.
• Layers: fixed headers z-[1100], dialogs z-[1200].

Media and icons

• {{ '<mediaId>' | image_url: width: 800 }} is the URL; {{ '<mediaId>' | image_url: width: 800 | image_tag: alt: '…' }} an <img>. image_tag takes a URL: a bare id gives a broken image. width, height, crop, format size the file (CSS url() too).
• upload_image gives the id. Files: {{ '<mediaId>' | file_url }}.
• Icons: {{ 'tb/TbPhone' | icon }} (find_icon).

Behaviour: native HTML first

commandfor anywhere

• commandfor + command also work on a NON-button (a gallery tile, a card): a click on it or on anything inside it runs the command (show-popover, hide-popover, toggle-popover, show-modal, close).
• An overlay whose commandfor names ITSELF closes only on a click that lands on it, its backdrop, never on one bubbling up from its panel.
• An element with content INSIDE the overlay it names (a drawer or modal panel carrying its overlay's command) never acts, so a click on blank panel space doesn't close it.
• A childless one (a click-away strip beside a drawer) is a backdrop and acts.

<div commandfor="viewer" command="show-popover" class="cursor-zoom-in">
  <img src="a.jpg" alt="Kitchen">
</div>

Classes: variants and modifiers

Variants stack in this order, which is how the editor reads and writes them: breakpoint, dark:, state. So md:dark:hover:bg-primary is one class.

The device condition is two classes: md:hidden shows the element on phones only, max-md:hidden on desktop only.

<a class="group">
  <span class="opacity-0 group-hover:opacity-100">Open</span>
</a>

Modifiers

Classes the site runtime styles. Give an element ONE interaction modifier (the editor's inspector picks one): grow, lift and press all set transform, so stacked they fight, and glow breaks grow's transition. State modifiers stack freely.

<button class="btn ph-mod-lift" data-state-class="tab=a=>ph-mod-tab-active">A</button>

Runtime attributes

Declarative behaviour from the site runtime, no script to write. Every name here is read by the runtime.

• On the editor canvas the author-behaviour ones stay off, so a click selects instead of acting: copy, dismiss, theme toggle, the click helpers, the lightbox, data-on, form submit, tracking, chat, data-show-on, data-refetch swaps.
• The preview and the live site run them.

Cart

Add to the cart, open it and check out.

<input name="qty" type="number" value="1">
<button data-cart="add" data-cart-id="tee-1" data-cart-qty-field="qty">Add</button>

Forms and lists

Submit filter forms as the visitor types, and swap a listing's rows without a reload.

<button data-state-set="url:category:tees">Tees</button>
<div id="grid" data-refetch="category,page">
  …rows…
</div>

Motion

data-animate="fade-up" animates an element as it scrolls into view. Anything already on screen when the page opens stays as it is (no hide-and-replay flash), so a plain data-animate on the hero does nothing.

• Timing is classes on that element: [--anim-duration:0.8s], [--anim-delay:0.2s], [--anim-easing:ease-in-out], [--anim-iteration:2] (or infinite).

Fit text

data-fit-text sets the largest font size that fits. data-fit-min / data-fit-max are the limits in px (4 and 512).

<h2 class="w-full" data-fit-text="oneline" data-fit-max="160">Built to be found.</h2>

Overflow

On a scroller. Each attribute works on its own.

<div class="flex gap-space-sm overflow-x-auto" data-drag-scroll data-scrollbar-autohide="1500ms">
  …
</div>

Scroll effect

data-scroll-effect="horizontal" pins a section and pans its track sideways as the page scrolls. The section's first child is the pin, and the pin's first child the track.

• data-scroll-effect="timeline" sets --scroll-progress (0 to 1) on the section for your CSS instead.
• Reduced motion: no pin, a plain sideways scroll.

<section data-scroll-effect="horizontal" data-scroll-runway="3">
  <div>
    <div class="flex w-max gap-space-md">…panels…</div>
  </div>
</section>

Carousel

Turns a scroll-snap track into a carousel.

<div data-carousel="dots arrows wrap" class="flex snap-x snap-mandatory overflow-x-auto">
  <img src="a.jpg" alt="">
  <img src="b.jpg" alt="">
</div>

<div class="relative">
  <button data-carousel-prev aria-label="Previous">‹</button>
  <div data-carousel="wrap" class="flex snap-x overflow-x-auto">…slides…</div>
  <button data-carousel-next aria-label="Next">›</button>
</div>

Show / hide

Opens a target on load or hover, where commandfor only covers clicks.

<div id="cookie" popover="manual" data-show-on="load" data-show-dir="show" data-show-if="!ls:seen">
  <button commandfor="cookie" command="hide-popover" data-state-set="ls:seen:1">OK</button>
</div>

Tabs

Tabs without radio inputs.

• A tab with aria-expanded keeps it in step.

<button data-tab-target="p1" data-tab-of="plans">Monthly</button>
<div id="p1" data-tab-group="plans">…</div>
<div id="p2" data-tab-group="plans" class="hidden">…</div>

Click helpers

Small things a click does.

Photo lightbox

A photo viewer over a grid. The overlay is a popover="manual" (or <dialog>) with an <img>.

<div id="grid">
  <div data-lightbox="viewer" data-lightbox-caption="cap" commandfor="viewer" command="show-popover">
    <img src="a.jpg" alt="Kitchen">
  </div>
</div>
<div id="viewer" popover="manual" data-idx="0">
  <img src="" alt="">
  <p id="cap"></p>
  <button data-lightbox="viewer" data-lightbox-step="-1" data-lightbox-grid="grid">Previous</button>
</div>

State

Named keys that markup sets and reads.

<span data-state-step="slide:1" data-min="1" data-max="3" data-wrap data-state-on="interval" data-every="4s"></span>

State views

They read keys with one test: key, !key, key=v, key!=v, key*=v (contains), key>3 (<, >=, <=), joined by && and || (&& binds tighter).

<button data-state-set="tab:pricing">Pricing</button>
<div data-state-show="tab=pricing" hidden>…</div>

State writers

They write keys for the views to read.

Other

Copy, dismiss and prerender.

Tracking

data-track="ga4:signup" on a link, button or form fires on click or submit.

• The provider's script must be on the page: ids via set_integrations, Plausible's snippet in site.json inject. An unknown provider does nothing.

Purchase events

data-track-purchase (+ data-id, data-value in minor units, data-currency) on a hidden element of an order confirmation page sends gtag purchase and fbq Purchase, once per order and browser. ="lead" sends generate_lead only, for a held request. Sends nothing without a tag; never put guest details on it.

{% if item.paid %}<div hidden data-track-purchase data-id="{{ item.id }}" data-value="{{ item.totalMinor }}" data-currency="{{ item.currency }}"></div>{% endif %}

Theme toggle

data-theme-toggle flips light and dark and remembers it. It needs a dark palette (set_theme darkPalette); it sets data-theme on <html>, so swap the icon with [[data-theme=dark]_&]:hidden.

<button type="button" data-theme-toggle aria-label="Switch theme">
  <span class="[[data-theme=dark]_&]:hidden">{{ 'tb/TbSun' | icon }}</span>
  <span class="hidden [[data-theme=dark]_&]:inline">{{ 'tb/TbMoon' | icon }}</span>
</button>

Scrollspy

data-scrollspy on a nav sets aria-current="true" on the link whose #id section is most in view (here a <section id="pricing"> elsewhere on the page).

<nav data-scrollspy>
  <a class="aria-[current=true]:text-primary" href="#pricing">Pricing</a>
</nav>

Site chat

The chat widget. Settings: set_site_chat; start from the site-chat-bubble block.

Your own functions

data-on="click:openChat; mouseenter:peek.once" calls a function the site's JavaScript registers (see Site JavaScript).

Site JavaScript

Native HTML and the runtime attributes above are the default. When a site needs behaviour they don't give, it may carry its own JavaScript, and nothing is stripped.

• It runs on the preview and the live site, never on the editor canvas; check it with the preview link or screenshot_site.
• The in-app PageHub AI and the catalogs (library blocks, templates) never carry JavaScript: it is refused or stripped there.
• Third-party vendor snippets (tracking, chat loaders) belong in site.json inject; analytics ids in set_integrations.

Inline

An on* attribute, or a <script>…</script> in a page, partial or section.

<button type="button" onclick="document.getElementById('promo').remove()">Hide</button>

A section's or partial's own script

• The body is raw (no Liquid inside).
• Each distinct block is added once per page, in one <script data-ph-javascript> before </body>.
• Each runs in its own function and try, so one block's error doesn't stop another.

{% javascript %}
  document.querySelectorAll('[data-year]').forEach(function (el) {
    el.textContent = new Date().getFullYear();
  });
{% endjavascript %}

A file

Write assets/app.js (write_site_file), then link it:

<script src="{{ 'app.js' | asset_url }}" defer></script>

• The URL carries the file's content hash, so a changed file is a new URL.
• The editor's Scripts panel lists these files; "load on every page" adds the file to partials/site-scripts.liquid, which each page renders.

Functions for data-on

data-on="click:openChat" calls a function registered by name:

window.PageHub = window.PageHub || { fns: {}, on: function (n, f) { this.fns[n] = f; } };
PageHub.on("openChat", function (event, el) { … });

• The PageHub global may not exist yet when your script runs, so create it first (the first line).
• An option after the name (openChat.once, .passive, .capture, .prevent) sets the listener.
• An unregistered name is a console warning, never code evaluation.

Lists from the URL

{% assign list = query["articles?limit=6&in=q,page,category"] %}
{% assign meta = query_meta["articles?limit=6&in=q,page,category"] %}
{% assign cats = collections.articles | facets: 'category' | first %}
<form method="get" data-autosubmit="300ms"><input type="search" name="q" value="{{ request.query.q }}" aria-label="Search"></form>
{% for v in cats.metadata.values %}<a href="?category={{ v.value | url_encode }}">{{ v.value }} ({{ v.count }})</a>{% endfor %}
<p>{{ meta.totalCount }} results, page {{ meta.page }} of {{ meta.totalPages }}</p>
{% for item in list %}<h3>{{ item.title }}</h3>{% else %}<p>Nothing matches.</p>{% endfor %}
{% for i in (1..meta.totalPages) %}<a href="?page={{ i }}">{{ i }}</a>{% endfor %}

• query["<collection>?<options>"] is the rows for THIS visitor's URL.
• query_meta["<same key>"] is their paging: totalCount, totalPages, page, hasMore. Write the key identically in both.
• Don't name a URL param size, first or last: request.query.size is Liquid's own count of the params, always truthy.

For a swap without a reload, give the list container an id and data-refetch="q,category", and drive the keys with data-state-bind="url:q" / data-state-set="url:category:tees".

Paging a whole collection

default_pagination takes previous: '‹' and next: '›'; or build links from paginate.previous.url, paginate.next.url, paginate.current_page, paginate.pages, paginate.items. Pages use ?page=, and the links keep the rest of the query.

{% paginate collections.articles by 6 %}
  {% for item in collections.articles %}…{% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}

Facets

rows | facets: 'category,size' counts over the rows you give it; collections['articles.facets'] and collections['articles.categories'] are the stored feeds. A facet row is { title, metadata: { key, values: [{ value, count }] } }.

Keeping a filtered list editable in the builder

The Data source panel reads and writes exactly this shape. A URL filter of any other shape renders fine but the builder doesn't see it.

1. ONE {% assign v = collections.<slug> | where: 'field', 'value' | sort: 'field' %} (only where, split and sort with quoted literals, or a bare {% assign v = collections.<slug> %}; any other filter is lost when the panel rewrites the line).
2. One line per URL filter, EXACTLY {% if request.query.color and request.query.color != '' %}{% assign v = v | where: 'colors', request.query.color %}{% endif %}. where also matches a list field that contains the value.
3. Optionally {% paginate v by 12 %} with the loop as its first child, {% for item in v limit: 12 %}<article>…</article>{% endfor %}, the nav and {% endpaginate %}. The for reads v, the same name the assigns use.

Conditions the builder can edit

A server condition is ONE {% if %}…{% endif %} around one element, with no {% else %}, whose terms are all joined by and or all by or.

{% if request.query.ref == 'ad' and company.phone != blank %}
  <a class="btn" href="tel:{{ company.phone }}">Call</a>
{% endif %}

Mixed and / or, brackets, filters, >=, not, a variable on the right, unless, elsif and else all render but stay raw Liquid text in the builder. A state, storage or form-field test is data-state-show, not Liquid.

Sections

A section is a reusable file with its own settings. sections/feature-card.liquid, used as {% section 'feature-card', headline: "Reliable" %}:

<div class="rounded-box bg-base-200 text-base-content p-space-sm">
  <h3 class="font-heading font-semibold">{{ section.settings.headline }}</h3>
</div>
{% schema %}
{ "name": "Feature card", "settings": [{ "type": "text", "id": "headline", "label": "Headline", "default": "Fast" }] }
{% endschema %}

• A section is isolated: it sees site, page, request and the data globals, not the page's assigns.
• section.settings is the schema's defaults overlaid with the tag's arguments.
• Setting types are Shopify's: text, textarea, richtext, number, checkbox, select, color, image_picker, url, …
• An argument of the wrong type or with no matching id is ignored, and lint reports it.

Forms

{% form 'contact', to: 'owner@example.com', webhook: 'https://example.com/hooks/leads' %}…{% endform %} posts to the inbox or collection named contact. A form needs no JavaScript to post.

• Arguments are literal strings (never {{ }}), read at publish: the address and webhook URL never appear in the page, and a crafted request can't choose them.

Leave redirect out and the post returns to the same page with its outcome, shown once. Inside the form:

{% form 'contact', to: 'owner@example.com', redirect: '/thanks' %}
  <label for="email">Email</label>
  <input id="email" name="email" type="email" autocomplete="email" required class="border border-base-300 bg-base-100 rounded-box px-space-sm py-space-xs">
  <button type="submit" class="btn btn-primary">Send</button>
{% endform %}

Staying on the page (no redirect):

{% form 'leads', map: 'name=name,email=email' %}
  {% if form.posted_successfully? %}
    <p>Thanks, you are on the list.</p>
  {% else %}
    {% if form.errors %}<div class="text-error">{{ form.errors | default_errors }}</div>{% endif %}
    <input name="name" value="{{ form.values.name }}">
    <input name="email" type="text" inputmode="email" value="{{ form.values.email }}">
    <button type="submit" class="btn btn-primary">Join</button>
  {% endif %}
{% endform %}

Webhooks

Every submission is POSTed as JSON { event: "form_submission", submissionId, site, formName, pagePath, submittedAt, data, attribution }.

• Signature: X-PageHub-Timestamp and X-PageHub-Signature: sha256=<hex>, an HMAC-SHA256 of <timestamp>.<raw body> keyed by the destination's signing secret (made on first delivery; set or rotate it from the form submissions screen, "Webhook signing").
• Retries: a 2xx is delivered; 5xx, 429 and network errors retry up to 6 attempts (waits of 1 min, 5 min, 30 min, 2 h, 12 h); any other status fails with no retry.
• Duplicates: the timestamp and signature are fresh on each attempt, the body and submissionId don't change, so receivers dedupe on submissionId.
• Each submission records its delivery (delivered, retrying, failed) and the owner can Resend it.

Attribution

The runtime remembers how a visitor arrived, for the session, and posts it with every PageHub form as the reserved hidden field _ph_attribution. Don't name a field _ph_attribution.

• What it remembers: utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, landing path, referrer.
• Where it shows: "Where they came from" on the submission, and attribution in the webhook.

Dates and time

Dates render in the site's timezone (update_site timezone, an IANA name such as America/Los_Angeles), never the server's; unset means UTC. {{ site.timezone }} prints it.

• {{ post.date | date: '%B %d, %Y' }} formats a date.
• {{ post.date | time_tag: '%B %d, %Y' }} is a <time datetime> element.
• {{ 'now' | date: '%Y' }} and {{ year }} are the current year.
• A date-only string (2026-06-15) keeps its day in every zone.
• A date-time with no offset (2026-06-15T10:00) is wall-clock time in the site's timezone (it prints 10:00 whatever the server's zone); add an offset (Z, -07:00) to name an exact instant.

Maps

{% map %} draws a map from its children: an <address data-pin> is a pin, a <span data-route> a route. Without JavaScript the children are a readable list.

{% map lat: 34.05, lng: -118.24, zoom: 14, tiles: 'osm' %}
  <address data-pin="34.05,-118.24"><strong>Shop</strong> 1 Main St</address>
  <span data-route="34.05,-118.24; 34.06,-118.25 dashed">Walk from the lot</span>
{% endmap %}

• Route words after the points: dashed, color red, weight 4.
• A route can instead carry attributes: <span data-path="34.05,-118.24,1; 34.06,-118.25,2" data-color="royalblue" data-weight="5" data-opacity="0.85" data-dashed>Walk from the lot</span> (a third ,label field draws a step badge; the text is the caption).

Core Liquid

Output is already escaped, and | escape encodes once (it never double-escapes). No and/or grouping with parentheses: nest {% if %} instead.

PageHub tags

PageHub filters

Objects and data

Lint rules (a write that breaks one is refused)