Introduction to Collections in Jekyll

Collections in Jekyll provide an easy way to create your own taxonomies around content of the same type. This is great for pieces that belong in a group, but that are not really posts and shouldn’t be chronologically organized. A good use case for collections are author pages, as they were implemented on this website for content collaborators.

Let’s setup a simple animals collection that will hold content that relates to our favorite animals.

Collection Configuration

First, setup the collection in your _config.yml file:

collections:
  animals:
    output: true

Then, in your Jekyll site’s root folder, you’ll create an _animals folder and fill it with markdown files for each one of the animals in our collection:

_animals/
  zebra.md
  lion.md
  alligator.md
  ...

With this, our animals will be accessible by going to, for example, /animals/zebra. If desired, you can also define a different permalink structure…

collections:
  animals:
    output: true
    permalink: /my-animal/:name

…And that will make our animal pages available at URLs like /my-animal/zebra.

You can define default values for attributes on animals. This can be useful if all the documents in the collection will share the same layout for example:

collections:
  animals:
    output: true
    permalink: /my-animal/:name

defaults:

Collection Documents

Here’s an example of the content in one of our collection’s mardown files:

---
layout: animal # You can ommit this if you've set it as a default
title: Zebra
class:     Mammalia
family: Equidae
headline: Zebras are the best!
picture: /images/animails/zebra.jpg
---

Each one of our animals will contain values for these attributes: title, class, family, …, along with some markdown content that will be outputted using {{ content }} in the animal layout.

Layout

Here’s an example of what a simple layout could look like:

---
layout: default
---
<article class="animal">


    <img src="{{ page.picture }}" alt="Photo of a {{ page.title | downcase }}">


  <h1>Animal Profile: {{ page.title }}</h1>

  <div class="animal-class {{ page.class | downcase }}">
    {{ page.class }}
  </div>

  <div class="animal-family {{ page.family | downcase }}">
    {{ page.family }}
  </div>

  <div>
    {{ content }}
  </div>

</article>

Listing Collection Documents

Say you have a page where you’d like to list and link to each animal in the collection. That’s easy to do by accessing our collection though the site variable. Note also how the url attribute is available automatically and allows to easily link to the document:

---
layout: page
title: "A list of animals"
permalink: "/animals/"
---

Other than the url, a few more attributes are automatically available on each document: content, output, path, relative_path, collection and date.

Author Use Case

In the case of this website, we retrieve a post’s author with something like this in the layout:

  <span class="author">
    <a href="{{ author.url }}">{{ author.title }}</a>
  </span>

Posts with an author define an author attribute with a value that correlates to a slug attribute in each document of the author collection. Thanks to the power of the liquid templating language, we can retrieve the correct author for each post.

🦄 Have fun creating collections for your static Jekyll sites! For more details, you can refer to the official documentation.