Filters

Filters transform values in template expressions. Alloy ships with 50+ built-in filters covering strings, dates, arrays, URLs, math, and content processing. Filters are registered in both the Liquid and Go template engines at startup.

{{ page.title | upcase }}
{{ page.date | date: "%B %d, %Y" }}
{{ collections.blog | sort: "title" | first }}

Filters chain left to right. Each filter receives the output of the previous expression as its input.

String filters

slugify

The slugify filter converts any string to a URL-safe slug by lowercasing, replacing spaces with hyphens, and stripping non-alphanumeric characters:

{{ "My First Blog Post!" | slugify }}
<!-- Output: my-first-blog-post -->

<a href="/tags/{{ tag | slugify }}/">{{ tag }}</a>

Date filter

The date filter formats dates using strftime directives, powered by lestrrat-go/strftime for full POSIX compliance.

{{ page.date | date: "%B %d, %Y" }}
<!-- Output: April 10, 2026 -->

{{ page.date | date: "%Y-%m-%d" }}
<!-- Output: 2026-04-10 -->

<time datetime="{{ page.date | date: '%Y-%m-%dT%H:%M:%S%z' }}">
  {{ page.date | date: "%A, %B %e, %Y" }}
</time>

Accepts time.Time objects or string input (ISO 8601, RFC 3339, YYYY-MM-DD HH:MM:SS, YYYY-MM-DD). Returns input unchanged when no format argument is provided.

Common directives:

Array filters

Array filters operate on collections, taxonomy groups, and any list data.

where

The where filter selects items from an array where a field matches a value:

{% assign featured = collections.blog | where: "featured", true %}
{% for post in featured %}
  <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
{% endfor %}

{% assign js_posts = collections.blog | where: "tags", "javascript" %}

sort

The sort filter is numeric-aware. When values are whole numbers, they are compared numerically rather than as strings:

{% assign sorted_nav = taxonomies.tags.foundations | sort: "order" %}
{% for page in sorted_nav %}
  <a href="{{ page.url }}">{{ page.title }}</a>
{% endfor %}

With front matter order: 1, order: 2, order: 10, order: 20, the sort produces 1, 2, 10, 20 – not 1, 10, 2, 20 as a naive string sort would.

Numeric detection rules:

• Integer YAML values (order: 10, order: -1) are compared as integers
• Float values with no fractional part (10.0) are compared as integers
• String values containing only digits ("10") are parsed and compared as integers
• Everything else falls back to string comparison
• Nil or missing values sort to the end

group_by

The group_by filter groups items by a shared field value:

{% assign by_year = collections.blog | group_by: "year" %}
{% for group in by_year %}
  <h2>{{ group.name }}</h2>
  {% for post in group.items %}
    <a href="{{ post.url }}">{{ post.title }}</a>
  {% endfor %}
{% endfor %}

map

The map filter extracts a single field from every item in an array:

{{ collections.blog | map: "title" | join: ", " }}
<!-- Output: First Post, Second Post, Third Post -->

Set operation filters

URL filters

<link rel="stylesheet" href="{{ 'css/main.css' | url }}">
<link rel="canonical" href="{{ page.url | absolute_url }}">

Math filters

Content filters

markdownify

Renders a Markdown string to HTML using the same goldmark configuration as the main content renderer:

{{ page.description | markdownify }}

This is useful for rendering Markdown in front matter fields or data file values. The filter uses the site’s content.markdown settings (unsafe mode, typographer, heading IDs) but does not run template tag protection – it processes already-rendered values.

# data/features.yaml
- title: Core Engine
  description: "Built on **Go** for speed and `goldmark` for Markdown."

{% for feature in site.data.features %}
  <div class="feature">
    <h3>{{ feature.title }}</h3>
    {{ feature.description | markdownify }}
  </div>
{% endfor %}

safeHTML

Bypasses auto-escaping for trusted HTML content. Relevant primarily for the Go template engine:

{{ page.embed_code | safeHTML }}

Regex filters

Data filters

<script type="application/ld+json">
  {{ page | json }}
</script>

<p>By {{ page.author | default: "Staff Writer" }}</p>

Asset filters

fingerprint

Content-hash fingerprinting for cache busting. Computes a SHA-256 hash of the file contents and appends it to the filename:

<link rel="stylesheet" href="{{ 'css/main.css' | fingerprint }}">
<!-- Output: /css/main.abc123def456.css -->

The filter resolves paths against source directories in order: static/ -> assets/ -> content/ (for co-located assets).

cachebust

Appends a content hash as a query parameter instead of rewriting the filename:

<link rel="stylesheet" href="{{ 'css/main.css' | cachebust }}">
<!-- Output: /css/main.css?h=abc123def456 -->

File not found degrades gracefully – returns the path without a hash.

get_hash

Returns the raw hash digest of a file:

{{ 'css/main.css' | get_hash }}
<!-- Output: base64-encoded SHA-256 digest -->

Feed-related filters

These filters are helpful when building RSS or Atom feed templates:

<!-- layouts/feed.xml.liquid -->
{% for post in collections.blog %}
<item>
  <title>{{ post.title | xml_escape }}</title>
  <pubDate>{{ post.date | rfc822_date }}</pubDate>
  <link>{{ post.url | absolute_url }}</link>
</item>
{% endfor %}

Custom filters via plugins

Register custom filters from a plugin. Plugin filters work in layouts, content templates, and partials.

JS plugin (Tier 2 – in-process):

// plugins/word-count.js
export default function(alloy) {
  alloy.filter("wordCount", (content) => {
    return content.split(/\s+/).filter(w => w.length > 0).length;
  });
}

<p>{{ page.content | wordCount }} words</p>

WASM plugin (Tier 2 – compiled, fastest):

Compile a filter to .wasm from Rust, TinyGo, or AssemblyScript for maximum performance on filters called thousands of times per build.

Node plugin (Tier 3 – full Node.js access):

// plugins/reading-time.js
export const runtime = "node";
export default function(alloy) {
  alloy.filter("readingTime", (content) => {
    const words = content.split(/\s+/).length;
    return Math.ceil(words / 200);
  });
}

If two plugins register the same filter name, the last one loaded wins. Alloy logs a warning:

[alloy] WARN Filter "slugify" registered by plugins/custom-slugify.wasm
        overwrites built-in filter "slugify"

Load order: built-in Go filters first, then Tier 2 plugins (.js and .wasm alphabetically), then Tier 3 Node plugins.