Jekyll has a powerful built-in templating language called Liquid so we can write code to do things in our pages. For a more comprehensive introduction, see the official Liquid docs–we’re mainly covering the highlights here.

Foundations#

Liquid functionality is split into two sections: objects and tags.

Objects and variables#

Objects always have some sort of output onto your page–and are surrounded by a double pair of curly brackets ( {{ an_expression }} ). The expression contained within these brackets is evaluated to form the value outputted by the object. For example, you could output the title of the page like so: {{ page.title }} .

The “page” object is always accessible, and contains information about the page in which the Liquid script is being evaluated–you can see a complete list of the properties of the page object here.

You can add your own data to the page object by adding extra variables to your front matter (the section of YAML at the top of your page, between the two “—” lines.

This is very handy. When writing your site, often times there will be links in your course content you need to change year-to-year: you simply just need to abstract these into your front matter.


---
repo_url: https://gitlab.cecs.anu.edu.au/course/compXXXX-2021-lab-1
---

Welcome to the first lab!

Start by [cloning the repo from GitLab]({{ page.repo_url }}).

Now, when we need to set up the course for 2022 we can just change the value of repo_url!

If you have a value which you want to be global across the entire site, you can set it in your _config.yml file and access it via the site variable in your Liquid templates–this might be helpful if you have a link to a forum (like Piazza) which changes regularly, but that you might refer to across multiple pages.

Tags#

Tags provide control flow and other logical facilities, and are frequently used in conjunction with objects to generate or modify your site at build-time.

Like most other programming languages, we have conditionals in the form of if-statements:

{% if page.title != "Home"  %}
  {{ page.title }}
{% endif %}

Determining if an expression is true or false in Liquid can be a bit funny. Fortunately there’s an entire page in their documentation about it.

You can also perform loops over variables (if, for example, you had an array called “tutors” in your front matter).

{% for tutor in tutors %}
- {{ tutor }}
{% endfor %}

Another handy tag is the “assign” tag, which allows you to specify a variable outside of your front matter.

{% assign message = "hello" %}

{% if page.message %}
  {% assign message = page.message %}
{% endif %}

The assign tag does not have a specific scope (variables assigned inside if-statements can be accessed as if they were not. They will be accessible until the end of the page!

There’s a nice list of all other tags in the Jekyll docs.

Filters#

You can use filters as part of an expression in a tag or an object. They can be used to capitalize a string, count the number of words in a sentence, process a Markdown document, and much more. You can even write your own filters in Ruby. A full list of the filters available to you by default is included in the Jekyll docs.

You use a filter on a variable using the pipe character, e.g.

There are {{ page.title | number_of_words }} words in the title of this page.

will output:

There are 4 words in the title of this page.

Generating content with data#

The following example combines all the techniques discussed above to provide an example of how you might use Liquid to auto-generate a table of lab times for your website.

Because front matter is YAML, you can store complicated objects in it (namely here, an array called “labs” with objects with name, time, and tutor keys).

You can also mix HTML and Markdown, another topic covered in our other documentation.

---
title: "Labs"

labs:
  - name: "OR"
    time: "Monday 1pm"
    tutor: Hades
  - name: "AND"
    time: "Tuesday 1pm"
    tutor: Zeus
  - name: "NOT"
    time: "Tuesday 3pm"
    tutor: Zeus
    hidden: true
---

<table>
<tr>
  <th>Lab name</th>
  <th>Time</th>
  <th>Tutor</th>
</tr>

{% for lab in page.labs %}
  {% if lab.hidden %}
    {% continue %}
  {% endif %}

  <tr>
    <td>{{ lab.name }}</td>
    <td>{{ lab.time }}</td>
    <td>{{ lab.tutor }}</td>
  </tr>
{% endfor %}
</table>

Quirks and Tips#

Arrays#

As mentioned earlier, you can use an {% assign %} {%- endraw -%} tag to create variables with Liquid, but you cannot natively create variables of an array type. Instead, you have to assign a string variable, then use a split filter to turn it into an array.

For example, I have the following names I would like in an array called members:

Anne, Bob, Cathy

Thus I would write:

{% raw %} {% assign members = "Anne, Bob, Cathy" | split: ", " %} Splitting the string on the ", " pattern to create an array of length 3.

Official Documentation.

arrow-left bars search times