Lesson 4: Front matter basics

This content is likely out of date

The content of this course was written in May 2020, so parts will be outdated. As of 2024, a maintained fork of the course is available at learn-eleventy.pages.dev and new students are encouraged to use that version.

This version of the course is no longer maintained. If the linked fork is also outdated, consider reviewing the open Issues on the original project to check for recent activity.

Front Matter is like metadata for your page or template. It’s generally powered by YAML (opens new window) that, when added between a set of ---, lets you add extra content to a markdown file, template, or pretty much anything in Eleventy contexts.

YAML is human readable, structured data that’s normally used in configuration files. It’s been used by SSGs for metadata for a long time because it’s generally a pretty-darn simple way for people to manage content.

In this lesson, we’re going to dip our toes into the Front Matter water.

Adding Front Matter to our home page

Open up eleventy-from-scratch/src/index.md in your text editor and take a look at what we’ve got:

---
title: 'Hello, world'
layout: 'layouts/home.html'
---

This is pretty _rad_, right?

Our existing Front Matter contains a title and layout key. If we were to convert this YAML into JSON, it would look like this:

{
  "title": "Hello, world",
  "layout": "layouts/home.html"
}

Let’s add some more Front Matter to this file. With index.md still open, add the following after the line that contains layout:

intro:
  eyebrow: 'Digital Marketing is our'
  main: 'Bread & Butter'
  summary: 'Let us help you create the perfect campaign with our multi-faceted team of talented creatives.'
  buttonText: 'See our work'
  buttonUrl: '/work'
  image: '/images/bg/toast.jpg'
  imageAlt: 'Buttered toasted white bread'

Your index.md file should look like this now:

---
title: 'Hello, world'
layout: 'layouts/home.html'
intro:
  eyebrow: 'Digital Marketing is our'
  main: 'Bread & Butter'
  summary: 'Let us help you create the perfect campaign with our multi-faceted team of talented creatives.'
  buttonText: 'See our work'
  buttonUrl: '/work'
  image: '/images/bg/toast.jpg'
  imageAlt: 'Buttered toasted white bread'
---

What’s all of this indenting business about? What we’re doing here is adding properties inside an intro. To do that in YAML, we indent items, instead of wrapping them in brackets like we do with JSON.

Let’s see how this looks as JSON again:

{
  "title": "Hello, world",
  "layout": "layouts/home.html",
  "intro": {
    "eyebrow": "Digital Marketing is our",
    "main": "Bread & Butter",
    "summary": "Let us help you create the perfect campaign with our multi-faceted team of talented creatives.",
    "buttonText": "See our work",
    "buttonUrl": "/work",
    "image": "/images/bg/toast.jpg",
    "imageAlt": "Buttered toasted white bread"
  }
}

TIP

You can use JSON in your Front Matter in Eleventy, too. All you have to do is add json to the first --- like this: ---json.

We’re going to use YAML in our Front Matter for this course, but you can read more about using JSON in Front Matter in Eleventy’s docs (opens new window).

Hopefully the JSON example makes that relationship make a bit more sense. What will help even more is putting it into practice, so let’s first add some Front Matter to our home page.

Open eleventy-from-scratch/src/_includes/layouts/home.html and replace the existing <article> element with this one:

<article class="intro">
  <div class="[ intro__header ] [ radius frame ]">
    <h1 class="[ intro__heading ] [ weight-normal text-400 md:text-600 ]">
      {{ intro.eyebrow }}
      <em class="text-800 md:text-900 lg:text-major weight-bold">{{ intro.main }}</em>
    </h1>
  </div>
  <div class="[ intro__content ] [ flow ]">
    <p class="intro__summary">{{ intro.summary }}</p>
    <a href="{{ intro.buttonUrl }}" class="button">{{ intro.buttonText }}</a>
  </div>
  <div class="[ intro__media ] [ radius dot-shadow ]">
    <img
      class="[ intro__image ] [ radius ]"
      src="{{ intro.image }}"
      alt="{{ intro.imageAlt }}"
    />
  </div>
</article>

What we have here is our page intro. It’s pre-wired up with class attributes ready for when we add some CSS later. But for now, let’s focus on those {{ }} sections.

Remember how our new content was indented under intro? This now gives us a handy shortcut for our templates. For example: if we want to read the summary, we use {{ intro.summary }}.

Wrapping up

As your Front Matter gets larger and more complex, indenting and structuring the content becomes more and more useful. We’re going to get into even more detail with that as the course progresses.

For now though, I hope you understand a bit more about Front Matter. Let’s move on and get that image working!