Table of Contents
URL: https://www.progressiverobot.com/jekyll-collections/
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](/info/#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:
[label _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…
[label _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:
[label _config.yml]
collections:
animals:
output: true
permalink: /my-animal/:name
defaults:
[warning] 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:
[label _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:
[label _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:
[label 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.
