Language Basics

Basic concepts of Liquid, the templating language that powers Live Editor layouts and content templates.

Syntax

Liquid looks similar to many common web scripting languages. Generally speaking, it is mixed in with regular HTML documents to add logic and to output data.

There are 2 main types of Liquid markup that you’ll be working with: output and tags.

Output

Double curly braces surround any logic or values that you would like to output onto the page:

The title of this page is {{ page_title }}.

You typically will be outputting values from objects, sometimes using filters. (See below for general examples of objects and filters.)

Tags

Tag markup does not output anything but allows you to code logic into your templates (e.g., if/else blocks, loops, variable assignment, etc.). Tags are surrounded by matched pairs of curly brackets and percent signs:

      {% unless page_title == 'Home' %}
        {{ page_title }}
      {% endunless %}
      

This is a complete list of tags available within Live Editor Liquid templates in the Liquid Tag Reference.

Variable assignment

There are 2 tags available for assigning variables for use within your templates: assign and capture.

The assign tag is your standard one-line assignment statement:

{% assign x = 5 %}

The capture tag allows you to capture a value from multiple lines.

      {% capture lyrics %}
        You can't avoid her
        She's in the air
        In between molecules
        Of oxygen and carbon dioxide
      {% endcapture %}
      

Operators

Liquid in Live Editor provides you with all of the operators that you would expect from a scripting language.

Examples

Test that 2 values are equal:

      {% if link.title == 'Special' %}
        <span class="badge-special">
          Special
        </span>
      {% endif %}
      

Chain multiple expressions together:

      {% if current_page.home? or current_page.path == '/test-home' %}
        <h1>{{ site.title }}</h1>
      {% endif %}
      

Check for the presence of a substring inside of a string:

      {% assign word_of_the_day = 'New' %}
      
      {% if title contains word_of_the_day %}
        <p>
          You've triggered the word of the day:
          <strong>{{ word_of_the_day }}</strong>!
        </p>
      {% endif %}
      

Data Types

Liquid objects and variables will return 1 of 5 types: string, number, boolean, nil, or array.

string

A string is a sequence of characters. Strings are declared by wrapping the variable’s value in single or double quotes.

      {% assign a_string = 'Oneness' %}
      {% assign b_string = "Doubleness" %}
      

number

Numbers include floats/decimals and integers.

      {% assign my_num = 3 %}
      {% assign your_num = 26.2 %}
      

boolean

Booleans are either true or false. No quotations are necessary when declaring a boolean.

      {% assign foo = true %}
      {% assign bar = false %}
      

nil

nil is an empty value. If a variable or object’s attribute holds nothing or is not present, Liquid will return nil.

When within an output, nil will not display anything on the screen. nil also evaluates to false.

array

An array is a collection of values of any type.

You often will access the items in an array by looping through it with a for loop tag.

One common array that you’ll work with is the navigation.links array within a navigation template. Pretend that this example contains 4 links to “Home,” “Products,” “About Us,” and “Contact Us”:

      <ul>
        {% for link in navigation.links %}
          <li>{{ link.title }}</li>
        {% endfor %}
      </ul>
      

      <ul>
        <li>Home</li>
        <li>Products</li>
        <li>About Us</li>
        <li>Contact Us</li>
      </ul>
      

You can access an individual item in the array using square bracket notation and the item’s index. (The first item in the list has an index of 0.)

Here is the same example from above using indexes to access the links directly:

      <ul>
        <li>{{ navigation.links[0].title }}</li>
        <li>{{ navigation.links[1].title }}</li>
        <li>{{ navigation.links[2].title }}</li>
        <li>{{ navigation.links[3].title }}</li>
      </ul>
      

      <ul>
        <li>Home</li>
        <li>Products</li>
        <li>About Us</li>
        <li>Contact Us</li>
      </ul>
      

Evaluating booleans

All values in Liquid evaluate to true, except for nil and false.

This means that all values would pass the test in an if statement unless their value was false or nil.

      {% if num_hats %}
        This displays, even if the value is 0.
      {% endif %}
      
      {% if num_hats > 0 %}
        This doesn't display if the value is
        less than or equal to 0.
      {% endif %}
      

      {% if greeting %}
        This displays, even if greeting
        holds an empty string.
      {% endif %}
      
      {% if greeting.size > 0 %}
        This doesn't display if greeting
        holds an empty string.
      {% endif %}
      

Lastly, if an object doesn’t exist, it will return nil, which will evaluate to false. The same goes if an object’s attribute has an empty value.

      {% if photo %}
        This will not display.
      {% endif %}
      

      {% if link.url %}
        This will not display.
      {% endif %}
      

Cutting straight to the chase, here are how different kinds of values evaluate in Liquid:

Next steps

Dive deeper into Liquid by learning about using tags for logic and control flow in the Tags Reference.