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.

Overview

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, gravity, 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, replaces non-alphanumeric characters with hyphens, and trims leading/trailing hyphens. Supports Unicode characters.

Syntax

{{ "<text>" | handleize }}

Parameters

Example

{{ "Summer Season 2025" | handleize }}

Output

summer-season-2025

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

{{ "Opening Night Gala" | handle }}

Output

opening-night-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

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

{{ "user@example.com" | md5 }}

Output

b58996c504c5638798eb6b511e6f49af

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

e2e4c8f9a1b3d5e7f9a1b3d5e7f9a1b3d5e7f9a1

See also

• md5

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>{{ work.title }} by {{ work.composer }}</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

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 a block settings object carrying analyticsKey / analyticsLabel (the values an editor fills in via the block's Analytics fields), or a plain string key with an optional label named argument. An explicit label argument always takes precedence over a settings object'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 settings object so the configured key and label flow through automatically:

<section{{ block.blockSettings | 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
• 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
• md5 -- MD5 hash of a string
• money -- formats cents as currency
• script_tag -- wraps filename in a script tag
• sha1 -- SHA1 hash of a string
• stylesheet_tag -- wraps URL in a stylesheet link tag

By category

Asset

• asset_url
• absolute_asset_url
• stylesheet_tag
• script_tag

Media

• img_url
• image_url
• file_url

String

• handleize
• handle

Formatting

• money

Hash

• md5
• sha1

Data

• custom_attribute_relations

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