Find the right Liquid filter for your Jekyll data

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

Contents

• 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

• append
• capitalize
• downcase
• escape
• escape_once
• lstrip
• newline_to_br
• prepend
• remove
• remove_first
• replace
• replace_first
• rstrip
• size
• slice
• split: convert to an array
• strip
• strip_html
• strip_newlines
• truncate
• truncatewords
• upcase
• url_decode
• url_encode

Jekyll String Filters

Path

• absolute_url
• relative_url

Escaping

• cgi_escape
• uri_escape
• xml_escape

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

• date_to_xmlschema
• date_to_rfc822
• date_to_string
• date_to_long_string

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

Conclusion

It wasn't too hard to implement my feature after finding the relevant filters. It's the search that was time-consuming!

I hope this post helps you find what you need fast. Happy coding!

---

This is my first blog post! I'd love some feedback. Please let me know what you think in the comments.

Photo by Daniele Levis Pelusi on Unsplash

Comments

[Timo Sarkar]

Awesome! Thanks, this will definitely help me understanding liquid filters better!