Liquid filters

This reference documents all custom Liquid filters available in Basker themes. These filters extend the standard LiquidJS filter set with CMS-specific functionality for asset URLs, image transforms, string handling, and data queries.

Standard LiquidJS filters (append, capitalize, date, default, downcase, escape, join, map, replace, size, slice, sort, split, strip, truncate, upcase, where, etc.) are not covered here. See the LiquidJS documentation for those.

asset_url

Type: Asset Returns: String (URL)

Builds a theme asset URL with cache-busting version parameters. The URL points to the theme's assets/ directory on the CDN.

Syntax

{{ "<filename>" | asset_url }}

Parameters

Example

{{ "theme.css" | asset_url }}

Output

https://cdn.example.com/files/theme-key/assets/theme.css?v=theme-key&c=abc123

The v parameter is the theme key and the c parameter is the theme version hash. Both enable cache busting when the theme is updated.

See also

• absolute_asset_url
• stylesheet_tag

absolute_asset_url

Type: Asset Returns: String (URL)

Builds an absolute theme asset URL with cache-busting version parameters. Functionally equivalent to asset_url -- both produce absolute URLs when the CDN is configured.

Syntax

{{ "<filename>" | absolute_asset_url }}

Parameters

Example

{{ "logo.svg" | absolute_asset_url }}

Output

https://cdn.example.com/files/theme-key/assets/logo.svg?v=theme-key&c=abc123

See also

• asset_url

stylesheet_tag

Type: Asset Returns: String (HTML)

Wraps a URL in a <link> tag for loading a CSS stylesheet.

Syntax

{{ <url> | stylesheet_tag }}

Parameters

Example

{{ "theme.css" | asset_url | stylesheet_tag }}

Output

<link href="https://cdn.example.com/files/theme-key/assets/theme.css?v=theme-key&c=abc123" rel="stylesheet" type="text/css" media="all" />

Chain with asset_url to build the full URL before wrapping in the tag.

See also

• asset_url
• script_tag

script_tag

Type: Asset Returns: String (HTML)

Wraps a filename in a <script> tag. The filter builds the full asset URL internally, so pass the raw filename rather than a pre-built URL.

Syntax

{{ "<filename>" | script_tag }}

Parameters

Example

{{ "app.js" | script_tag }}

Output

<script src="https://cdn.example.com/files/theme-key/assets/app.js?v=theme-key&c=abc123" type="text/javascript"></script>

Unlike stylesheet_tag, this filter builds the asset URL automatically. Pass the filename directly, not a URL.

See also

• stylesheet_tag
• asset_url

img_url

Type: Media Returns: String (URL)

Generates an image URL, optionally using a predefined size variant. Accepts image objects (with src or url properties), raw URL strings, or objects with predefined sizes.

Syntax

{{ <image> | img_url }}
{{ <image> | img_url: "<size_slug>" }}
{{ <image> | img_url: size: "<size_slug>" }}

Parameters

Example

Using a predefined size:

{{ event.image | img_url: "thumbnail" }}

Without a size (returns the original URL):

{{ post.image | img_url }}

Using named parameter syntax:

{{ person.headshot | img_url: size: "medium" }}

Output

https://media.example.com/images/event-hero-thumbnail.jpg

If the image object has a sizes property with matching entries, the predefined size URL is returned. Otherwise, the src or url property of the image object is used.

See also

• image_url
• file_url

image_url

Type: Media Returns: String (URL)

Generates an image URL with transform parameters for width, height, fit mode, and focal point. Provides more control than img_url for responsive image generation.

Syntax

{{ <image> | image_url: width: <w>, height: <h>, fit: "<mode>" }}

Parameters

Example

Resize to a specific width:

{{ page.image | image_url: width: 800 }}

Resize with fit mode:

{{ event.image | image_url: width: 1200, height: 630, fit: "cover" }}

Override focal points:

{{ person.headshot | image_url: width: 400, height: 400, fit: "cover", focalX: 50, focalY: 30 }}

Output

https://media.example.com/images/event-hero.jpg?w=1200&h=630&f=cover

With focal points:

https://media.example.com/images/person-headshot.jpg?w=400&h=400&f=cover&fx=50&fy=30

When the image object has focalX and focalY properties (set via the CMS media editor), those values are automatically appended unless explicitly overridden.

See also

• img_url
• file_url

file_url

Type: Media Returns: String (URL)

Generates a URL for a file or media object. Accepts file objects (with src or url properties) or raw URL strings.

Syntax

{{ <file> | file_url }}

Parameters

Example

<a href="{{ resource.programme_pdf | file_url }}" download>Download Programme (PDF)</a>

From a string:

{{ "/uploads/brochure.pdf" | file_url }}

Output

https://media.example.com/uploads/brochure.pdf

Returns an empty string if the input is null or empty.

See also

• img_url
• image_url

handleize

Type: String Returns: String

Converts a string to a URL-safe slug (handle). Lowercases the string, keeps letters, digits, underscores, and accented Latin characters, and replaces every other run of characters with a single hyphen, then trims leading/trailing hyphens. Non-Latin scripts (Cyrillic, Greek, CJK, and similar) are stripped rather than preserved, which can produce an empty handle.

Syntax

{{ "<text>" | handleize }}

Parameters

Example

{{ "Remarkable Theatre 2030" | handleize }}

Output

remarkable-theatre-2030

More examples:

See also

• handle

handle

Type: String Returns: String

Alias for handleize. Converts a string to a URL-safe slug.

Syntax

{{ "<text>" | handle }}

Parameters

Example

{{ "Moonclock Gala" | handle }}

Output

moonclock-gala

See also

• handleize

money

Type: Formatting Returns: String

Formats a number as a currency string. The input is treated as a value in cents (hundredths) and divided by 100. The output is prefixed with a dollar sign.

Syntax

{{ <amount_in_cents> | money }}

Parameters

Example

{{ 2500 | money }}

Output

$25

More examples:

Returns the original value unchanged if it cannot be parsed as a number.

See also

• N/A

t

Type: Translation Returns: String

Looks up a translation key for the active language and returns the translated string. Used to translate interface text the theme itself supplies. Translations live in locales/<language>.json files in the theme.

Syntax

{{ "<key>" | t }}

Parameters

Example

{{ "event.read_more" | t }}

With locales/cy.json containing { "event.read_more": "Darllen mwy" }, this renders Darllen mwy when the active language is Welsh.

Output

Read more

Resolution falls back from the active language to the default language, then to any other configured language. If the key is not found in any file, the key itself is returned unchanged, so untranslated strings appear verbatim on the page and are easy to spot.

See also

• Localization -- translation files, locale-aware links, and a language switcher

md5

Type: Hash Returns: String

Generates an MD5 hash of the input string. Useful for generating Gravatar URLs or cache keys.

Syntax

{{ "<text>" | md5 }}

Parameters

Example

{{ "developer@remarkable-theatre.example" | md5 }}

Output

01f938460108b4f223c36f18c238c05b

Gravatar usage:

<img src="https://www.gravatar.com/avatar/{{ person.email | md5 }}?s=200" alt="{{ person.title }}">

See also

• sha1

sha1

Type: Hash Returns: String

Generates a SHA1 hash of the input string.

Syntax

{{ "<text>" | sha1 }}

Parameters

Example

{{ "verification-token" | sha1 }}

Output

2275f8d2b37d2740b4149848266c4aa15df62a7b

See also

• md5

collection

Type: Data (async) Returns: Array

Finds documents in a collection whose normal field or custom attribute matches a value. Use field for a built-in field and attribute for a custom attribute.

{% assign venue_events = event.venue.id | collection: "events", field: "venue", limit: 6 %}
{% assign genre_events = event.attributes.custom.genre | collection: "events", attribute: "genre", limit: 6 %}

Optional named arguments are limit, page, depth, sort, and locale. The filter returns an empty array when the collection, field, or value cannot be resolved.

related_posts

Type: Data (async) Returns: Array

Returns other posts that share tags, categories, or both with the input post. The first argument is "tags", "categories", or "both"; the second is the maximum number of posts. The default matching mode is both.

{% assign related = post | related_posts: "both", 4 %}
{% for item in related %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

custom_attribute_relations

Type: Data (async) Returns: Array

Queries documents that share a custom attribute relationship. This filter is asynchronous and returns an array of related documents.

Syntax

{{ <collection_or_input> | custom_attribute_relations: attribute: "<attribute_name>", value: <relation_value> }}

Parameters

Example

Find all events with the same genre as the current event:

{% assign related = "events" | custom_attribute_relations: attribute: "genreName", value: event.genre, limit: 6 %}
{% for item in related %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

Query works by a specific attribute:

{% assign classical_works = "works" | custom_attribute_relations: attribute: "period", value: "Classical", limit: 10, sort: "title" %}
<ul>
  {% for work in classical_works %}
    <li><a href="{{ work.url }}">{{ work.title }}</a></li>
  {% endfor %}
</ul>

Output

Returns an array of document objects matching the attribute relationship query. Returns an empty array if no matches are found, if the attribute name is empty, or if the resolver is not available.

See also

• N/A

tenant

Type: Data (async) Returns: Collection drop or empty array

Scopes a collection drop to a site identified by its slug. This is intended for sites configured to share public content.

{% assign partner_events = all_events | tenant: "partner-site" %}
{% for event in partner_events %}
  <a href="{{ event | tenant_url }}">{{ event.title }}</a>
{% endfor %}

If the site cannot be resolved, the filter returns an empty array.

tenant_url

Type: URL Returns: String

Builds the correct public URL for a document loaded from another site. Existing absolute URLs pass through unchanged.

{{ event | tenant_url }}

limit

Type: Data (async) Returns: Array

Returns at most the requested number of items from an array or joined-document list. Unlike Liquid's slice, this filter can load additional pages from a joined list when required.

{% assign first_six = blog.posts | limit: 6 %}

Pass "all" to request the complete joined list. Use that only when the result is known to be small.

analytics_attributes

Type: Analytics Returns: String (HTML attributes)

Renders editor-defined data-analytics-* attributes for stable GA4/GTM reporting hooks. Apply it inside the opening tag of a block or section wrapper. The result has a leading space so it slots directly after the tag name, and is HTML-attribute-escaped to prevent attribute injection. When no analytics key is set, the filter outputs an empty string, so markup is unchanged for blocks without analytics metadata.

Pass either the block object (it carries the editor-entered analyticsKey / analyticsLabel), or a plain string key with an optional label named argument. An explicit label argument always takes precedence over the block's analyticsLabel; the key always comes from the input.

Syntax

{{ <settings_or_key> | analytics_attributes }}
{{ "<key>" | analytics_attributes: label: "<label>" }}

Parameters

Example

Pass the block object so the configured key and label flow through automatically:

<section{{ block | analytics_attributes }}>
  ...
</section>

Or pass an explicit key with an optional label:

<section{{ "homepage-featured-events" | analytics_attributes: label: "Homepage featured events" }}>

Output

<section data-analytics-key="homepage-featured-events" data-analytics-label="Homepage featured events">

The data-analytics-label attribute is only emitted when a label is present. No-code blocks render these same attributes automatically on their outer wrapper when an editor fills in the Analytics fields, so custom and no-code themes share one reporting taxonomy.

Technical IDs vs analytics keys. data-block-id is a generated technical identifier for rendering and debugging only; it can change and must NOT be used as a reporting key. Configure GA4/GTM triggers and variables against data-analytics-key, and read the human-readable data-analytics-label for display.

See also

• N/A

Index

By name

• absolute_asset_url -- absolute theme asset URL with cache busting
• analytics_attributes -- renders data-analytics-* attributes for GA4/GTM
• asset_url -- theme asset URL with cache busting
• collection -- finds documents by a field or custom attribute
• custom_attribute_relations -- queries custom attribute relationships
• file_url -- file or media URL
• handle -- alias for handleize
• handleize -- converts string to URL-safe slug
• image_url -- image URL with transform parameters
• img_url -- image URL with predefined size variant
• limit -- limits arrays and joined-document lists
• md5 -- MD5 hash of a string
• money -- formats cents as currency
• related_posts -- finds posts with shared tags or categories
• script_tag -- wraps filename in a script tag
• sha1 -- SHA1 hash of a string
• stylesheet_tag -- wraps URL in a stylesheet link tag
• t -- translates an interface string for the active language
• tenant -- scopes a collection drop to another site
• tenant_url -- builds a cross-site document URL

By category

Asset

• asset_url
• absolute_asset_url
• stylesheet_tag
• script_tag

Media

• img_url
• image_url
• file_url

String

• handleize
• handle

Formatting

• money

Translation

• t

Hash

• md5
• sha1

Data

• collection
• related_posts
• custom_attribute_relations
• tenant
• limit

URL

• tenant_url

Analytics

• analytics_attributes

Related

• Liquid tags reference -- all custom Liquid tags
• Field types reference -- schema field types for blocks and templates
• How to create page templates -- writing templates that use filters
• How to define theme-level settings -- settings that filters can reference