Introduction to Collections in Jekyll


While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

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:

    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:


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

    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:

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


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:

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.


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 class="animal-family {{ page.family | downcase }}">
    {{ page.family }}

    {{ content }}


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:

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>

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.

Creative Commons License