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:

_config.yml

collections:
  animals:
    output: true

Setting the output option to true will generate a page for each document in our collection.

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…

_config.yml

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:

_config.yml

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

defaults:
  - scope:
      path: ""
      type: "animals"
    values:
      layout: animal

Don't forget to restart your local server after you've made changes to _config.yml.

Collection Documents

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

_animals/zebra.md

---
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
---

Some content about Zebras here...

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:

_layouts/animal.html

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

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

  <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>

Here our animal layout depends on the default layout.

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:

pages/animals.md

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

<ul>
  {% for animal in site.animals %}
    <li>
      <a href="{{ animal.url }}">{{ animal.title }}</a>
      - {{ animal.headline }}
    </li>
  {% endfor %}
</ul>

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:

{% assign author = site.authors | where: 'slug', page.author | first %}
{% if author %}
  <span class="author">
    <a href="{{ author.url }}">{{ author.title }}</a>
  </span>
{% endif %}

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.

✖ Clear

🕵 Search Results

🔎 Searching...