Liquid Filters
The following is a full list of the output block filters supported by the Liquid markup implementation used in TwentyThree. If you are not already familiar with the Liquid templating language, we recommend that you first read our Introduction to Liquid.
Reading and using filters
Each filter has a syntax documentation for easy reference which shows their name and their parameters enclosed in parentheses. The simplest filters only take one parameter, like downcase:
downcase(input)
The first parameter is always the input to the filter. This is either the variable or constant you applied the filter to, or the output from the previous filter if multiple filters are chained. Filters are applied using the | character after the variable or constant, and chaining is just a question of adding multiple filters:
{{ "Hello, World" | downcase }}
{{ "Hello, World" | downcase | upcase }}
/* output */
hello, world
HELLO, WORLD
Some filters, like the append filter, accept multiple parameters. The syntax for this looks like
append(input, added)
In this case, using the filter requires you to add the parameter added to your call to the filter. Filter parameters are provided using a colon after the filter name, and they are separated by commas. Using the append filter for example, looks like
{{ "Hello, " | append: "world" }}
/* output */
Hello, world
Filters like replace have a syntax that requires multiple parameters:
replace(input, substring, replacement)
Using this filter requires you to supply both the substring and replacement parameters after the filter name:
{{ "Hello, world" | replace: "Hello", "Hi" }}
/* output */
Hi, world
Lastly, some filters, like the img_tag filter have optional parameters. These are parameters that have a default value, which will be used if you do not provide the parameter yourself. The syntax for img_tag looks like
img_tag(url, alt="")
The alt parameter has an optional value, which is an empty string, so the following two lines produce the same output:
{{ "logo.png" | img_tag }}
{{ "logo.png" | img_tag: "" }}
append
append(input, added)
The append filter appends the string value of the parameter added at the end of the string value of the input.
Appending “, world” to the string “hello” can be done like
{{ "hello" | append: ", world" }}
with the output being
hello, world
capitalize
capitalize(input)
The capitalize filter returns a capitalized form of the input value. Capitalize only capitalizes the first word in the input string. Transforming “hello, world” to “Hello, world” can be done like
{{ "hello, world" | capitalize }}
with the output being
Hello, world
date
date(input, format)
The date filter transform a timestamp to a pretty string representation described by the format parameter. The syntax of the format parameter is the same as you would use for the ISO C strftime function, so a full reference for formatting parameters is available.
Formatting a simple date can be done like this
{{ photo.publish_time | date: "%Y-%m-%d" }}
with the output being something like
2011-05-07
divided_by
divided_by(input, operand)
Divides the input by the value of the operand parameter. For example, dividing 100 by 10 can be done like
{{ 100 | divided_by: 10 }}
with the output being
10
downcase
Converts the input to a lower-case string representation:
{{ "HELLO" | downcase }}
will result in
hello
escape(input)
Escapes the input value, so it’s an HTML safe representation:
{{ "25 < 26" | escape }}
will result in
25 < 26
first
first(array)
Returns the first value in the array parameter. For example, to get the first tag in the array tags, you would call:
{{ tags | first }}
img_tag
img_tag(url, alt="")
This filter creates an image tag, using the URL parameter as image source (<img src="…" />) and an optional second parameter as the alternative description of the image (<img alt="…" />).
Example usage for a static file on your TwentyThree site:
{{ "/files/logo.png" | img_tag }}
This will render the image logo.png from your static file folder founder under Power Mode → Site Designer → Files. The output will look like
<img src="/files/logo.png" />
If you want to add an alternative description to the image, you must add the optional alt parameter like
{{ "/files/logo.png" | img_tag: "Our logo" }}
This will render the same image but with the alternative description like
<img src="/files/logo.png" alt="Our logo" />
join
join(array, separator=" ")
Joins an array to a string using the separator parameter between each of the elements in the array. Creating a comma separated list of tags can be done like
{{ tags | join: ", " }}
which will generate a context dependant output like
blog, music, video
last
last(array)
Returns the last value in the array parameter. For example, to get the last tag in the array tags, you would call:
{{ tags | last }}
minus
minus(input, operand)
Subtracts the operand parameter from the value of input. For example, subtracting 10 from 100 can be done like
{{ 100 | minus: 10 }}
with the output being
90
newline_to_br
newline_to_br(input)
Adds an HTML line break before each new line in a string.
{% capture example %} Hello world {% endcapture %} {{ example | newline_to_br }}
This will then output
Hello<br/> world<br/>
plus
plus(input, operand)
Add the operand parameter from the value of input. For example, adding 10 to 100 can be done like
{{ 100 | plus: 10 }}
with the output being
110
prepend
prepend(input, added)
The prepend filter prepend the string value of the parameter added at the beginning of the string value of the input.
Prepending "hello, " to the string “world” can be done like
{{ "world" | prepend: "hello, " }}
with the output being
hello, world
remove
remove(input, substring)
Removes any occurrences of substring from the input value. For example:
{{ "Coca Cola is the best soft drink. I love Coca Cola." | remove: "Coca" }}
will result in an output of
Cola is the best soft drink. I love Cola.
remove_first
remove_first(input, substring)
Removes the first occurrence of substring from the input value. For example:
{{ "Coca Cola is the best soft drink. I love Coca Cola." | remove_first: "Coca" }}
will result in an output of
Cola is the best soft drink. I love Coca Cola.
replace
replace(input, substring, replacement)
Replaces any occurences of substring in the input value with replacement. For example:
{{ "Coca Cola is the best soft drink. I love Coca Cola." | replace: "Coca", "Pepsi" }}
will result in an output of
Pepsi Cola is the best soft drink. I love Pepsi Cola.
replace_first
replace_first(input, substring, replacement)
Replaces the first occurance of substring in the input value with replacement. For example:
{{ "Coca Cola is the best soft drink. I love Coca Cola." | replace_first: "Coca", "Pepsi" }}
will result in a semi-nonsensical output of
Pepsi Cola is the best soft drink. I love Coca Cola.
script_tag
script_tag(url)
This filter takes the URL of a JavaScript file and wraps it in a HTML compliant script tag. If you want to include a custom piece of JavaScript from your static files, this can be done like
{{ "/files/custom.js" | script_tag }}
The resulting HTML will be
<script type="text/javascript" src="/files/custom.js"></script>
It is generally advised, that you use this filter for working with custom JavaScript files.
size
size(input)
Gets the size of an array or string. For example
{{ "hello, world" | size }}
result in an output of
12
strip_html
strip_html(input)
Removes all HTML and HTML-like tags from the input, like
{{ "<a href='#hello'>hello</a>, world" | strip_html }}
will result in an output of
hello, world
strip_newlines
strip_newlines(input)
Removes all new line characters from the input, like
{{ "hello,
world" | strip_newlines }}
will result in an output of
hello, world
stylesheet_tag
stylesheet_tag(url)
This filter takes the url of a CSS file and wraps it in a HTML compliant link tag. If you want to include a custom piece of CSS from your static files, this can be done like
{{ "/files/custom.css" | stylesheet_tag }}
The resulting HTML will be
<link href="/files/custom.css" rel="stylesheet" type="text/css" media="all" />;
It is generally advised that you use this filter for working with custom stylesheets.
times
times(input, operand)
Multiplies the input by the value of the operand parameter. For example, multiplying 10 by 10 can be done like
{{ 10 | times: 10 }}
with the output being
100
truncate
truncate(input, characters = 100, end = "...")
Truncates the input string down to characters number of characters. If the input string is shorter than the specified number of characters, it will not be truncated. Otherwise, the end parameter will be appended to the output string.
If you are truncating a string that might contain HTML, make sure to use the strip_html filter to remove the HTML before truncating the string, as this filter does not respect HTML input. Examples of usage are:
{{ photo.content | truncate: 25 }}
{{ photo.content | truncate: 25, "" }}
The result is context dependent but will be something along the lines of
Corned beef swine turduck...
Corned beef swine turduck
truncatewords
truncatewords(input, words = 15, end = "...")
Truncates the input string down to words number of words. If the input string contains fewer words than the specified number of words, it will not be truncated. Otherwise, the end parameter will be appended to the output string.
If you are truncating a string that might contain HTML, make sure to use the strip_html filter to remove the HTML before truncating the string, as this filter does not respect HTML input. Examples of usage are:
{{ photo.content | truncatewords: 5 }}
{{ photo.content | truncatewords: 5, "" }}
The result is context dependent but will be something along the lines of
Corned beef swine turducken, shoulder...
Corned beef swine turducken, shoulder
upcase
Converts the input to an uppercase string representation:
{{ "hello" | upcase }}
will result in
HELLO