Skip to Content

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