How to use Liquid Syntax in Jekyll?

Nov 06, 2016 - sharathdt

Liquid Syntax is an open-source template language created by Shopify. Jekyll uses it to load data dynamically, access data across the site, implement conditional logics like if, for, case etc.,

For a beginner, this might look like an alien programming which doesn’t resemble any of the programming languages that he/she may have seen before.

But I assure you that it is probably the simplest and comprehensive language that I have seen so far. Take this snippet for example,

{% if age >= 18 %}
  You're allowed to drink beer!
{% else %}
  You are a minor!
{% endif %}

So simple isn’t it. I wish other programs were also this easy and did not make a fuss whenever I miss a semicolon.

Let’s begin learning Liquid keeping Jekyll in mind. There are 3 things that we should know before we jump right in.

Tags Objects Filters
{% %} {{ }} {{  | }}
Conditions Output Modify Output


Tags are functional. They usually tell what to do and how to do something. They are used to implement control flows, iterations etc., The best example for this would be the one I have mentioned above - legal age for drinking beer.

Along with conditional statements, tags are also used for special purposes like including a file from _includes folders. I have also discussed it here.

{% include head.html %}
{% include header.html %}
{% include footer.html %}

These statements will look for the files head.html, header.html and footer.html and insert them in the places where the tags are defined. I have discussed this here as well.

Liquid tags and objects may not work on a page if you have not defined front matter in it. At least blank front matter like this


Objects are used to output dynamic data on a page. In Jekyll, we have front matter title for almost all pages and posts. This can be accessed inside that page or post using the following object,


Here is the output of the same object for this page.

How to use Liquid Syntax in Jekyll?


Filters are used to modify outputs. It is used along with objects. A simple example is shown below.

{{page.title | upcase }}

Here is the output for this post


Here the output string will be converted into uppercase letters.

I hope by now you have a basic idea of how liquid syntax works. But these are very simple examples. There can be complex liquid code blocks as well. Let’s discuss some variables that we can use in Jekyll.

Here is a link for all the filters that you can use: Liquid Filters

Site Variables

These are sitewide objects. They can be used anywhere on the website to fetch data either something related to the site or data from _config.yml file.

Some examples here.

Variable Description
{{site.time}} Fetches current time - Ex: 2022-03-04 13:57:56 +0000
{{site.pages}} Fetches a list of all the pages
{{site.posts}} Fetches a list of all the posts
{{}} Fetches a list containing the data loaded from the YAML files located in the _data directory

Site variables defined in _config.yml are very useful and can be used to change things globally. Imagine you define your facebook username in the configuration file. You can access this from anywhere on the site.

Let’s say this is how you define all the social media accounts in _config.yml,

facebook: webjeda
twitter: webjeda
github: sharu725

Let’s say you create an author section with follow buttons,

Follow me on:
  <a href="{{site.facebook}}" target="_blank" >
      <i class="footer-icon fa fa-facebook-official"></i>

  <a href="{{site.twitter}}" target="_blank" >
      <i class="footer-icon fa fa-twitter"></i>

  <a href="{{site.github}}" target="_blank" >
      <i class="footer-icon fa fa-github-alt"></i>

Checkout the demo see the output.


This comes in very handy if you want to use these variables very often or change them altogether. I have used this feature while creating themes. Defining accent colors in configuration helps change the color globally.

Page variables

Variable Description
{{page.title}} Fetches title of the page. Ex: - How to use Liquid Syntax in Jekyll?
{{page.content}} Fetches anything after frontmatter of the page
{{page.excerpt}} Fetches the excerpt or first paragraph of the page
{{page.url}} Fetches the url of the page. Ex: for this page - /amp/jekyll-liquid

Page variables are page specific. They can only fetch data with respect to the page they are declared in.


These variables are very easy to implement but using them within a loop is a little tricky. I will give you some examples,

For Loop

{% for pot in site.posts %}
{% endfor %}

The output is here


Svelte Shopping Cart

Why do I like Svelte

How I built a free ecommerce website - Crocodaily

I’m limiting the outputs to 3. If not, the whole page will be filled with titles. Here, pot is just a variable. We generally use post in its place. You can use any word that you fancy.

You can also fetch titles manually (not recommended!)

{{ site.posts[0].title }}
{{ site.posts[1].title }}
{{ site.posts[2].title }}
{{ site.posts[n].title }}

Here n should be an integer. This method is not practical. You can use it if you’re willing to fetch the titles of first few posts.

For numbering a loop, you can use forloop.index. This can also be used to provide different ids for consecutive elements in a for loop.

{% for pot in site.posts %}
  {{forloop.index}}. {{pot.title}}
{% endfor %}

I have intentionally used pot instead of post because we can use any variable there.

The output looks like this,

1. How to use Liquid Syntax in Jekyll!

2. 14 Ways to Customize your Company Website

3. Jekyll's got a new GUI for local editing!
n. Nth post title

If else condition

{% if page.title contains 'Jekyll' %}
  This is a Jekyll related article.
{% endif %}

{% if page.title contains 'Liquid' %}
  This is a Liquid related article.
{% endif %}

{% if page.title contains 'Jekyll' and 'Liquid' %}
  This is a Jekyll Liquid article!
{% else %}
  This is neither Jekyll nor a Liquid article.
{% endif %}

The output is here

  This is a Jekyll related article.

  This is a Liquid related article.

  This is a Jekyll Liquid article!

Since this page has a title that contains both Jekyll and Liquid, the output is as shown above.

Else if in Jekyll Liquid Syntax is implemented this way,

{% if page.url == '/liquid/' %}
  The page URL for this page is /liquid/
{% elsif page.url == '/jekyll-liquid/' %}
  The page URL for this page is /jekyll-liquid/
{% endif %}

The output will be,

This is exactly how I have implemented active menu highlight for this blog. Navigate to About or Contact page and see how the colored-underline gets highlighted.

For loops will usually have more than one output but if conditions will have only one output.

Please go through this document to get familiar with other types of condtional flows.

Also refer:


Front Matter:


Watch the video: