20 May 2017

An introduction to liquid for jekyll site creators - Part 1

I suppose it is a good thing that you can get quite far with jekyll site creation without really knowing what you are doing. I’ve been playing around with jekyll for some time, and using it for some projects at work without, I’ve realized recently, a particularly clear understanding of quite a few foundational concepts.

One rather glaring example: I had seen mention of Liquid, but didn’t understand that I was using it every time I created a layout or a list of posts.

If you’re new to jekyll, or if you have been fumbling along like me for a while, and you want to get a clearer picture of how Liquid helps make jekyll’s magic happen - this post is for you!

What is Liquid?

Liquid describes itself as an “open-source template language”1.

In the context of jekyll, this means that Liquid enables you to use little bits of code, like {{ page.title }} , to display content and information about your site, in this case, the title of a page. So, for example, if I add the code {{ page.title }} to the code on this page, I will get the title of this page: An introduction to liquid for jekyll site creators - Part 1.

Liquid calls things like {{ page.title }} Objects and they are extraordinarily handy in jekyll. You’ll use objects all the time and find them in jekyll themes and code snippets.

Objects come into play quite often in layouts which jekyll uses to define how pages that appear frequently in your site will look. Most jekyll themes have a layout called post.html which defines the structure for every post on your site.

The post.html file might contain a few lines of code similar to the following, which can describe how the page title and date should appear for every post on the site:


<h3>{{ page.title }}</h3>
<em>{{ page.date | date_to_string }}</em>

Objects also come into play whenever you want to display the title of your site, which is defined in your _config.yml file. Once defined, you can place the object {{ site.title }} anywhere in your code, and the title of your site will appear. Change the site title in _config.yml and it will instantly change everywhere on your site.

A few key things to know about Liquid Objects:

  • Objects are wrapped in double curly braces: {{ }}
  • By themselves, objects render content, usually something you have defined in _config.yml, the front matter of one of your posts, something you have defined in a _data file, or some other bit of content or information about your site.

Some common liquid objects used in jekyll, and what they output on this page

{{ site.title }} : dmcwo’s notebook

{{site.time}} : 2018-06-09 23:36:33 +0000

{{ page.title }} : An introduction to liquid for jekyll site creators - Part 1

{{page.url}} : /blog/intro-to-liquid-for-jekyll/

Super useful, right? It gets quite a bit better, though! In the next post, I’ll dive into how jekyll leverages Liquid tags and filters which is where the real magic happens!

Here’s a preview!

Filters let you fiddle with the output of Liquid objects:

Compare the output for this liquid object:

{{page.tags}} : tinkeringjekyllliquid

with this output, where we have added a filter to change how the output is displayed:

{{ page.tags | array_to_sentence_string }} : tinkering, jekyll, and liquid

  1. https://shopify.github.io/liquid/