Browse documentation

Liquid Filters

On this page

All of the standard Liquid filters are supported (see below).

Rustyll adds several high-performance filters of its own, all of which you can find on this page. You can also create your own filters using plugins. Rustyll’s filter implementation is significantly faster than Jekyll’s, as they’re written in Rust rather than Ruby.

Description Filter and Output

Relative URL

Prepend baseurl config value to the input to convert a URL path into a relative URL. This is recommended for a site that is hosted on a subpath of a domain.

{{ "/assets/style.css" | relative_url }}

/my-baseurl/assets/style.css

Absolute URL

Prepend url and baseurl values to the input to convert a URL path to an absolute URL.

{{ "/assets/style.css" | absolute_url }}

http://example.com/my-baseurl/assets/style.css

Date to XML Schema

Convert a Date into XML Schema (ISO 8601) format.

{{ site.time | date_to_xmlschema }}

2008-11-07T13:07:54-08:00

Date to RFC-822 Format

Convert a Date into the RFC-822 format used for RSS feeds.

{{ site.time | date_to_rfc822 }}

Mon, 07 Nov 2008 13:07:54 -0800

Date to String

Convert a date to short format.

{{ site.time | date_to_string }}

07 Nov 2008

Date to String in ordinal US style

Format a date to ordinal, US, short format. 3.8.0

{{ site.time | date_to_string: "ordinal", "US" }}

Nov 7th, 2008

Date to Long String

Format a date to long format.

{{ site.time | date_to_long_string }}

07 November 2008

Date to Long String in ordinal UK style

Format a date to ordinal, UK, long format. 3.8.0

{{ site.time | date_to_long_string: "ordinal" }}

7th November 2008

Where

Select all the objects in an array where the key has the given value.

{{ site.members | where:"graduation_year","2014" }}

Where Expression

Select all the objects in an array where the expression is true. 3.2.0

{{ site.members | where_exp:"item", "item.graduation_year == 2014" }}

{{ site.members | where_exp:"item", "item.graduation_year < 2014" }}

{{ site.members | where_exp:"item", "item.projects contains 'foo'" }}

Find

Return the first object in an array for which the queried attribute has the given value or return nil if no item in the array satisfies the given criteria. 4.1.0

{{ site.members | find: "graduation_year", "2014" }}

Find Expression

Return the first object in an array for which the given expression evaluates to true or return nil if no item in the array satisfies the evaluated expression. 4.1.0

{{ site.members | find_exp:"item", "item.graduation_year == 2014" }}

{{ site.members | find_exp:"item", "item.graduation_year < 2014" }}

{{ site.members | find_exp:"item", "item.projects contains 'foo'" }}

Group By

Group an array's items by a given property.

{{ site.members | group_by:"graduation_year" }}

[{"name"=>"2013", "items"=>[...]}, {"name"=>"2014", "items"=>[...]}]

Group By Expression

Group an array's items using a Liquid expression. 3.4.0

{{ site.members | group_by_exp: "item", "item.graduation_year | truncate: 3, ''" }}

[{"name"=>"201", "items"=>[...]}, {"name"=>"200", "items"=>[...]}]

XML Escape

Escape some text for use in XML.

{{ page.content | xml_escape }}

CGI Escape

CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements. CGI escape normally replaces a space with a plus + sign.

{{ "foo, bar; baz?" | cgi_escape }}

foo%2C+bar%3B+baz%3F

URI Escape

Percent encodes any special characters in a URI. URI escape normally replaces a space with %20. Reserved characters will not be escaped.

{{ "http://foo.com/?q=foo, \bar?" | uri_escape }}

http://foo.com/?q=foo,%20%5Cbar?

Number of Words

Count the number of words in some text.
From v4.1.0, this filter takes an optional argument to control the handling of Chinese-Japanese-Korean (CJK) characters in the input string.
Passing 'cjk' as the argument will count every CJK character detected as one word irrespective of being separated by whitespace.
Passing 'auto' (auto-detect) works similar to 'cjk' but is more performant if the filter is used on a variable string that may or may not contain CJK chars.

{{ "Hello world!" | number_of_words }}

2

{{ "你好hello世界world" | number_of_words }}

1

{{ "你好hello世界world" | number_of_words: "cjk" }}

6

{{ "你好hello世界world" | number_of_words: "auto" }}

6

Array to Sentence

Convert an array into a sentence. Useful for listing tags. Optional argument for connector.

{{ page.tags | array_to_sentence_string }}

foo, bar, and baz

{{ page.tags | array_to_sentence_string: "or" }}

foo, bar, or baz

Markdownify

Convert a Markdown-formatted string into HTML.

{{ page.excerpt | markdownify }}

Smartify

Convert "quotes" into “smart quotes.”

{{ page.title | smartify }}

Converting Sass/SCSS

Convert a Sass- or SCSS-formatted string into CSS.

{{ some_sass | sassify }}

{{ some_scss | scssify }}

Slugify

Convert a string into a lowercase URL "slug". See below for options.

{{ "The _config.yml file" | slugify }}

the-config-yml-file

{{ "The _config.yml file" | slugify: "pretty" }}

the-_config.yml-file

{{ "The _cönfig.yml file" | slugify: "ascii" }}

the-c-nfig-yml-file

{{ "The cönfig.yml file" | slugify: "latin" }}

the-config-yml-file

Data To JSON

Convert Hash or Array to JSON.

{{ site.data.projects | jsonify }}

Normalize Whitespace

Replace any occurrence of whitespace with a single space.

{{ "a \n b" | normalize_whitespace }}

Sort

Sort an array. Optional arguments for hashes 1. property name 2. nils order (first or last).

{{ page.tags | sort }}

{{ site.posts | sort: "author" }}

{{ site.pages | sort: "title", "last" }}

Sample

Pick a random value from an array. Optionally, pick multiple values.

{{ site.pages | sample }}

{{ site.pages | sample: 2 }}

To Integer

Convert a string or boolean to integer.

{{ some_var | to_integer }}

Array Filters

Push, pop, shift, and unshift elements from an Array. These are NON-DESTRUCTIVE, i.e. they do not mutate the array, but rather make a copy and mutate that.

{{ page.tags | push: "Spokane" }}

["Seattle", "Tacoma", "Spokane"]

{{ page.tags | pop }}

["Seattle"]

{{ page.tags | shift }}

["Tacoma"]

{{ page.tags | unshift: "Olympia" }}

["Olympia", "Seattle", "Tacoma"]

Inspect

Convert an object into its String representation for debugging.

{{ some_var | inspect }}

Rustyll-specific Performance Filters

Rustyll adds several filters specifically designed for performance optimization:

Description Filter and Output

Parallel Map

Maps a collection in parallel across multiple CPU cores, providing significant performance improvements for large collections.

site.posts | parallel_map: 'title'

Cached

Caches the result of a filter chain for reuse, improving performance for expensive operations that are used multiple times.

site.posts | where: 'category', 'news' | cached: 'news_posts'

Optimized Sort

A highly optimized sorting implementation that's significantly faster than the standard sort filter for large collections.

site.posts | optimized_sort: 'date'

Parallel Where

Performs collection filtering in parallel for better performance on large datasets.

site.posts | parallel_where: 'category', 'news'

Memoize

Remembers the result of expensive operations for the duration of the build.

{{ site.posts | where_exp: 'post', 'post.content contains "keyword"' | memoize: 'keyword_posts' }}

Options for the slugify filter

The slugify filter accepts an option, each specifying what to filter. The default is default. They are as follows (with what they filter):

  • none: no characters
  • raw: spaces
  • default: spaces and non-alphanumeric characters
  • pretty: spaces and non-alphanumeric characters except for ._~!$&'()+,;=@
  • ascii: spaces, non-alphanumeric, and non-ASCII characters
  • latin: like default, except Latin characters are first transliterated (e.g. àèïòü to aeiou)

Rustyll’s implementation is significantly faster than Jekyll’s, particularly for large strings.

Detecting nil values with where filter

You can use the where filter to detect documents and pages with properties that are nil or "". For example,

// Using `nil` to select posts that either do not have `my_prop`
// defined or `my_prop` has been set to `nil` explicitly.
{% assign filtered_posts = site.posts | where: 'my_prop', nil %}

// Using Liquid's special literal `empty` or `blank` to select
// posts that have `my_prop` set to an empty value.
{% assign filtered_posts = site.posts | where: 'my_prop', empty %}

Binary operators in where_exp filter

You can use Liquid binary operators or and and in the expression passed to the where_exp filter to employ multiple conditionals in the operation.

For example, to get a list of documents on English horror flicks, one could use the following snippet:

{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}

Or to get a list of comic-book based movies, one may use the following:

{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}

Rustyll’s implementation of where_exp includes advanced optimization techniques that make these expressions much faster than Jekyll’s Ruby implementation.

Filter Performance

Rustyll’s filters are implemented in Rust, providing several performance advantages:

  1. Native code execution: Filters run as compiled code, not interpreted Ruby
  2. Parallel processing: Many filters can operate in parallel
  3. Memory efficiency: Minimal memory overhead during filter operations
  4. Zero-copy operations: Data is processed without unnecessary duplication
  5. Optimized algorithms: Using highly efficient data structures and algorithms

For the best performance with large sites, consider using the Rustyll-specific parallel filters.

Standard Liquid Filters

For your convenience, here is the list of all Liquid filters with links to examples in the official Liquid documentation.

Search Rustyll

Type to find a page.