// Tutorial //

Introduction to Collections in Jekyll

Published on July 25, 2017
Default avatar
By Alligator.io
Developer and author at DigitalOcean.
Introduction to Collections in Jekyll

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking 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:

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

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


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


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

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


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.


Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!