Liquid Templating Crash Course

This is mostly here as a reference to remind myself of how this works on the rare occassions when I need to work on some Liquid templates and need to re-learn this. But it might be useful to someone else as well.

Liquid is a template language that was first developed for and is still used by Shopify, but it’s now open source and also used by Jekyll and many other projects. You can use Liquid templating in your Jekyll site’s layouts and includes, but you can also use it directly in posts or pages, which can be pretty handy (for example it’s used loads in the source code for this page).

Liquid is a bit of a weird template language. At least it is if you have a similar background to me: used to Python-world templating languages like Jinja2. As a result if you try to just use Liquid without taking the time out to properly learn it first, you’ll be frustrated.

The good news is that Liquid is a pretty small language, and more-or-less well-documented, so it is thoroughly learnable in an afternoon.

Weird Things about Liquid

Here’s a few of the unexpected things that threw me, before I took the time to learn Liquid properly:

Shopify’s Liquid docs contain a lot of Shopify-only stuff, and those are what often comes up in search results, which is confusing. To learn how to use Liquid effectively with GitHub Pages / Jekyll you need to read the Liquid docs, Jekyll’s docs and Liquid for Designers.
You can’t initialize your own arrays or hashes directly.

You can create new variables in Liquid templates and assign string, number, boolean or nil values to them. For example: {% assign my_string = "foo" %}. But there are no array or hash literals and no way to initialize a new array or hash.

There are oblique workarounds like splitting a string to create a new array of strings, or using various array processing filters to create new arrays, or using Jekyll’s front matter or data files to create your own arrays or hashes.

There’s no “not” (or !) operator. You do have unless (which is the opposite of if) and else, and !=, but there’s no not / !.
Truthiness doesn’t work how you expect it to: only false and nil are falsy, everything else is truthy including empty strings, empty arrays, and 0. If your if-statement doesn’t seem to be working this is probably why.
The order of operations in compound conditionals is fixed and you can’t use ( ... )‘s to control it. (...)‘s aren’t allowed in conditional expressions.
(You can choose to use nested ifs instead of compound ifs, though).
An explanation of hashes and how to use them is mysteriously missing from the documentation, which doesn’t even list hashes as one of the available types. See my section on hashes instead.
Jekyll’s site.categories and site.tags are a bit difficult to work with.

Objects, Tags and Filters

There are only three types of thing in a Liquid template: objects (variables that have types), tags (control flow, iteration, and variable assignment), and filters (functions that return new objects).

1. Objects, a.k.a Variables: `{{ ... }}`

These are references to variables, or sub-parts of variables in the case of hash or array access, that print out the referenced variable’s value.

All object references print something out into the rendered page, unless the variable’s value is nil or the empty string.

For example given a variable foo whose value is "bar" (a string), {% assign foo = “bar” %} this:

<p>{{ foo }}</p>

will output this:

<p>bar</p>

Each variable has a type. There are 6 types in Liquid:

Strings: "..." or '...' (there’s no difference between double and single quotes)
Numbers: 42 or 25.672
Booleans: true and false
nil
Arrays: lists of objects. The special object empty is shorthand for an empty array. For example {% if my_array == empty %} is equivalent to {% if my_array.size == 0 %}
Hashes: objects with multiple fields

2. Tags: `{% ... %}`

Tags implement control flow, iteration and variable assignments, among other things.

For example, {% if %} is one of the control flow tags. This if-statement will print out the value of the variable user if a variable named user exists and its value isn’t false or nil:

{% if user -%}
  The user is: {{ user }}
{%- else -%}
  There is no user.
{%- endif %}

Whitespace Control with {%- and -%}

The - characters in {%- and -%} are whitespace control. A {%- strips any leading whitespace from before the tag’s contents, in the rendered output. It strips spaces, tabs and newlines. -%} strips any trailing whitespace after the tag’s contents. They remove empty lines where the tags were from the rendered output. They can also remove the indentation (leading spaces) when the contents of tags are indented in the source file, but this only works when the tag only contains a single line, indentation from subsequent indented lines doesn’t seem to be stripped.

When there’s no user variable, or user‘s value is false or nil, the {% if %} tag above outputs:

There is no user.

When there is a user variable whose value is "fred" it outputs:

The user is: fred

3. Filters: `|`

Filters are functions that return new objects based on a given object. For example: doing string manipulations and returning new strings; doing array operations and returning new arrays; doing math and returning new numbers; formatting dates; and more. Filters are pure functions that always just compute and return a new object, they never modify a given object and never have any side effects. (But you can use {% assign %} to assign the new object returned by a filter to an existing variable name.)

upcase is a simple string manipulation filter that returns an ALL CAPS copy of a given string. This:

{{ "apple" | upcase }}

Outputs:

APPLE

append is another string manipulation filter that takes an additional parameter: the suffix string to append to the first string. This:

The file is: {{ "index" | append: ".html" }}

Outputs:

The file is: index.html

Filters can take multiple positional parameters, but there are no named parameters:

{{ "A long string to be truncated" | truncate: 24, ", and so on" }}

Outputs:

A long string, and so on

Filter parameters can be optional. For example truncate‘s second argument defaults to an ellipsis if omitted:

{{ "A long string to be truncated" | truncate: 24 }}

Outputs:

A long string to be t...

Finally, multiple filters can be chained together in a sequence like UNIX pipes:

{{ "adam!" | capitalize | prepend: "Hello " }}

Strings

String literals can use either 'single quotes' or "double quotes", there’s no difference.

There are lots of string manipulation filters:

See also: The complete list of all filters in the Liquid docs.

<STRING> | capitalize

a copy of a string with only the first character capitalized

<STRING> | downcase

an all-lowercase copy of a string

<STRING> | upcase

a copy of a string in ALL CAPS

<STRING> | lstrip

a copy of a string with leading whitespace removed

<STRING> | rstrip

a copy of a string with trailing whitespace removed

<STRING> | strip

a copy of a string with leading and trailing whitespace removed

<STRING> | strip_html

a copy of a string with HTML tags removed

<STRING> | strip_newlines

a copy of a string with line breaks removed

<STRING> | remove: "rain"

a copy of string with all occurrences of a substring removed

<STRING> | remove_first: "rain"

a copy of a string with the first occurrence of a substring removed

<STRING> | replace: "my", "your"

a copy of a string with all occurrences of the first argument replaced with the second argument

<STRING> | replace_first: "my", "your"

a copy of a string with the first occurrence of the first argument replaced with the second argument

<STRING> | newline_to_br

a copy of a string with all the \n‘s replaced with <br />‘s

<STRING> | escape

a URL-escaped copy of a string

<STRING> | escape_once

like escape but avoids double-escaping

<STRING> | url_encode

a copy of a string with any URL-unsafe characters percent-encoded

<STRING> | url_decode

a copy of a string with any percent-encoded characters decoded

<STRING> | append: ".html"

a new string by concatenating two strings

<STRING> | prepend: "prefix"

a copy of a string with a prefix string prepended onto the front

<STRING> | size

the number of characters in a string. Also works with arrays

<STRING> | slice: 0

<STRING> | slice: 2, 5

<STRING> | slice: -3, 2

a substring of a string

<STRING> | truncate: 25

<STRING> | truncate: 25, ", and so on"

a copy of a string truncated to the given number of characters, with an ellipsis appended if any characters had to be removed from the end. If the second argument is given it’s used instead of an ellipsis. Use "" for the second argument if you just don’t want any ellipsis.

<STRING> | truncatewords: 3

<STRING> | truncatewords: 3, "--"

a copy of a string truncated to the given number of words.

<STRING> | split: ", "

an array of substrings by splitting a string on the given substring. You can also join an array of substrings into a single string with the |join filter, which works on arrays

There’s no filter for reversing a string, but you can do it by first splitting it into a character array, then reversing the array, then joining the array back into a string: {{ <STRING> | split: "" | reverse | join: "" }}

<TIMESTAMP_STRING> | date: "<STRFTIME_FORMAT>"

a copy of a timestamp string, formatted according to the given strftime format string. Jekyll also adds a lot more date formatting filters

Numbers

Number literals can be either integers: 25, or floats: 39.756.

There are lots of filters for manipulating numbers:

See also: The complete list of all filters in the Liquid docs.

<NUMBER> | abs: the absolute value of a number
<NUMBER> | round
<NUMBER> | round: 2: a copy of a number, rounded to the nearest integer or to a given number of decimal places
<NUMBER> | at_least: 5: a copy of a number, clamped to a given minimum value
<NUMBER> | at_most: 5: a copy of a number, clamped to a given maximum value
<NUMBER> | floor: a copy of a number, rounded down to the nearest whole number
<NUMBER> | ceil: a copy of a number, rounded up to the nearest whole number
<NUMBER> | plus: 2: a copy of a number by adding a given number to it
<NUMBER> | minus: 2: a copy of a number by subtracting a given number from it
<NUMBER> | times: 2: a copy of a number by multiplying it by a given number
<NUMBER> | divided_by: 4: a copy of a number by dividing it by a given number
<NUMBER> | modulo: 2: a new number by taking the remainder from dividing a number by a given number

Arrays

Hashes

They’re missing from the documentation, but Liquid also has hashes: objects with multiple named fields. Jekyll passes several hashes into your templates, for example:

site is an object containing site-wide information and settings from your _config.yml file
page is an object containing page-specific information and metadata from the page’s YAML front matter
layout is an object containing layout-specific information and metadata from the layout’s YAML front matter
site.pages is an array of objects, one for each page on your site
site.posts is an array of objects, one for each post on your site
On GitHub Pages site.github is an object containing all sorts of GitHub Pages-specific metadata about the site

The main thing you can do with hashes is access their attributes using . or [] notation. For example here’s some code that prints out some common Jekyll site attributes:

Site title: {{ site.title }}
Site description: {{ site.description }}
Site base URL: {{ site.baseurl }}
Site last updated at: {{ site.time }}

This outputs:

Site title: seanh.cc
Site description: 
Site base URL: 
Site last updated at: 2023-08-05 13:59:13 +0000

You can also access object attributes using ["string"] notation, which works even if the key has a space in it. For example here’s some code that prints out a bunch of Jekyll’s page attributes:

Page title: {{ page["title"] }}
Beginning of page content: {{ page["content"] | truncate }}
Page URL: {{ page["url"] }}

This outputs:

Page title: Liquid Templating Crash Course
Beginning of page content: This is mostly here as a reference to remind my...
Page URL: /2019/09/29/liquid/

You can also put a string variable or an expression that resolves to a string in []‘s, for example:

{% assign tag = "Jekyll" %}
Number of posts tagged "{{ tag }}": {{ site.tags[tag].size }}

You can loop over a hash with {% for %} and it loops over the hash’s keys:

{% for key in site.github limit:3 -%}
  {{ key }}: {{ site.github[key] }}
{% endfor %}

Output:

api_url: https://api.github.com
archived: false
baseurl:

Trying to access an attribute that doesn’t exist returns nil, which is falsey. For example this page has an attribute does_exist: true in its Jekyll front matter, but it doesn’t have any attribute named doesnt_exist. Given this code:

{% if page.does_exist -%}
  The does_exist attribute does exist
{%- endif %}

{% if page.doesnt_exist -%}
  This won't be printed out
{%- else -%}
  The doesnt_exist attribute doesn't exist
{%- endif %}

{% if page.doesnt_exist == nil -%}
  The doesnt_exist attribute is nil
{%- endif %}

You get this output:

The does_exist attribute does exist

The doesnt_exist attribute doesn't exist

The doesnt_exist attribute is nil

As far as I know there’s no way to create your own hashes in pure Liquid. But you can create them in the YAML front matter at the top of the file. This is a Jekyll feature, not a Liquid feature. For example:

---
my_hash:
  some_attr: some_value
  another_attr: 23
---

Jekyll then makes my_hash available as page.my_hash. For example {{ page.my_hash.some_attr }} would render {{ page.my_hash.some_attr }}.

A hash in the layout’s front matter (available on the layout variable) or in _config.yml (available on the site variable) would also work.

Jekyll’s data files would be another way to create your own hashes.

Variable Assignment Tags: `{% assign %}`, `{% capture %}`, `{% increment %}` and `{% decrement %}`

Control Flow Tags: `{% if %}`, `{% unless %}` and `{% case %}`

`{% if %}`, `{% else %}` and `{% elsif %}`

{% if %} is the basic control flow tag in Liquid, along with its helper tags {% else %} (which also works with for loops, see below) and {% elsif %}. Examples:

{% if page.categories == empty -%}
  This page has no categories.
{%- endif %}

{% if page.draft == true -%}
  This page is a draft.
{%- else -%}
  This page is not a draft.
{%- endif %}

{% assign num_apples = 4 -%}
{% if num_apples > 5 -%}
  There are lots of apples.
{%- elsif num_apples > 3 -%}
  There are several apples.
{%- elsif num_apples > 0 -%}
  There are a few apples.
{%- else -%}
  There are no apples.
{%- endif %}

Outputs:

This page has no categories.

This page is not a draft.

There are several apples.

Control Flow Operators

`{% unless %}`

{% unless %} is a convenience that’s the same as using {% if %} with != instead of ==. {% unless product.title == "Awesome Shoes" %} ... {% endunless %} is equivalent to {% if product.title != "Awesome Shoes" %} ... {% endunless %}. {% else %} and {% elsif %} work with {% unless %} the same as they work with {% if %}.

`{% case %}` and `{% when %}`

{% case %}/{% when %} is a convenience for when you’d otherwise have to write a repetitive {% if %}/{% elsif %} block testing multiple different values of the same variable. A {% case %} can have an {% else %} on the end just like an {% if %}/{% elsif %} can. Here’s the example from the Liquid docs:

{% case handle %}
  {% when "cake" %}
     This is a cake
  {% when "cookie" %}
     This is a cookie
  {% else %}
     This is not a cake nor a cookie
{% endcase %}

Iteration Tags: `{% for %}`, `{% cycle %}` and `{% tablerow %}`

For loop over an array

To loop over an array of strings:

{%- assign items = "first item, second item, third item" | split: ", " %}
<ol>
{%- for item in items %}
  <li>{{ item }}</li>
{%- endfor %}
</ol>

Outputs:

<ol>
  <li>first item</li>
  <li>second item</li>
  <li>third item</li>
</ol>

For loop over a hash

Looping over a hash seems to loop over the keys of the hash. For example in Jekyll the page variable is a hash of page-specific information and YAML front matter. Looping over page like this:

<ol>
{%- for item in page %}
  <li>{{ item }}: {{ page[item] | truncate: 20 }}</li>
{%- endfor %}
</ol>

Outputs this:

<ol>
  <li>content: This is mostly he...</li>
  <li>output: </li>
  <li>id: /2019/09/29/liquid</li>
  <li>url: /2019/09/29/liquid/</li>
  <li>next: Breadcrumbs help ...</li>
  <li>previous: <!DOCTYPE html>
<...</li>
  <li>path: _posts/2019-09-29...</li>
  <li>relative_path: _posts/2019-09-29...</li>
  <li>excerpt: <p>This is mostly...</li>
  <li>collection: posts</li>
  <li>draft: false</li>
  <li>categories: []</li>
  <li>subtitle: My Liquid templat...</li>
  <li>does_exist: true</li>
  <li>foo: bar</li>
  <li>my_array: [6, "five", 3.2]</li>
  <li>my_hash: {"some_attr"=>"so...</li>
  <li>tags: ["Jekyll"]</li>
  <li>date: 2019-09-29 00:00:...</li>
  <li>title: Liquid Templating...</li>
  <li>slug: liquid</li>
  <li>ext: .md</li>
  <li>layout: post</li>
</ol>

For loop over a range of numbers

(n..m) is a special syntax for creating a range of integers for a for loop. n and m can either be literal numbers or variables whose values are numbers. Examples:

{% for i in (3..5) %}
  {{ i }}
{% endfor %}

{% assign num = 4 %}
{% for i in (1..num) %}
  {{ i }}
{% endfor %}

`{% else %}` tags on for loops

An {% else %} tag in a {% for %} loop specifies an alternative block to be rendered if the array is empty:

{%- assign items = empty %}
<ol>
{%- for item in items %}
  <li>{{ item }}</li>
{%- else %}
  The list is empty.
{%- endfor %}
</ol>

Outputs:

<ol>
  The list is empty.
</ol>

`{% break %}` and `{% continue %}`

A {% break %} tag breaks out of a for loop, and a {% continue %} jumps to the next iteration, as you would expect. You’d normally use these in an {% if %} within a {% for %}, of course:

{% for item in items %}
  {% if should_stop_looping %}
    {% break %}
  {% elsif should_skip_item %}
    {% continue %}
  {% else %}
    ...
  {% endif %}
{% endfor %}

`limit`, `offset` and `reversed` parameters

{% for %} can accept three parameters limit, offset and reversed. This:

{%- for i in (1..10) reversed limit:3 offset:2 %}
{{ i }}
{%- endfor %}

Outputs this:

5
4
3

When passing multiple parameters to a tag like {% for %} the ordering of the parameters can be tricky: flags have to come before parameters with values. reversed is a flag: a parameter that doesn’t take a value, whereas limit and offset are parameters that require values. When passing multiple parameters to a tag, any flag parameters have to be listed before any parameters with values. Other than that the order of parameters doesn’t make any difference. These are equivalent:

{% for i in (1..10) reversed limit:3 offset:2 %}
{% for i in (1..10) reversed offset:2 limit:3 %}

But these don’t work because reversed has no effect if it isn’t listed before the parameters with values:

{% for i in (1..10) limit:3 reversed offset:2 %}
{% for i in (1..10) limit:3 offset:2 reversed %}

for loop helper variables

See also: The forloop object in Shopify’s Liquid docs.

Several special helper variables are available inside a for loop:

forloop.length: The total number of items being looped over.
forloop.index: The current index of the for loop. Starts at 1.
forloop.index0: The current index of the for loop. Starts at 0.
forloop.rindex: forloop.index but in reverse order.
forloop.rindex0: forloop.index0 but in reverse order.
forloop.first: true if this is the first iteration.
forloop.last: true if this is the last iteration.

`{% cycle %}` and `{% tablerow %}`

Finally, the {% cycle %} tag is a convenience for generating alternating or looping values within a loop (for example alternating or cycling between two or more colours or odd/even classes in a list), and the {% tablerow %} tag is a convenience for generating HTML tables. See the Liquid docs for how to use these.

Miscellaneous Filters

Filters that don’t fit under strings, numbers or arrays:

See also: The complete list of all filters in the Liquid docs.

<OBJECT> | default: <FALLBACK_VALUE>: Either returns <OBJECT> or, if <OBJECT> is false, nil or empty, returns <FALLBACK_VALUE> instead

Comments

Comments can be entered using the {% comment %} tag:

Jekyll Liquid

Jekyll adds custom filters, custom tags, global variables, a very important {% include %} tag, and template inheritance (“layouts”) on top of standard Liquid:

Jekyll’s `{% link %}` and `{% post_url %}`

Jekyll’s includes

See also: Jekyll’s docs on Includes and Liquid’s docs on capture.

Includes are a way of compartmentalizing your templates into lots of small, reusable templates. It’s a good idea to use as many of these as possible. The basic idea is that you create a snippet of Liquid, HTML and Markdown (Kramdown) code in an _includes/foo.html file and then include that code in another template, page or post whenever you want it with {% include foo.html %}.

There’s also {% include_relative %} which searches for an include file relative to the location of the current file, instead of looking in the global _includes/ directory.

You can pass one or more parameters into an include:

{% include my_include.html foo="foo" bar="bar" %}

These are then available in my_include.html as {{ include.foo }} and {{ include.bar }}.

Optional include parameters can be implemented by using if-statements like {% if include.foo %} ... {% else %} ... {% endif %}, or by using the |default filter.

Captures are often useful when passing parameters into includes.

Jekyll’s `site.categories` and `site.tags`

See also: Jekyll’s docs on Categories and Tags (includes a for-loop similar to the one below for listing all posts by category).

Jekyll’s site.categories and site.tags are arrays of arrays, one subarray for each category or tag, where each category or tag subarray contains two elements: [0]: the name of the category or tag (a string), and [1]: a subsubarray containing all the posts (post objects with various fields) with that category or tag:

The structure of site.categories looks something like this (and site.tags is the same):

[
  [
    "<name of first category>",
    [
      {
        "title": "<title of first post in category>",
        "url": "<URL of first post in category>",
        ...
      },
      {
        "title": "<title of second post in category>",
        "url": "<URL of third post in category>",
        ...
      },
      ...
    ],
  ],
  [
    "<name of second category>",
    [
      {<first post in category>},
      {<second post in category>},
    ],
  ],
  ...
]

For example here’s some code to loop over all of a site’s tags and, for each tag, print out a list of links to all of the posts with that tag:

<ul>
  {% for tag in site.tags %}
    <li>
      <p>{{ tag[0] }}:</p> <!-- The name of the tag. -->
      <ol>
        {% for post in tag[1] %} <!-- Loop over all of the tag's posts. -->
          <li>
            <a href="{{ post.url | absolute_url }}">
              {{ post.title }}
            </a>
          </li>
        {% endfor %}
      </ol>
    </li>
  {% endfor %}
</ul>

As well as looping over them, you can also access individual tags or categories by name:

The "Jekyll" tag has {{ site.tags.Jekyll.size }} posts.

{% for post in site.tags.Jekyll limit:3 %}
  {{ post.title }}
{% endfor %}

Arbitrary front matter are available as variables

See also: Front Matter in Jekyll’s docs.

You can put arbitrary key/value pairs in the YAML front matter at the top of a page or post file and Jekyll makes them available as attributes of the page object.

For example given this YAML front matter at the top of a page or post file:

---
foo: bar
---

You could do this to render “bar”:

{{ page.foo }}

You can also put key/value pairs in the front matter of layout files, and Jekyll makes them available as attributes of the global variable layout.

Arbitrary config settings are available as variables

See also: Configuration in Jekyll’s docs.

You can put arbitrary key/value pairs in your site’s _config.yml file and Jekyll makes them available as attributes of the global variable site. For example given this line on _config.yml:

foo: bar

You could do this to render “bar”:

{{ site.foo }}

YAML, JSON, CSV and TSV files in `_data` are accessible as variables

You can put YAML, JSON, CSV and TSV files in a _data folder and Jekyll makes them all available as attributes of a site.data object. See Data Files in the Jekyll docs.

With Jekyll you can also create variables for templates to use in YAML front matter, in the config file, or in data files. ↩

Liquid Templating Crash Course

Weird Things about Liquid

Objects, Tags and Filters

1. Objects, a.k.a Variables: {{ ... }}

2. Tags: {% ... %}

3. Filters: |

Strings

Numbers

Arrays

Hashes

Variable Assignment Tags: {% assign %}, {% capture %}, {% increment %} and {% decrement %}

Control Flow Tags: {% if %}, {% unless %} and {% case %}

{% if %}, {% else %} and {% elsif %}

Control Flow Operators

{% unless %}

{% case %} and {% when %}

Iteration Tags: {% for %}, {% cycle %} and {% tablerow %}

For loop over an array

For loop over a hash

For loop over a range of numbers

{% else %} tags on for loops

{% break %} and {% continue %}

limit, offset and reversed parameters

for loop helper variables

{% cycle %} and {% tablerow %}

Miscellaneous Filters

Comments

Jekyll Liquid

Jekyll’s {% link %} and {% post_url %}

Jekyll’s includes

Jekyll’s site.categories and site.tags

Arbitrary front matter are available as variables

Arbitrary config settings are available as variables

YAML, JSON, CSV and TSV files in _data are accessible as variables

1. Objects, a.k.a Variables: `{{ ... }}`

2. Tags: `{% ... %}`

3. Filters: `|`

Variable Assignment Tags: `{% assign %}`, `{% capture %}`, `{% increment %}` and `{% decrement %}`

Control Flow Tags: `{% if %}`, `{% unless %}` and `{% case %}`

`{% if %}`, `{% else %}` and `{% elsif %}`

`{% unless %}`

`{% case %}` and `{% when %}`

Iteration Tags: `{% for %}`, `{% cycle %}` and `{% tablerow %}`

`{% else %}` tags on for loops

`{% break %}` and `{% continue %}`

`limit`, `offset` and `reversed` parameters

`{% cycle %}` and `{% tablerow %}`

Jekyll’s `{% link %}` and `{% post_url %}`

Jekyll’s `site.categories` and `site.tags`

YAML, JSON, CSV and TSV files in `_data` are accessible as variables