Filters are simple methods that modify the input markup. Filters take whatever is on the left, modify it, and pass it on to the next filter. If there are no more filters to apply, the result is returned.
Some examples:
// Capitalize the output of the "test" variable.
{{ "test" | capitalize }}
#=> TEST
// Output the number of the characters in the "test" variable.
Word "test" has {{ "test" | size }} letters!
#=> Word "test" has 4 letters!
You can also "chain" filters together like so:
{{ "foo" | append: "bar" | upcase }}
#=> FOOBAR
Append a string to another. Useful for joining string variables.
{% assign suffix = "-suffix" %}
{{ "foo" | append: suffix }}
#=> foo-suffix
Capitalizes words in input.
Only works on ASCII strings. For UTF-8 strings, use capitalize_utf8.
{{ "howdy developers!" | capitalize }}
#=> Howdy Developers!
Limits a number to a minimum value.
{{ 4 | at_least: 5 }}
#=> 5
{{ 4 | at_least: 3 }}
#=> 4
Limits a number to a maximum value.
{{ 4 | at_most: 5 }}
#=> 5
{{ 4 | at_most: 3 }}
#=> 3
Returns the smallest integer greater than or equal to given number.
{{ "1.1" | ceil }}
#=> 2
{{ 1.0 | ceil }}
#=> 1
Remove nil values within an array.
{{ someArray | compact }}
It provide also optional property with which to check for nil:
{{ elements | compact: "lastname" }}
Join two arrays.
{% assign fruitsArray = "orange,apple,banana" | split: "," %}
{% assign tagsArray = "first,best" | split: "," %}
{% assign newArr = fruitsArray | concat: tagsArray %}
{{ newArr | join: ", "}}
#=> orange, apple, banana, first, best
Reformat a date.
This page was last updated at {{ page.updated_at | date: "%d.%m.%Y" }}
#=> This page was last updated at 09.10.2008
Available date format attributes:
%a - The abbreviated weekday name (``Sun'')
%A - Full weekday name (''Sunday'')
%b - The abbreviated month name (''Jan'')
%B - Full month name (''January'')
%c - Preferred local date and time representation (Tue Apr 22 11:16:09 2014)
%d - Day of the month, zero-padded (01, 02, 03, etc.).
%-d - Day of the month, not zero-padded (1,2,3, etc.).
%D - Formats the date (dd/mm/yy).
%e - Day of the month, blank-padded ( 1, 2, 3, etc.).
%F - Returns the date in ISO 8601 format (yyyy-mm-dd).
%H - Hour of the day, 24-hour clock (00 - 23).
%I - Hour of the day, 12-hour clock (01 - 12).
%j - Day of the year (001 - 366).
%k - Hour of the day, 24-hour clock (1 - 24).
%m - Month of the year (01 - 12), zero-padded.
%-m - Month of the year (1 - 12), not padded.
%M - Minute of the hour (00 - 59).
%p - Meridian indicator (AM/PM).
%r - 12-hour time (%I:%M:%S %p)
%R - 24-hour time (%H:%M)
%T - 24-hour time (%H:%M:%S)
%U - The number of the week in the current year, starting with the first Sunday as the first day of the first week.
%W - The number of the week in the current year, starting with the first Monday as the first day of the first week.
%w - Day of the week (0 - 6, with Sunday being 0).
%x - Preferred representation for the date alone, no time. (mm/dd/yy).
%X - Preferred representation for the time. (hh:mm:ss).
%y - Year without a century (00..99).
%Y - Year with a century.
%Z - Time zone name.
%% - Literal ''%'' character
Returns provided default value if the input is empty or null.
{{ "" | default: "default value" }}
#=> default value
Division. Returns an integer (no commas). Strings are automatically converted to numbers.
{{ 10 | divided_by: 2 }}
#=> 5
{{ 10 | divided_by: 3 }}
#=> 3
{{ 10 | divided_by: 3.0 }}
#=> 3.3333333333333335
{{ "10" | divided_by: "2" }}
#=> 5
Sets all words in input to lowercase.
Only works on ASCII strings. For UTF-8 strings, use downcase_utf8.
{{ "SCREAM!" | downcase }}
#=> scream!
Escapes HTML from output:
{{ "<b>I'm a big orangutang</b>" | escape }}
#=> <b>I'm a big orangutang</b>
Returns an escaped version of html without affecting existing escaped entities.
{{ "<b>I'm a big & orangutang</b>" | escape_once }}
#=> <b>I'm a big & orangutang</b>
Get the first element of passed in array.
{{ blog.articles | first }}
Returns the largest integer less than or equal to given number.
{{ "1.1" | floor }}
#=> 1
{{ 1.0 | floor }}
#=> 1
Formats date in respect to active locale settings. For example if user is on page that is in French then day and month names will also be translated to french. Same formatting attributes apply as in date filter.
{{ page.updated_at | format_date: "%A, %d %B"}}
=> Vendredi, 5 Mars
This filter also accepts shortcut parameters to format date accordingly to locale settings. Format for date will be chosen
by language that the current page is in. Valid shortcut arguments are default
, long
,short
and long_without_year
.
Example:
{{ page.updated_at | format_date: "long" }}
Formats time in respect to active locale settings. For example if user is on page that is in French then day and month names will also be translated to french. Same formatting attributes apply as in date filter.
{ "2033-01-02 11:12:13" | format_time: "%A, %d %B %H:%M" }}
=> Dimanche, 02 Janvier 11:12
This filter also accepts shortcut parameters to format time accordingly to locale settings. Format for date will be chosen
by language that the current page is in. Valid shortcut arguments are default
, long
,short
and long_without_year
.
Example:
{{ page.updated_at | format_time: "long" }}
#=> 2 Janvier 2033 11:12
Join elements of array with certain characters between them.
{{ site.language_tags | map: "name" | join: ", " }}
Converts object to JSON. Useful for passing custom data, and other objects to JavaScript.
<script>
var pageData = {{ page.data | json }};
</script>
Converts JSON string to JSON object. Useful for passing custom data, and other objects to JavaScript.
{% assign json_result = '{"foo":{"bar":[1,2,3]}}' | json_parse %}
{{ json_result.foo.bar.last }}
#=> 3
Filter supports boolean parameter (defaults to false) to control raising of the JSON string parsing exception. When true the exception is raised. Sometimes you don't want to brake the page for public mode but you want to show parsing errors for admin so this is possible:
{% assign broken_json_result = '"foo":{"bar":[1,2,3' | json_parse: editmode %}
Get the last element of passed in array.
{{ blog.articles | last }}
Returns translation for the given key based on current locale. See also available built-in translation keys.
{{ "add_a_comment" | lc }}
Current locale can be override with additional parameter:
{{ "add_a_comment" | lc: "en" }}
{{ "add_a_comment" | lc: editor_locale }}
Returns translation for the given key based on editor interface locale. See also available built-in translation keys.
{{ "add_a_comment" | lce }}
it's alias for:
{{ "add_a_comment" | lc: editor_locale }}
Returns translation for the given key based on current locale and provided number. See also available built-in translation keys.
{{ "post_has_replies" | lcc: article.comments_count }}
Current locale can be override with additional parameter:
{{ "post_has_replies" | lcc: article.comments_count, "en" }}
{{ "post_has_replies" | lcc: article.comments_count, editor_locale }}
Returns translation for the given key based on editor interface locale and provided number. See also available built-in translation keys.
{{ "post_has_replies" | lcce: article.comments_count }}
it's alias for:
{{ "post_has_replies" | lcc: article.comments_count, editor_locale }}
Removes white spaces and newlines from left of string. See also strip and rstrip.
{{ " some word " | lstrip }}
#=> "some word "
Returns array of given property values in an object.
{% assign latestArticleTitles = site.latest_articles | map: "title" %}
{{ latestArticleTitles | join: ", " }}
Subtraction. Strings are automatically converted to numbers.
{{ 4 | minus: 2 }}
#=> 2
{{ "4" | minus: 2 }}
#=> 2
Remainder. Strings are automatically converted to numbers.
{{ 3 | modulo: 2 }}
#=> 1
{{ "3" | modulo: "2" }}
#=> 1
Replaces each newline (\n
) with HTML break.
{% capture multilineText %}
Multiple
lines
of
text.
{% endcapture %}
{{ multilineText | newline_to_br }}
#=> <br />
Multiple<br />
lines<br />
of<br />
text.<br />
Addition. Strings are automatically converted to numbers.
{{ 1 | plus: 2 }}
#=> 3
{{ "1" | plus: "2" }}
#=> 3
Prepend a string to another. Useful for joining string variables.
{% assign prefix = "prefixed-" %}
{{ "foo" | prepend: prefix }}
#=> prefixed-foo
Removes each occurrence in a string.
{{ "foobarfoobar" | remove: "foo" }}
#=> barbar
Removes the first occurrence in a string.
{{ "barbar" | remove_first: "bar" }}
#=> bar
Replaces each occurrence in a string.
{{ "foofoo" | replace: "foo", "bar" }}
#=> barbar
Replaces first occurrence in a string.
{{ "barbar" | replace_first: "bar", "foo" }}
#=> foobar
Rounds input to the nearest integer or specified number of decimals.
{{ "19.333" | round }}
#=> 19
{{ "19.333" | round: 2 }}
#=> 19.33
Removes the last element(s) (1 by default) from an array and returns the modified array.
{% assign fruits = "1,2,3,4" | split: "," %}{{ fruits | pop: 2 | join: "," }}
#=> 1,2
Append the given object(s) on to the end of this array and returns the modified array.
{% assign fruits = "1,2" | split: "," %}{{ fruits | push: "3" | join: "," }}
#=> 1,2,3
Reverses an array.
{% assign numbers = "one,two,three" | split: "," %}
{{ numbers | reverse | join: "," }}
#=> three,two,one
Removes white spaces and newlines from right of string. See also strip and lstrip.
{{ " some word " | rstrip }}
#=> " some word"
Removes element(s) (1 by default) form the beginning of an array and returns the modified array.
{% assign fruits = "1,2,3" | split: "," %}{{ fruits | shift: 2 | join: "," }}
#=> 3
Returns the length of an array or string.
There are {{ blog.articles | size }} articles in this blog
#=> There are 5 articles in this blog
Slice a string. Takes an offset and length.
{{ "hello" | slice: -3, 3 }}
#=> llo
Sorts the elements of the array in ascending order (case sensitive).
{% assign fruitsArray = "orange,apple,banana" | split: "," %}
{{ fruitsArray | sort | join: ", " }}
#=> apple, banana, orange
Also can sort object by given key:
{% assign sortedTags = site.language_tags | sort: "name" %}
{% for tag in sortedTags %}
{{ tag.name }}<br/>
{% endfor %}
Sorts the elements of the array in ascending order (ignoring case if value is string).
{% assign fruitsArray = "orange,apple,APPLE,banana" | split: "," %}
{{ fruitsArray | sort_natural | join: ", " }}
#=> apple, banana, orange
Also can sort object by given key:
{% assign sortedTags = site.language_tags | sort_natural: "name" %}
{% for tag in sortedTags %}
{{ tag.name }}<br/>
{% endfor %}
Splits a string on a matching pattern. Useful for creating arrays in Liquid.
{% assign fruitsArray = "orange,apple,banana" | split: "," %}
#=> ["orange", "apple", "banana"]
Removes surrounding white spaces and newlines. See also lstrip and rstrip.
{{ " some word " | strip }}
#=> some word
Removes HTML-tags from passed in string.
{{ "<b>Do not cross the <a href="#yellow">yellow</a> line</b>" | strip_html }}
#=> Do not cross the yellow line
strip all newlines (\n
) from string.
{% capture multilineText %}
a,
b,
c
{% endcapture %}
{{ multilineText | strip_newlines }}
#=> a,b,c
Multiplication. Strings are automatically converted to numbers.
{{ 5 | times: 4 }}
#=> 20
{{ "5" | times: "4" }}
#=> 20
Converts string to number.
{% assign numString = "123" %}
{% if numString | to_num > 99.9 %}
Bigger than 99.9
{% endif %}
Truncate string down to predefined number of characters.
{{ "Quick brown fox jumps over the lazy dog" | truncate: 8 }}
#=> Quick...
Truncate string can also be defined:
{{ "Quick brown fox jumps over the lazy dog" | truncate: 7, "--" }}
#=> Quick--
Truncate an HTML string down to predefined number of characters (excluding the HTML tags and including the tail).
{{ "<p><b>Hello world!</b></p>" | truncate_html: 5 }}
#=> <p><b>Hell…</b></p>
Truncate string can also be defined (by default it is "…"):
{{ "<p><b>Hello world!</b></p>" | truncate_html: 6, "?" }}
#=> <p><b>Hello?</b></p>
Truncates string down to n words.
{{ "String of four words" | truncatewords: 3 }}
#=> String of four...
{{ "String of four words" | truncatewords: 3, " --" }}
#=> String of four --
Converts all characters in string into uppercase.
Only works on ASCII strings. For UTF-8 strings, use upcase_utf8.
{{ "scream!" | upcase }}
#=> SCREAM!
Returns only unique elements in array.
{% assign fruitsArray = "orange,apple,orange,banana,banana" | split: "," %}
{{ fruitsArray | uniq | join: ", " }}
#=> orange, apple, banana
It supports also uniqueness over object property:
{% for tag in site.language_tags | uniq: "name" %}
{{ tag.name }}<br/>
{% endfor %}
Prepends object to the front of an array, moving other elements upwards and returns the modified array.
{% assign fruits = "1,2" | split: "," %}{{ fruits | unshift: "3" | join: "," }}
#=> 3,1,2
Creates an array including only the objects with a given property value, or any truthy value by default.
All products:
{% for product in products %}
– {{ product.title }}
{% endfor %}
#=>
All products:
– Vacuum
– Spatula
– Television
– Garlic press
{% assign kitchen_products = products | where: "type", "kitchen" %}
Kitchen products:
{% for product in kitchen_products %}
– {{ product.title }}
{% endfor %}
#=>
Kitchen products:
– Spatula
– Garlic press
Encodes string. Useful for appending some data to url as parameter.
{{ "http://www.voog.com/developers/api/resources/articles" | url_encode }}
#=> http%3A%2F%2Fwww.voog.com%2Fdevelopers%2Fapi%2Fresources%2Farticles
Decodes decoded url values.
{{ "http%3A%2F%2Fwww.voog.com%2Fdevelopers%2Fapi%2Fresources%2Farticles" | url_decode }}
#=> http://www.voog.com/developers/api/resources/articles