Jekyll Collections usage and examples.

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

graph LR Collections["Collections"] == 1 === ColRelationship{" "} ColRelationship == N === Collection Collection["Collection
label
docs
files
relative_directory
directory
output"] == 1 === relationship{" "} relationship == N === Document["Document
path
relative_path
collection
date"]

Creating a Collection

graph TB; A["Add *my_collection* as a collection directory in /_config.yml"]==>B("Add markdown files to *my_collection* directory"); B==>C{"Is *output: true* in _config.yml"}; C==>|yes|D["each file in the *my_collection* can be accesed through the url *my_collection/file* "]; C==>|no|E["collections content is only available through the variable *site.my_collection* or *site.collections*"]

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 %}
Uruguay
Marcelo Canina
I'm Marcelo Canina, a developer from Uruguay. I build websites and web-based applications from the ground up and share what I learn here.

Articles in this category

Articles

This article is being referenced in: