Sylvie Fiquet

Posted on Nov 18, 2020

Find the right Liquid filter for your Jekyll data

#jekyll #liquid #webdev #codenewbie

Liquid filters are great for manipulating data. Finding the one you need in the documentation is another matter.

A few weeks ago I decided to use Jekyll to quickly build a prototype. On one of the pages I needed to combine data from two JSON files to create a hierarchical list. That's where it got tricky. I needed array manipulation filters but I spent more time looking for them in the documentations than actually implementing the feature.

Most filters are specific to a particular type of data: array, string, number, date. However this is not how the Liquid documentation or the Jekyll Filter page are structured. Instead filters are listed alphabetically (Liquid) or in some arbitrary order (Jekyll). In order to see what type of data they work on, you have to go through every single item in each list, and, in the case of Liquid, click on each one.

If only they could be listed by type of input...

Introduction
Array Filters
String Filters
Number Filters
Date Filters
Weakly Typed Filters
Side Note: Jekyll Tags
Conclusion

Introduction

Liquid filters: an overview

In Jekyll, posts and layouts are written in the Liquid template language. Liquid is characterised by three types of elements:

data, called objects
control flow structures, called tags
data transformation functions, called filters

This post focuses on filters.

When using Liquid in the context of Jekyll, you have access to Jekyll's custom filters in addition to the standard filters that come with Liquid.

If your needs are too specific, you can add new filters through library plugins or you can write your own in Ruby. This, however, is out of the scope of this article.

About this post

This post is based on the documentations for Jekyll 4.1.1 and Liquid 4.0.3.

All filters link to the relevant documentation, where you can find a full description of the filter with examples.

Array Filters

Liquid Array Filters

compact: remove nil values from array
concat: concatenates another array
first: returns the first item
join: converts array into a string with given separator
last: returns the last item
map: extracts the values for a given item property into a new array
reverse: reverse the order of the items
size: number of items
sort: case sensitive, can sort on item property
sort_natural: case insensitive version of sort
uniq: remove duplicate elements
where: filter an array of objects

Jekyll Array Filters

Array Queries

where: same as standard where
where_exp: combine conditionals to filter an array
find: get the first item matching the condition
find_exp: find with combined conditionals
group_by: group an array's items by a given property
group_by_exp: group_by with combined conditionals

Note that find and find_exp seem to have a bug. I don't know why but in my case they returned the whole array. Combining where with first instead of using find works well.

Array Manipulation

Those filters work on a copy of the input array.

push: adds an item at the end of the array
pop: returns the first element of the array
shift: returns the last element of the array
unshift: adds an item at the beginning of the array

Other Array Filters

array_to_sentence_string: converts array into a string, alternative output format to join
sample: pick one or more random values from an array
sort: like standard sort, with additional argument for whether to place nils first or last
See also jsonify and inspect in Jekyll Weakly Typed Filters below.

String Filters

Liquid String Filters

Jekyll String Filters

Path

Escaping

Other String Filters

markdownify: convert markdown to HTML
normalize_whitespace
number_of_words
sassify
slugify
smartify: convert "" to smart quotes “”
See also to_integer and inspect in Jekyll Weakly Typed Filters below.

Number Filters

Liquid Number Filters

abs
at_least
at_most
ceil: tries to convert input to number first
divided_by
floor
minus
modulo
plus
round
times

Jekyll Number Filters

There are no number-specific Jekyll filters.

Date Filters

Those filters format a date for output and return a string. Strictly speaking there is no date type in Liquid. The input to those filters is normally a timestamp.

Liquid Date Filters

date: convert date (timestamp or string) to string

Jekyll Date Filters

Weakly Typed Filters

Those filters accept more than one type of data as input.

Liquid Weakly Typed Filters

default: output a default value if the input is nil, false or empty

Jekyll Weakly Typed Filters

jsonify: convert a hash or array to a JSON string
to_integer: convert a string or boolean to an integer
inspect: convert any object to a string

Side Note: Jekyll Tags

In addition to filters, Jekyll also provides a few tags which might come in handy. They are also listed here for easy reference:

highlight: syntax highlighting with Rouge
include: include partial from the _includes folder
include_relative: include partial located with the current file (in the same directory or one of its subdirectories)
link: creates and validates site permalink url (build fails if url is wrong)
post_url: same as link but specific to posts so you don’t need to give the full path from the root