URL Filters

URL filters generate URLs for theme assets, images, and files. These filters are essential for loading static assets and displaying optimized images in your theme.

Asset URL Filters

asset_url filter

Generates a URL for a file in your theme’s assets/ directory. The URL includes cache-busting parameters based on the theme version.

Syntax:

{{ 'path/to/file' | asset_url }}

Input: A string path relative to the assets/ directory.

Output: A fully-qualified URL to the asset with cache-busting parameters.

Code

{{ 'css/main.css' | asset_url }}
{{ 'js/app.js' | asset_url }}
{{ 'images/logo.svg' | asset_url }}

Output

/files/theme-key/assets/css/main.css?v=theme-key&c=1.0.0
/files/theme-key/assets/js/app.js?v=theme-key&c=1.0.0
/files/theme-key/assets/images/logo.svg?v=theme-key&c=1.0.0

Common usage with stylesheet and script tags:

<link rel="stylesheet" href="{{ 'css/main.css' | asset_url }}">
<script src="{{ 'js/app.js' | asset_url }}"></script>
<img src="{{ 'images/hero-bg.jpg' | asset_url }}" alt="Hero background">

---

absolute_asset_url filter

Similar to asset_url, but without the cache-busting version parameter. The name is historical—in most cases both filters produce relative URLs.

Syntax:

{{ 'path/to/file' | absolute_asset_url }}

Code

{{ 'images/og-image.jpg' | absolute_asset_url }}

Output

/files/theme-key/assets/images/og-image.jpg?v=theme-key

Tip

For Open Graph images that require absolute URLs, combine with the site.url global:

<meta property="og:image" content="{{ site.url }}{{ 'images/og-default.jpg' | asset_url }}">

---

Image URL Filter

image_url filter

Generates an optimized image URL with optional transformation parameters. This filter works with media objects from the CMS and supports automatic focal point handling.

Syntax:

{{ image | image_url }}
{{ image | image_url: width: 800 }}
{{ image | image_url: width: 800, height: 600, fit: 'cover' }}

Parameters:

Parameter	Type	Description
width	number	Target width in pixels
height	number	Target height in pixels
fit	string	How to fit the image: cover, contain, fill, inside, outside
gravity	string	Focus area: center, north, south, east, west, etc.
focalX	number	Horizontal focal point (0-100)
focalY	number	Vertical focal point (0-100)

Note

When passing a media object (not just a URL string), the filter automatically includes focalX and focalY values from the media object if they are set in the CMS. This ensures images are cropped around the defined focal point.

Basic usage:

Code

{# Simple resize #}
{{ event.image | image_url: width: 400 }}

{# Resize with specific dimensions #}
{{ event.image | image_url: width: 800, height: 450 }}

{# Resize with fit mode #}
{{ event.image | image_url: width: 800, height: 450, fit: 'cover' }}

Output

/media/event-image.jpg?w=400&fx=50&fy=50
/media/event-image.jpg?w=800&h=450&fx=50&fy=50
/media/event-image.jpg?w=800&h=450&f=cover&fx=50&fy=50

With focal point override:

{# Override the default focal point #}
{{ event.image | image_url: width: 800, height: 450, focalX: 30, focalY: 20 }}

Responsive images example:

<picture>
  <source
    media="(min-width: 1200px)"
    srcset="{{ event.image | image_url: width: 1200 }}">
  <source
    media="(min-width: 768px)"
    srcset="{{ event.image | image_url: width: 800 }}">
  <img
    src="{{ event.image | image_url: width: 400 }}"
    alt="{{ event.image.alt | default: event.title }}">
</picture>

Fit modes explained:

Mode	Description
cover	Scales the image to fill both dimensions, cropping if necessary
contain	Scales the image to fit within both dimensions, may letterbox
fill	Stretches the image to fill both dimensions exactly
inside	Like contain, but never upscales
outside	Like cover, but never downscales

---

img_url filter

A simpler filter that extracts the source URL from a media object. Does not support transformation parameters.

Syntax:

{{ image | img_url }}

Input: A media object or string URL.

Output: The src property if the input is an object, otherwise returns the input unchanged.

{# Works with media objects #}
{{ event.image | img_url }}

{# Also works with plain strings #}
{{ 'https://example.com/image.jpg' | img_url }}

---

File URL Filter

file_url filter

Generates a URL for downloadable files such as PDFs, documents, or other non-image media.

Syntax:

{{ file | file_url }}

Input: A file object from the CMS or a string URL.

Output: The file’s source URL.

{% if event.program_pdf %}
  <a href="{{ event.program_pdf | file_url }}" download>
    Download Program (PDF)
  </a>
{% endif %}

---

HTML Tag Filters

These filters wrap asset URLs in HTML tags for convenience.

stylesheet_tag filter

Wraps a URL in a <link> tag for CSS stylesheets.

Syntax:

{{ url | stylesheet_tag }}

Code

{{ 'css/main.css' | asset_url | stylesheet_tag }}

Output

<link href="/files/theme-key/assets/css/main.css?v=theme-key" rel="stylesheet" type="text/css" media="all" />

---

script_tag filter

Wraps a filename in a <script> tag with the full asset URL.

Syntax:

{{ 'filename.js' | script_tag }}

Code

{{ 'js/main.js' | script_tag }}

Output

<script src="/files/theme-key/assets/js/main.js?v=theme-key" type="text/javascript"></script>

Tip

Note that script_tag takes just the filename and generates the full asset URL internally, while stylesheet_tag requires you to first generate the URL with asset_url.

---

Custom Attribute Filter

custom_attribute_relations filter

Looks up content items that have a specific custom attribute value. This is an advanced async filter for querying related content via custom attributes.

Syntax:

{{ collection_name | custom_attribute_relations: attribute: 'attribute_name', value: related_id }}
{{ input_object | custom_attribute_relations: attribute: 'attribute_name', collection: 'collection_name' }}

Parameters:

Parameter	Type	Required	Description
attribute	string	Yes	The custom attribute name to query
collection	string	Yes*	The collection to search (e.g., 'events', 'people')
value	string/object	Yes*	The ID value to match against
limit	number	No	Maximum number of results
depth	number	No	Relationship depth for populated fields
sort	string	No	Sort field and direction
locale	string	No	Locale for localized content

*Either pass the collection as the input string or via the collection parameter.

Output: An array of matching content items.

Code

{# Find all events where custom attribute 'featured_artist' equals this person's ID #}
{% assign related_events = 'events' | custom_attribute_relations: attribute: 'featured_artist', value: person.id, limit: 6 %}

{% for event in related_events %}
  <a href="/events/{{ event.slug }}">{{ event.title }}</a>
{% endfor %}

Alternative Syntax

{# Pass the relation object directly #}
{% assign related_events = person | custom_attribute_relations: attribute: 'featured_artist', collection: 'events' %}

Example Usage

Finding events by a custom “composer” attribute:

{% assign composer_events = 'events' | custom_attribute_relations:
  attribute: 'composer',
  value: work.id,
  limit: 10,
  sort: 'startDate' %}

{% if composer_events.size > 0 %}
  <h2>Upcoming Performances</h2>
  {% for event in composer_events %}
    <article>
      <h3>{{ event.title }}</h3>
      <time>{{ event.startDate | date: '%B %d, %Y' }}</time>
    </article>
  {% endfor %}
{% endif %}

Note

This filter requires custom attributes to be configured in your Basker CMS tenant. The attribute must be a relationship type pointing to another collection.