Understanding How Collections Work

Overview

Jekyll Collections makes it possible to define new document types. A collection is an array of documents.

They are very similar to posts but also have some unique features that makes them more appropiate in certain circumstances.

Default Jekyll posts are collections of type posts.

Variables and front matter

Each collection can have many document files.

.
└──_my_collection
    ├── a_document.html
    └── another_document.md

Variables of a Collection and Documents Collections

Creating a Collection

Collections variables

Variables that belong to collections and also the ones defined in _config.yml

label

The name of your collection, e.g. my_collection.

docs

An array of documents.

files

An array of static files in the collection.

relative_directory

The path to the collection's source directory, relative to the site source.

directory

The full path to the collections's source directory.

output

Whether the collection's documents will be output as individual files.

A single Collection Document variables

Variables in a single collection Document

content

The (unrendered) content of the document. If no YAML Front Matter is provided, Jekyll will not generate the file in your collection. If YAML Front Matter is used, then this is all the contents of the file after the terminating ```---``` of the front matter.

output

The rendered output of the document, based on the content.

path

The full path to the document's source file.

relative_path

The path to the document's source file relative to the site source.

url

The URL of the rendered collection. The file is only written to the destination when the collection to which it belongs has output: true in the site's configuration.

collection

The name of the document's collection.

date

The date of the document's collection.

Source

Access

All Jekyll Collections can be accessed with the global variable site using site.collections:

{% for collection in site.collections%}
 Collection name: {{collection.label}} 
 Relative path to the collection's source directory: {{collection.relative_directory }}
 Full path to the collection's directory: {{collection.directory}}
 Output collection files as individual files?: {{collection.output}}
 {% for doc in collection.docs%}
  {{doc.title}}
  {{doc.slug}}
 {% endfor %}
{% endfor %}

And variables of each Document of a Collection can be accessed with:

{% for collection in site.collections %}

<h4>Collection {{forloop.index}}</h4>

<dl>
{% for doc in collection.docs %}
<dt>Path</dt><dd>{{doc.path}}</dd>
<dt>Relative_path</dt><dd> {{doc.relative_path}}</dd>
<dt>Collection</dt><dd> {{doc.collection}}</dd>
<dt>Date</dt><dd> {{doc.date}}</dd>
{% endfor %}
</dl>
<hr>
{% endfor %}