Tutorial

Introduction to Collections in Jekyll

Published on July 25, 2017
author

Alligator.io

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:

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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar
Alligator.io

author

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.

Still looking for an answer?

Ask a questionSearch for more help

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!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more