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
site, request and routeasset_url and markdown filters, redirect and not_found tagsescapeLiquid
{{ … }} outputs a value, through any filters after |.{% … %} is a tag: logic, loops, variables and other templates.- inside the braces, {%- or -}}, trims the whitespace on that side.==, !=, <, >, <=, >= and contains (text in text, or an item in an array), and join conditions with and and or.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..size, .first and .last of arrays and text.{{ 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
The website, the same on every page.
| Field | Is |
|---|---|
site.name | The website’s name. |
site.url | The origin the page is served at, such as https://example.com: the site’s own address, a custom domain or its preview. |
site.host | The host alone, such as example.com. |
site.data | Every data template, by name: site.data.posts is the JSON of the data template posts (an empty one is nil). |
site.pages | The 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. |
<ul>
{% for path in site.pages %}
<li><a href="{{ path }}">{{ path }}</a></li>
{% endfor %}
</ul>Objects
What the visitor asked for. Templates never see cookies or headers.
| Field | Is |
|---|---|
request.path | The path asked for, such as /blog/hello. |
request.host | The host asked for. |
request.url | The whole address, origin and path, without the query. |
request.query | The 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.
{% assign q = request.query.q | default: '' | strip %}
<h1>Results for “{{ q | escape }}”</h1>Objects
The page answering, and what its route matched.
| Field | Is |
|---|---|
route.path | The route of the page answering, such as /blog/:slug. |
route.params | What its :param and *rest segments took, by name: route.params.slug. A * with no name is route.params.splat. |
<!-- 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
| Tag | Does |
|---|---|
if, elsif, else | Renders the first branch whose condition holds. |
unless | Renders when its condition doesn't hold, with an else if you like. |
case, when, else | Renders the when whose value matches, any of several separated by commas or or. |
{% 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
| Tag | Does |
|---|---|
for … else | Renders once for each item of an array or range, or its else when there are none. Takes limit:, offset: and reversed. |
break, continue | Leaves the loop, or goes on to the next item. |
forloop | Inside a loop: index and index0 (from 1 or 0), rindex and rindex0 (counting down), first, last and length. |
cycle | Outputs the next of its values each time, such as alternating row classes. |
tablerow | Renders table rows and cells, cols: to a row; tablerowloop holds col, row and the rest of forloop's. |
{% 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
| Tag | Does |
|---|---|
assign | Sets a variable, filters and all. |
capture | Sets a variable to what its block renders. |
increment, decrement | Outputs a counter of its own and steps it up (from 0) or down (from -1). |
echo | Outputs a value, as {{ }} does, for use in liquid. |
liquid | Several tags, one to a line, without their braces. |
{% 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
| Tag | Does |
|---|---|
layout | Draws 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. |
block | In 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. |
render | Draws 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. |
include | Draws 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.
<!-- 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 %}{% render 'card', post: post %}
{% render 'card' for site.data.posts as post %}
{% render 'card' with site.data.posts.first as post %}
{% include 'header' %}Filters
The two filters the site adds:
| Filter | Does |
|---|---|
asset_url | An 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 |
markdown | Markdown to HTML: CommonMark with tables and strikethrough, bare addresses linked, and HTML in it kept.{{ '# Hello *there*' | markdown }}→<h1>Hello <em>there</em></h1> |
<img src="{{ 'images/logo.png' | asset_url }}" alt="Acme">
<link rel="stylesheet" href="{{ 'site.css' | asset_url }}">
{{ site.data.about.body | markdown }}Filters
Filters change a value on its way out: {{ value | filter: argument, … }}. They chain left to right.
| Filter | Does |
|---|---|
append, prepend | Adds text after or before.{{ 'a' | append: 'b' | prepend: 'c' }}→cab |
capitalize, upcase, downcase | Changes case.{{ 'hello world' | capitalize }}→Hello world |
strip, lstrip, rstrip | Removes whitespace from both ends, the start or the end.{{ ' hi ' | strip }}→hi |
strip_newlines | Removes line breaks. |
normalize_whitespace, squish | Collapses runs of whitespace to one space; squish also strips both ends.{{ ' a b ' | squish }}→a b |
replace, replace_first, replace_last | Replaces every, the first or the last occurrence.{{ 'banana' | replace_last: 'a', 'o' }}→banano |
remove, remove_first, remove_last | Removes every, the first or the last occurrence.{{ 'banana' | remove_first: 'a' }}→bnana |
truncate | Cuts to a length, ... included (or the text given second).{{ 'The quick brown fox' | truncate: 12 }}→The quick... |
truncatewords | Cuts to a number of words.{{ 'The quick brown fox jumps' | truncatewords: 3 }}→The quick brown... |
split | Splits text into an array.{{ 'a-b-c' | split: '-' | join: ', ' }}→a, b, c |
slice | Characters from an index, a number of them (or one).{{ 'hello' | slice: 1, 3 }}→ell |
slugify | Lowercase words joined by hyphens, for an address.{{ 'Hello, World!' | slugify }}→hello-world |
number_of_words | Counts words.{{ 'one two three' | number_of_words }}→3 |
array_to_sentence_string | Joins an array as a sentence.{{ 'a,b,c' | split: ',' | array_to_sentence_string }}→a, b, and c |
size | The length of text or an array. |
Filters
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.
| Filter | Does |
|---|---|
escape, xml_escape | Escapes <, >, &, " and '.{{ '<b>Hi</b>' | escape }}→<b>Hi</b> |
escape_once | Escapes without escaping what already is. |
strip_html | Removes tags.{{ '<p>Hi</p>' | strip_html }}→Hi |
newline_to_br | Puts a <br /> before each line break. |
url_encode, url_decode | Encodes or decodes for a query string.{{ 'a b&c' | url_encode }}→a+b%26c |
cgi_escape, uri_escape | Escapes for a query value, or for a whole address. |
raw | Outputs as it is. |
Filters
Numbers keep their decimals: 10 | divided_by: 4 is 2.5, unlike Shopify’s Liquid.
| Filter | Does |
|---|---|
plus, minus, times | Adds, subtracts, multiplies.{{ 4 | plus: 2 }}→6 |
divided_by | Divides. Pass true second for a whole number.{{ 10 | divided_by: 4 }} {{ 10 | divided_by: 4, true }}→2.5 2 |
modulo | The remainder.{{ 10 | modulo: 3 }}→1 |
round, ceil, floor | Rounds to a number of decimals (or a whole number), up or down.{{ 3.14159 | round: 2 }}→3.14 |
abs | The absolute value. |
at_least, at_most | No less, or no more, than a number.{{ 3 | at_least: 5 }}→5 |
to_integer | Text to a whole number.{{ '12' | to_integer | plus: 1 }}→13 |
Filters
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.
| Filter | Does |
|---|---|
first, last | The first or last item. |
join | Joins items with text (a space unless given). |
map | Each item’s property.{{ site.data.posts | map: 'title' | join: ', ' }}→Hello, Draft |
where, reject | Items 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_exp | Items 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_exp | The 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_exp | Whether any item matches. |
group_by, group_by_exp | Groups items by a property, each group with its name and items. |
sort, sort_natural | Sorts, by a property if given; sort_natural ignores case.{% assign newest = site.data.posts | sort: 'date' | last %} |
reverse, uniq, compact | Reverses, drops repeats, drops nils. |
concat, push, unshift, pop, shift | Joins two arrays, or adds or removes an item at the end or the start. |
slice | Items from an index, a number of them (or one). |
sum | Adds the items, or a property of each.{{ '1,2,3' | split: ',' | sum }}→6 |
sample | A random item, or a number of them. |
size | How many items. |
Filters
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'.
| Filter | Does |
|---|---|
date | Formats 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_xmlschema | ISO 8601, for feeds and <time>.{{ '2026-03-05' | date_to_xmlschema }}→2026-03-05T00:00:00+00:00 |
date_to_rfc822 | RFC 822, for RSS.{{ '2026-03-05' | date_to_rfc822 }}→Thu, 05 Mar 2026 00:00:00 +0000 |
date_to_string, date_to_long_string | Short and long day, month and year.{{ '2026-03-05' | date_to_long_string }}→05 March 2026 |
Filters
| Filter | Does |
|---|---|
default | A value instead of nil, false or empty.{{ request.query.page | default: 1 }}→1 |
json, jsonify | As JSON.{{ route.params | json }} |
inspect | As JSON, for debugging. |
base64_encode, base64_decode | Base64.{{ 'abc' | base64_encode }}→YWJj |
sha256, hmac_sha256 | A SHA-256 digest in hex, or an HMAC with the key given. |
Reference
: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.