Loading…

Liquid reference

A website's pages, layouts and snippets are Liquid templates, rendered by liquidjs on the server whenever a page is asked for.

This page lists everything a template can use: three objects, Liquid's tags and filters, and the tags and filters the site adds. Whatever isn't listed here isn't there; a template naming a filter that doesn't exist can't be published.

At a glance

Engine
liquidjs 10
Objects
site, request and route
Site’s own
asset_url and markdown filters, redirect and not_found tags
Dates
Read and shown in UTC
Escaping
None by itself: use escape

Liquid

Syntax

  • {{ … }} outputs a value, through any filters after |.
  • {% … %} is a tag: logic, loops, variables and other templates.
  • A - inside the braces, {%- or -}}, trims the whitespace on that side.
  • Compare with ==, !=, <, >, <=, >= and contains (text in text, or an item in an array), and join conditions with and and or.
  • Only false and nil are false: 0 and empty text are true. Compare with empty to test for an empty array or text.
  • (1..5) is a range of whole numbers; either end may be a variable.
  • Templates read only a value's own properties, and .size, .first and .last of arrays and text.
Syntax
{{ site.name | upcase }}       <!-- output -->
{% if site.data.posts %}…{% endif %}  <!-- a tag -->
{%- assign n = 3 -%}             <!-- trims whitespace -->
{% # a comment on one line %}
{% for i in (1..n) %}{{ i }}{% endfor %}  <!-- 123 -->

Objects

site

The website, the same on every page.

FieldIs
site.nameThe website’s name.
site.urlThe origin the page is served at, such as https://example.com: the site’s own address, a custom domain or its preview.
site.hostThe host alone, such as example.com.
site.dataEvery data template, by name: site.data.posts is the JSON of the data template posts (an empty one is nil).
site.pagesThe routes of the site’s HTML pages that answer one address each, such as / and /about: not /404, not routes with :param or *rest, not /feed.xml.
A list of every page
<ul>
{% for path in site.pages %}
  <li><a href="{{ path }}">{{ path }}</a></li>
{% endfor %}
</ul>

Objects

request

What the visitor asked for. Templates never see cookies or headers.

FieldIs
request.pathThe path asked for, such as /blog/hello.
request.hostThe host asked for.
request.urlThe whole address, origin and path, without the query.
request.queryThe query’s parameters, by name, each a string: request.query.page for ?page=2.

A site whose templates never mention request or query (beyond request.path, .host and .url) renders a page once for every query, so it's served faster.

Page /search
{% assign q = request.query.q | default: '' | strip %}
<h1>Results for “{{ q | escape }}”</h1>

Objects

route

The page answering, and what its route matched.

FieldIs
route.pathThe route of the page answering, such as /blog/:slug.
route.paramsWhat its :param and *rest segments took, by name: route.params.slug. A * with no name is route.params.splat.
Page /blog/:slug
<!-- Page /blog/:slug -->
{% assign post = site.data.posts | find: 'slug', route.params.slug %}
{% unless post %}{% not_found %}{% endunless %}
<h1>{{ post.title | escape }}</h1>
<time datetime="{{ post.date | date_to_xmlschema }}">
  {{ post.date | date: '%B %-d, %Y' }}
</time>
{{ post.body | markdown }}

Tags

Control flow

TagDoes
if, elsif, elseRenders the first branch whose condition holds.
unlessRenders when its condition doesn't hold, with an else if you like.
case, when, elseRenders the when whose value matches, any of several separated by commas or or.
Conditions
{% if post.tags contains 'news' and post.draft != true %}
  News
{% elsif post.tags.size > 0 %}
  {{ post.tags | join: ', ' }}
{% else %}
  Untagged
{% endif %}

{% case request.query.sort %}
  {% when 'new', 'newest' %}Newest first
  {% else %}Oldest first
{% endcase %}

Tags

Iteration

TagDoes
for … elseRenders once for each item of an array or range, or its else when there are none. Takes limit:, offset: and reversed.
break, continueLeaves the loop, or goes on to the next item.
forloopInside a loop: index and index0 (from 1 or 0), rindex and rindex0 (counting down), first, last and length.
cycleOutputs the next of its values each time, such as alternating row classes.
tablerowRenders table rows and cells, cols: to a row; tablerowloop holds col, row and the rest of forloop's.
A loop
{% for post in site.data.posts limit: 5 %}
  {% if post.draft %}{% continue %}{% endif %}
  <li class="{% cycle 'odd', 'even' %}">
    {{ forloop.index }}. {{ post.title }}
  </li>
{% else %}
  <li>No posts yet.</li>
{% endfor %}

Tags

Variables

TagDoes
assignSets a variable, filters and all.
captureSets a variable to what its block renders.
increment, decrementOutputs a counter of its own and steps it up (from 0) or down (from -1).
echoOutputs a value, as {{ }} does, for use in liquid.
liquidSeveral tags, one to a line, without their braces.
Variables
{% assign drafts = site.data.posts | where: 'draft', true %}
{% capture heading %}{{ drafts.size }} drafts{% endcapture %}
<h2>{{ heading }}</h2>
{%- liquid
  for post in drafts
    echo post.title | append: ' '
  endfor
-%}

Tags

Layouts and snippets

TagDoes
layoutDraws the page in a layout: {% layout 'default', title: 'About' %}. The variables after the name are the layout's to read; the page shows only what's inside its blocks.
blockIn a layout, a named place a page may fill, keeping the layout's own content if it doesn't. In a page, what fills it.
renderDraws a snippet with only what it's given: name: value, with value as name, or for array as name to draw it once for each. It sees site, request and route, but none of the variables around it.
includeDraws a snippet that shares every variable around it, and may change them.

Layouts and snippets are named by their template's name, folders included ({% render 'partials/nav' %}). They reach nothing else, and draw one another at most 50 deep.

A layout and a page
<!-- Layout default -->
<title>{{ title }} · {{ site.name }}</title>
<body>
  {% render 'header' %}
  {% block content %}{% endblock %}
</body>

<!-- Page /about -->
{% layout 'default', title: 'About' %}
{% block content %}
  <h1>About us</h1>
{% endblock %}
Snippets
{% render 'card', post: post %}
{% render 'card' for site.data.posts as post %}
{% render 'card' with site.data.posts.first as post %}
{% include 'header' %}

Tags

Redirects and not found

Two tags the site adds stop a page where they are and answer instead of it:

TagDoes
redirectSends the visitor to a path of the site (/new) or an http or https address, permanently (301) unless a status follows: 302, 307 or 308. The address is one line, up to 2,000 characters, and a value or variable rather than filters: assign one first.
not_foundAnswers with the site's /404 page, as an address nothing answers does: a /blog/:slug with no such post, say.
Redirects
<!-- Page /old-blog/*rest -->
{% assign to = '/blog/' | append: route.params.rest %}
{% redirect to %}

<!-- Page /shop -->
{% redirect 'https://shop.example.com', 302 %}

Tags

Raw and comments

TagDoes
rawOutputs its block as written, Liquid and all, such as a client-side template's braces.
commentRenders nothing of its block.
#A comment of one tag: {% # note %}.

Filters

Site filters

The two filters the site adds:

FilterDoes
asset_urlAn asset’s address by its contents, which browsers keep for good and which changes when the file does. The path may start with / or not; a path that is no asset is given back as it is.
{{ 'images/logo.png' | asset_url }}→/_assets/<sha256>/logo.png
markdownMarkdown to HTML: CommonMark with tables and strikethrough, bare addresses linked, and HTML in it kept.
{{ '# Hello *there*' | markdown }}→<h1>Hello <em>there</em></h1>
Assets and Markdown
<img src="{{ 'images/logo.png' | asset_url }}" alt="Acme">
<link rel="stylesheet" href="{{ 'site.css' | asset_url }}">

{{ site.data.about.body | markdown }}

Filters

Text

Filters change a value on its way out: {{ value | filter: argument, … }}. They chain left to right.

FilterDoes
append, prependAdds text after or before.
{{ 'a' | append: 'b' | prepend: 'c' }}→cab
capitalize, upcase, downcaseChanges case.
{{ 'hello world' | capitalize }}→Hello world
strip, lstrip, rstripRemoves whitespace from both ends, the start or the end.
{{ ' hi ' | strip }}→hi
strip_newlinesRemoves line breaks.
normalize_whitespace, squishCollapses runs of whitespace to one space; squish also strips both ends.
{{ ' a b ' | squish }}→a b
replace, replace_first, replace_lastReplaces every, the first or the last occurrence.
{{ 'banana' | replace_last: 'a', 'o' }}→banano
remove, remove_first, remove_lastRemoves every, the first or the last occurrence.
{{ 'banana' | remove_first: 'a' }}→bnana
truncateCuts to a length, ... included (or the text given second).
{{ 'The quick brown fox' | truncate: 12 }}→The quick...
truncatewordsCuts to a number of words.
{{ 'The quick brown fox jumps' | truncatewords: 3 }}→The quick brown...
splitSplits text into an array.
{{ 'a-b-c' | split: '-' | join: ', ' }}→a, b, c
sliceCharacters from an index, a number of them (or one).
{{ 'hello' | slice: 1, 3 }}→ell
slugifyLowercase words joined by hyphens, for an address.
{{ 'Hello, World!' | slugify }}→hello-world
number_of_wordsCounts words.
{{ 'one two three' | number_of_words }}→3
array_to_sentence_stringJoins an array as a sentence.
{{ 'a,b,c' | split: ',' | array_to_sentence_string }}→a, b, and c
sizeThe length of text or an array.

Filters

HTML and URLs

Output is not escaped for you: escape whatever a visitor can send, such as request.query and request.path, and any data you didn’t write.

FilterDoes
escape, xml_escapeEscapes <, >, &, " and '.
{{ '<b>Hi</b>' | escape }}→&lt;b&gt;Hi&lt;/b&gt;
escape_onceEscapes without escaping what already is.
strip_htmlRemoves tags.
{{ '<p>Hi</p>' | strip_html }}→Hi
newline_to_brPuts a <br /> before each line break.
url_encode, url_decodeEncodes or decodes for a query string.
{{ 'a b&c' | url_encode }}→a+b%26c
cgi_escape, uri_escapeEscapes for a query value, or for a whole address.
rawOutputs as it is.

Filters

Numbers

Numbers keep their decimals: 10 | divided_by: 4 is 2.5, unlike Shopify’s Liquid.

FilterDoes
plus, minus, timesAdds, subtracts, multiplies.
{{ 4 | plus: 2 }}→6
divided_byDivides. Pass true second for a whole number.
{{ 10 | divided_by: 4 }} {{ 10 | divided_by: 4, true }}→2.5 2
moduloThe remainder.
{{ 10 | modulo: 3 }}→1
round, ceil, floorRounds to a number of decimals (or a whole number), up or down.
{{ 3.14159 | round: 2 }}→3.14
absThe absolute value.
at_least, at_mostNo less, or no more, than a number.
{{ 3 | at_least: 5 }}→5
to_integerText to a whole number.
{{ '12' | to_integer | plus: 1 }}→13

Filters

Arrays

Most work on a data template’s arrays, or on site.pages. The examples read a data template posts of two posts, Hello and a draft, each with a slug, title, date, draft and tags.

FilterDoes
first, lastThe first or last item.
joinJoins items with text (a space unless given).
mapEach item’s property.
{{ site.data.posts | map: 'title' | join: ', ' }}→Hello, Draft
where, rejectItems whose property equals a value, or doesn’t (or is truthy, given no value).
{{ site.data.posts | where: 'draft', false | size }}→1
where_exp, reject_expItems an expression holds for.
{{ site.data.posts | where_exp: 'post', 'post.tags.size > 0' | map: 'slug' | join }}→hello
find, find_exp, find_index, find_index_expThe first item, or its index, whose property equals a value or an expression holds for.
{% assign post = site.data.posts | find: 'slug', route.params.slug %}
has, has_expWhether any item matches.
group_by, group_by_expGroups items by a property, each group with its name and items.
sort, sort_naturalSorts, by a property if given; sort_natural ignores case.
{% assign newest = site.data.posts | sort: 'date' | last %}
reverse, uniq, compactReverses, drops repeats, drops nils.
concat, push, unshift, pop, shiftJoins two arrays, or adds or removes an item at the end or the start.
sliceItems from an index, a number of them (or one).
sumAdds the items, or a property of each.
{{ '1,2,3' | split: ',' | sum }}→6
sampleA random item, or a number of them.
sizeHow many items.

Filters

Dates

Dates are read and shown in UTC, so a page renders alike on every server. A date is a timestamp, an ISO 8601 text or 'now'.

FilterDoes
dateFormats a date with strftime codes; 'now' is the time of the render.
{{ '2026-03-05T14:30:00Z' | date: '%b %-d, %Y %H:%M' }}→Mar 5, 2026 14:30
date_to_xmlschemaISO 8601, for feeds and <time>.
{{ '2026-03-05' | date_to_xmlschema }}→2026-03-05T00:00:00+00:00
date_to_rfc822RFC 822, for RSS.
{{ '2026-03-05' | date_to_rfc822 }}→Thu, 05 Mar 2026 00:00:00 +0000
date_to_string, date_to_long_stringShort and long day, month and year.
{{ '2026-03-05' | date_to_long_string }}→05 March 2026

Filters

Data and encoding

FilterDoes
defaultA value instead of nil, false or empty.
{{ request.query.page | default: 1 }}→1
json, jsonifyAs JSON.
{{ route.params | json }}
inspectAs JSON, for debugging.
base64_encode, base64_decodeBase64.
{{ 'abc' | base64_encode }}→YWJj
sha256, hmac_sha256A SHA-256 digest in hex, or an HMAC with the key given.

Reference

Limits and errors

  • Publishing checks first: every template is parsed and every page with a fixed route rendered. If any fails, nothing is published, and the template opens at the line that failed.
  • A page renders in at most 2 seconds and 64 MB, and outputs at most 10 MB.
  • A template is at most 200,000 characters, and a site holds at most 500 of them.
  • Data templates must be valid JSON.
  • A page that fails on a live site, such as a :param route given something its template didn't expect, answers with an error until it's fixed and published again.

Questions or something missing? Contact us.