Filters

Overview

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

List of available filters

Text filters:

append
capitalize
capitalize_utf8
date
default
downcase
downcase_utf8
format_date
format_time
lc
lcc
lce
lstrip
newline_to_br
prepend
remove
remove_first
replace
replace_first
rstrip
size
slice
split
strip
strip_html
strip_newlines
to_num
truncate
truncate_html
truncatewords
upcase
upcase_utf8

append

Append a string to another. Useful for joining string variables.

{% assign suffix = "-suffix" %}
{{ "foo" | append: suffix }}
#=> foo-suffix

capitalize, capitalize_utf8

Capitalizes words in input.
Only works on ASCII strings. For UTF-8 strings, use capitalize_utf8.

{{ "howdy developers!" | capitalize }}
#=> Howdy Developers!

at_least

Limits a number to a minimum value.

{{ 4 | at_least: 5 }}
#=> 5
{{ 4 | at_least: 3 }}
#=> 4

at_most

Limits a number to a maximum value.

{{ 4 | at_most: 5 }}
#=> 5
{{ 4 | at_most: 3 }}
#=> 3

ceil

Returns the smallest integer greater than or equal to given number.

{{ "1.1" | ceil }}
#=> 2
{{ 1.0 | ceil }}
#=> 1

compact

Remove nil values within an array.

{{ someArray | compact }}

It provide also optional property with which to check for nil:

{{ elements | compact: "lastname" }}

concat

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

date

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

default

Returns provided default value if the input is empty or null.

{{ "" | default: "default value" }}
#=> default value

divided_by

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

downcase, downcase_utf8

Sets all words in input to lowercase.
Only works on ASCII strings. For UTF-8 strings, use downcase_utf8.

{{ "SCREAM!" | downcase }}
#=> scream!

escape

Escapes HTML from output:

{{ "<b>I'm a big orangutang</b>" | escape }}
#=> &lt;b&gt;I&#39;m a big orangutang&lt;/b&gt;

escape_once

Returns an escaped version of html without affecting existing escaped entities.

{{ "&lt;b&gt;I&#39;m a big & orangutang&lt;/b&gt;" | escape_once }}
#=> &lt;b&gt;I&#39;m a big &amp; orangutang&lt;/b&gt;

first

Get the first element of passed in array.

{{ blog.articles | first }}

floor

Returns the largest integer less than or equal to given number.

{{ "1.1" | floor }}
#=> 1
{{ 1.0 | floor }}
#=> 1

format_date

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" }}

format_time

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

Join elements of array with certain characters between them.

{{ site.language_tags | map: "name" | join: ", " }}

json

Converts object to JSON. Useful for passing custom data, and other objects to JavaScript.

<script>
  var pageData = {{ page.data | json }};
</script>

json_parse

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 %}

last

Get the last element of passed in array.

{{ blog.articles | last }}

lc

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 }}

lce

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 }}

lcc

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 }}

lcce

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 }}

lstrip

Removes white spaces and newlines from left of string. See also strip and rstrip.

{{ "     some word     " | lstrip }}
#=> "some word     "

map

Returns array of given property values in an object.

{% assign latestArticleTitles = site.latest_articles | map: "title" %}
{{ latestArticleTitles | join: ", " }}

minus

Subtraction. Strings are automatically converted to numbers.

{{ 4 | minus: 2 }}
#=> 2
{{ "4" | minus: 2 }}
#=> 2

modulo

Remainder. Strings are automatically converted to numbers.

{{ 3 | modulo: 2 }}
#=> 1
{{ "3" | modulo: "2" }}
#=> 1

newline_to_br

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 />

plus

Addition. Strings are automatically converted to numbers.

{{ 1 | plus: 2 }}
#=> 3
{{ "1" | plus: "2" }}
#=> 3

prepend

Prepend a string to another. Useful for joining string variables.

{% assign prefix = "prefixed-" %}
{{ "foo" | prepend: prefix }}
#=> prefixed-foo

remove

Removes each occurrence in a string.

{{ "foobarfoobar" | remove: "foo" }}
#=> barbar

remove_first

Removes the first occurrence in a string.

{{ "barbar" | remove_first: "bar" }}
#=> bar

replace

Replaces each occurrence in a string.

{{ "foofoo" | replace: "foo", "bar" }}
#=> barbar

replace_first

Replaces first occurrence in a string.

{{ "barbar" | replace_first: "bar", "foo" }}
#=> foobar

round

Rounds input to the nearest integer or specified number of decimals.

{{ "19.333" | round }}
#=> 19
{{ "19.333" | round: 2 }}
#=> 19.33

pop

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

push

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

reverse

Reverses an array.

{% assign numbers = "one,two,three" | split: "," %}
{{ numbers | reverse | join: "," }}
#=> three,two,one

rstrip

Removes white spaces and newlines from right of string. See also strip and lstrip.

{{ "     some word     " | rstrip }}
#=> "     some word"

shift

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

size

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

Slice a string. Takes an offset and length.

{{ "hello" | slice: -3, 3 }}
#=> llo

sort

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 %}

sort_natural

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 %}

split

Splits a string on a matching pattern. Useful for creating arrays in Liquid.

{% assign fruitsArray = "orange,apple,banana" | split: "," %}
#=> ["orange", "apple", "banana"]

strip

Removes surrounding white spaces and newlines. See also lstrip and rstrip.

{{ "     some word     " | strip }}
#=> some word

strip_html

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_newlines

strip all newlines (\n) from string.

{% capture multilineText %}
a,
b,
c
{% endcapture %}
{{ multilineText | strip_newlines }}
#=> a,b,c

times

Multiplication. Strings are automatically converted to numbers.

{{ 5 | times: 4 }}
#=> 20
{{ "5" | times: "4" }}
#=> 20

to_num

Converts string to number.

{% assign numString = "123" %}
{% if numString | to_num > 99.9 %}
  Bigger than 99.9
{% endif %}

truncate

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_html

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>

truncatewords

Truncates string down to n words.

{{ "String of four words" | truncatewords: 3 }}
#=> String of four...
{{ "String of four words" | truncatewords: 3, " --" }}
#=> String of four --

upcase, upcase_utf8

Converts all characters in string into uppercase.
Only works on ASCII strings. For UTF-8 strings, use upcase_utf8.

{{ "scream!" | upcase }}
#=> SCREAM!

uniq

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 %}

unshift

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

where

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

url_encode

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

url_decode

Decodes decoded url values.

{{ "http%3A%2F%2Fwww.voog.com%2Fdevelopers%2Fapi%2Fresources%2Farticles" | url_decode }}
#=> http://www.voog.com/developers/api/resources/articles