Skip to documentation content

Liquid Syntax

On this page

    Entry point to methods, objects, and filters and how they work together to render pages.

    Templates are made up of a combination of methods, objects (variables), and filters embedded inside markup. This markup is processed by the server using pre-defined input (the request, page, entity, and user objects) in order to render every page on the site.

    There are three types of markup in Liquid: Output, Methods, and Text

    Output Markup is surrounded by matching curly brackets ({{ and }}). When Output Markup is processed, it is evaluated and converted into a string which is output to the template.

    Method Markup is surrounded by matching method markup ({% and %}), and always starts with the name of the method to be evaluated. There are a large number of methods. Some methods control the flow of logic, some methods store and manipulate variables, and some methods output strings to the template. Each method also has its own syntax which defines how it should be used.

    All methods may be divided into two types of methods. Block methods have an open method markup and a close method markup (eg: {% if %}...{% endif %}), they change the way that content in between the open and close markup is handled, and most create a new child scope for variables. Inline methods do not have any closing markup and do not have any impact on other markup.

    Text Markup is everything that is not included inside Output or Method markup, and it is always output to the template.
    Example Use for_json when serializing to JSON (deprecation note)Use the for_json filter on variables that both do and do not have values
    Liquid
    {"something": {{'with "value"' | for_json}} }
{"something": {{null | for_json}} }
    Output
    {"something": "with \"value\""}
{"something": }

    The for_json filter works for input with valid values

    Liquid
    {"something": {{'with "value"' | for_json}} }
    Output
    {"something": "with \"value\""}

    The for_json filter does not produce output if the input is null

    Liquid
    {"something": {{null | for_json}} }
    Output
    {"something": }

    You can get away with the for_json filter by manually handling null/invalid values

    Liquid
    {"something": {% if variable is_valid %}{{variable | for_json}}{% else %}null{% endif %} }

    The entire for_json filter is deprecated because the json_encode filter handles this and other uses cases more robustly

    Liquid
    {"something": {{variable | json_encode }} }
    Example Case statement comparing custom field to stringUse case/when to compare a custom field value to multiple string options and branch accordingly.
    Liquid
    {%- case page.title_type.value -%}
	{%- when 'fullwidth' -%}
		<span class="fullwidth">This is full width title</span>
	{%- when 'halfwidth' or 'quarterwidth' -%}
		<span class="{{page.title_type.value}}">This is partial width title</span>
	{%- when "empty", "none", "null", "skip" -%}
		{%- comment %}No title{% endcomment -%}
	{%- else -%}
		This title does not have a span
{%- endcase -%}
    Example Use the comment tag to exclude markup from outputWrap content in comment tags so it is not rendered.
    Liquid
    {%- comment %}
<p>This text will not be output</p>
{% endcomment -%}
    Example Literal tagUse the literal tag to output Liquid-like syntax as plain text so it is not executed.
    Liquid
    <script id="mustache_template" type="text/template">{% literal -%}
	{{- object.name }} is {{ object.age }} years old
{%- endliteral %}</script>
    Example Capturing markup and passing it to an included templateCapture a block of markup with the capture tag and pass it to an included template as a variable.
    Liquid
    {%- capture blockContent -%}
	<div class="block-outer">
		<h3 class="block-title">
			{%- if article.default_page_url.is_valid -%}
				<a href="{{article.default_page_url.value}}">{{article.title}}</a>
			{%- else -%}
				{{-article.title-}}
			{%- endif -%}
		</h3>
		<div class="block-description">{{article.summary_html}}</div>
		<div class="block-footer">Posted {{article.post_date}}</div>
	</div>
{%- endcapture -%}
{%- include "_block_outer" content:blockContent -%}
    Example Dynamically render html tags using varBuild HTML tag names or markup in a variable and output them (e.g. with var and concatenation).
    Liquid
    <!-- This example uses a unicode variant of angle brackets (<>) to prevent the characters being escaped.
 You will want to replace the angle brackets if you intend to copy/paste this example. -->

{%- var tagtype = "div" -%}
〈{{tagtype}}〉
	{%- if true -%}
		{%- var tagtype = "span" -%}
		〈{{tagtype}}〉Some Content 〈/{{tagtype}}〉
	{%- endif -%}
〈/{{tagtype}}〉