Learning Liquid

Understanding Shopify’s Liquid is imperative to implementing Metafields in your theme. Liquid is the template language your theme is written in, and it is how the values you enter in Accentuate Custom Fields end up on the storefront.

Shopify has a great selection of articles with technical tips, Liquid language resources, beginner how-tos, and a collection of useful code examples that you may use for inspiration.

---

Reference material

• Liquid reference - the complete, authoritative reference for Shopify’s Liquid.
• Liquid basics - the syntax itself: tags, filters, objects, operators and whitespace control.
• Tags, Filters and Objects - the three building blocks, each with its own index.
• Learning Liquid on the Shopify blog - beginner how-tos and longer-form tutorials.
• Liquid code examples - short, copy-and-paste examples for common storefront tasks.
• Shopify cheat sheet - a one-page summary of the most used Liquid objects and filters.

---

What has changed in Liquid

Liquid has moved on quite a bit since metafields were first introduced, and several of the changes matter directly for how you display Accentuate fields. The sections below cover the ones worth knowing about. Shopify tracks everything else in the developer changelog, which can be filtered down to the Liquid entries.

Metafields are objects, not plain values

A metafield of a modern Shopify type is a metafield object rather than a bare string. The data lives on its value property, and the object also exposes type and list?:

{{ product.metafields.accentuate.subtitle.value }}

For reference types - file, product, collection, page or metaobject references - value is the referenced object itself, so you keep drilling into it:

{% assign spec_sheet = product.metafields.accentuate.spec_sheet.value %}
<a href="{{ spec_sheet.url }}">Download the spec sheet</a>

For list types, value is the array you iterate over. Reference lists carry a count property, while text lists are measured with the size filter:

{% for author in product.metafields.accentuate.authors.value %}
  <p>{{ author.name }}</p>
{% endfor %}

Note

The older integer, json_string and string metafield types are deprecated and do not behave like this - they return their value directly and have none of the metafield object properties. That is why some of the examples elsewhere in these guides output a field without .value. When in doubt, .value is the safe default for anything created against a current Shopify type.

One gotcha worth remembering: if a field’s key is size, first or last, dot notation collides with the built-in Liquid filters of the same name. Use square brackets instead:

{{ product.metafields.accentuate["size"].value }}

Metafield filters

Two filters render a metafield without you having to branch on its type yourself:

• metafield_tag - outputs a complete HTML element appropriate to the metafield’s type.
• metafield_text - outputs the plain-text version of the value.

{{ product.metafields.accentuate.care_instructions | metafield_tag }}

Both now understand metaobject references, so you can pull a single field out of a referenced entry:

{{ product.metafields.accentuate.authors | metafield_text: field: "name" }}

Neither filter supports list metafields other than list.single_line_text_field and list.metaobject_reference - for any other list, loop over value yourself.

Metaobjects on the storefront

Metaobject entries are reachable from anywhere in the theme through the global metaobjects object, addressed by definition type and entry handle:

{{ metaobjects.testimonials.homepage.title }}

Entries also carry a system property holding their id, handle, type and URL, kept separate so it can never collide with your own field names. If the definition has the publishable capability enabled, only active entries resolve - draft entries return nil.

Definitions that publish entries as web pages get their own metaobject template at templates/metaobject/{type}.json, where the current entry is available as the metaobject object. See Displaying metaobjects on your storefront for how this fits together with Accentuate.

Theme blocks and the content_for tag

Theme blocks live in the theme’s /blocks folder, can be reused across sections and nested inside one another. They are rendered with the content_for tag, which comes in two forms:

{% comment %} A merchant-configurable region, filled from the theme editor {% endcomment %}
{% content_for 'blocks' %}

{% comment %} A single static block, with arguments passed in {% endcomment %}
{% content_for 'block', type: "slide", id: "slide-1", color: "red" %}

This is the modern way to build a section that a merchant can rearrange, and it is where custom field output usually belongs in a current theme.

LiquidDoc

Since May 2025, snippets and blocks can document their own interface with the {% doc %} tag. Editors and theme tooling read these annotations to give you parameter validation, type checking and hover documentation:

{% doc %}
  @description Renders a labelled Accentuate field value.
  @param {object} field - The metafield object to render.
  @param {string} [label] - Optional label shown before the value.
  @example
  {% render 'acf-field', field: product.metafields.accentuate.size, label: 'Size' %}
{% enddoc %}

The full annotation list is in the LiquidDoc guide.

Other additions worth knowing

• The {% liquid %} tag lets you write a run of statements inside a single set of delimiters, which makes long blocks of field logic far easier to read.
• image_url combined with image_tag replaces the deprecated img_url filter. See Resize & crop images for how this applies to Accentuate media fields.
• unit_price_with_measurement (June 2025) formats unit prices in the customer’s language. Unit prices apply to stores in the EU and Switzerland.
• In developer preview since July 2026, the {% block %} and {% partial %} tags let a Liquid template compose a page directly - block renders a theme block from a template with arguments, and partial marks a server-rendered region that JavaScript can refresh without a full page load. Existing themes built on sections and JSON templates keep working unchanged. Details are in the changelog entry.

---

Tooling

• Theme Check - a linter for Liquid that catches syntax errors, schema problems and mismatched arguments before they reach the storefront.
• Shopify Dev MCP - since October 2025 it can search the full Liquid API reference and validate Liquid through Theme Check, which is useful if you write your theme code with an AI assistant.

---

Where to go next in these guides

• Access field definitions - read your ACF definitions (labels, order, sections) from Liquid.
• Check for empty values - the correct blank tests for single, multi-language and repeatable fields.
• Resize & crop images - serving the right image size from a media field.