Jekyll Front matter

Episode #2 - Mar 01, 2016 - 6 minutes

Subscribe to Jekyll Casts

Front matter is used to set variables and metadata on pages in your Jekyll site. Let’s get straight into an example to demonstrate why this is useful.

We’ll start with some basic HTML structure in about.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>About</title>
  </head>
  <body>
    <h1>About page</h1>
  </body>
</html>

Starting about page

Now we’ll set a variable in front matter, then output it on our page. Front matter lives between two triple dashed lines --- at the top of the file. In between these lines we can write YAML to set variables.

Let’s set a variable called hello_text and give it a value of “Hello there!”. about.html now looks like this:

---
hello_text: "Hello there!"
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>About</title>
  </head>
  <body>
    <h1>About page</h1>
  </body>
</html>

To output front matter variables, Jekyll uses a language called Liquid. We’ll cover Liquid in later videos, for now you need to know two basic tags:

  • You can output variables by surrounding them in two curly braces e.g. {{ variable }}
  • You can perform logic statements by surrounding them in a curly brace, percentage sign e.g. {% if statement %}

We can access variables set in front matter using page.name_of_variable. So let’s add p straight after the h1 and output hello_text.

---
hello_text: "Hello there!"
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>About</title>
  </head>
  <body>
    <h1>About page</h1>
    <p>{{ page.hello_text }}</p>
  </body>
</html>

Output about page

We can use front matter to show/hide sections of a page. In this example we’ll add a show_footer variable to the front matter which when set to true, will add a footer to the page.

---
hello_text: "Hello there!"
show_footer: true
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>About</title>
  </head>
  <body>
    <h1>About page</h1>
    <p>{{ page.hello_text }}</p>

    {% if page.show_footer %}
      <footer>I am a footer</footer>
    {% endif %}
  </body>
</html>

Footer about page

Changing show_footer to false will remove the footer.

Arrays are also possible in front matter. We’ll create a new array called fruit, each item is indented with two spaces then starts with a hyphen. Then we’ll iterate over the items on our page and output them as an unordered list.

---
hello_text: "Hello there!"
show_footer: false
fruit:
  - apple
  - banana
  - orange
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>About</title>
  </head>
  <body>
    <h1>About page</h1>
    <p>{{ page.hello_text }}</p>

    <ul>
      {% for item in page.fruit %}
        <li>{{ item }}</li>
      {% endfor %}
    </ul>

    {% if page.show_footer %}
      <footer>I am a footer</footer>
    {% endif %}
  </body>
</html>

Object about page

In this last example we’ll use objects in front matter. Objects allow for more complex data structures, we’re going to use it in our fruits array so we’re not only setting the name of the fruit, but also the cost and color. Instead of array items being strings we want them to be keys and values. When we’re outputting the fruit, item is now an entire object so we need to reference the keys inside the object.

---
hello_text: "Hello there!"
show_footer: false
fruit:
  - name: apple
    cost: $1
    color: red
  - name: banana
    cost: $2
    color: yellow
  - name: orange
    cost: $1.50
    color: orange
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>About</title>
  </head>
  <body>
    <h1>About page</h1>
    <p>{{ page.hello_text }}</p>

    <ul>
      {% for item in page.fruit %}
        <li>{{ item.name }}, cost: {{ item.cost }}, color: {{ item.color }}</li>
      {% endfor %}
    </ul>

    {% if page.show_footer %}
      <footer>I am a footer</footer>
    {% endif %}
  </body>
</html>

Object about page

The real power of front matter comes when it’s used in combination with layouts and includes which we’ll cover in the next tutorials.

Subscribe to Jekyll Casts