Skip to main content
Documentation Designing Your Site Template Engines

Liquid Filters

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

To make common tasks easier, Bridgetown even adds a few handy filters of its own, all of which you can find on this page. You can also create your own filters using plugins.

Description Filter and Output

Relative URL

Prepend the base_path value to the input. Useful if your site is hosted at a subpath rather than the root of the domain.

{{ "/assets/image.jpg" | relative_url }}

/my-basepath/assets/image.jpg

Absolute URL

Prepend the url and base_path value to the input.

{{ "/assets/image.jpg" | absolute_url }}

http://example.com/my-basepath/assets/image.jpg

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.

{{ 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.

{{ 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. (Tip: You might want to try using the find tag instead.)

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

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.

{{ 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?

Obfuscate Link

Obfuscate emails, telephone numbers etc. The link text is replaced by a ciphered string (using the ROT47 algorithm, so numbers are included). On page load, this cipher is reversed, so the string is readable again. Takes an optional argument to specify the URI scheme prefix (default "mailto")

{{ "+1 234 567" | obfuscate_link:"tel" }}

Number of Words

Count the number of words in some text.

{{ page.content | number_of_words }}

1337

Reading Time

Returns the average number of minutes to read the supplied content. Based on 250 WPM but that can be changed using the reading_time_wpm configuration variable. You can also pass an argument to specify which decimal point to round to (defaults to 0 for no decimals).

{{ page.content | reading_time }} minutes

4 minutes

{{ page.content | reading_time: 1 }} minutes

3.2 minutes

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

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

Titleize

Transform a lowercase string, slug, or identifier string into a capitalized title.

{{ "to-kill-a-mockingbird" | titleize }}

To Kill A Mockingbird

{{ "as_easy_as_123" | titleize }}

As Easy As 123

{{ "working hard or hardly working" | titleize }}

Working Hard Or Hardly Working

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.collections.posts.resources | sort: "author" }}

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

Sample

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

{{ site.collections.pages.resources | sample }}

{{ site.collections.pages.resources | 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 }}

Options for the slugify filter #

The slugify filter accepts an option, each specifying what to filter. The default is pretty (unless the slugify_mode setting is changed in the site config). 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).

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 = collections.posts.resources | 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 = collections.posts.resources | 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:

{{ collections.movies.resources | 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:

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

Standard Liquid Filters #

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

Back to Template Engines