Collections

Collections are a great way to group related content like members of a team or talks at a conference.

Setup

To use a Collection you first need to define it in your _config.yml. For example here’s a collection of staff members:

collections:
  - staff_members

You can optionally specify metadata for your collection in the configuration:

collections:
  staff_members:
    people: true
Gather your collections3.7.0

You can optionally specify a directory to store all your collections in the same place with collections_dir: my_collections.

Then Jekyll will look in my_collections/_books for the books collection, and in my_collections/_recipes for the recipes collection.

Be sure to move drafts and posts into custom collections directory

If you specify a directory to store all your collections in the same place with collections_dir: my_collections, then you will need to move your _drafts and _posts directory to my_collections/_drafts and my_collections/_posts. Note that, the name of your collections directory cannot start with an underscore (`_`).

Add content

Create a corresponding folder (e.g. <source>/_staff_members) and add documents. Front matter is processed if the front matter exists, and everything after the front matter is pushed into the document’s content attribute. If no front matter is provided, Jekyll will not generate the file in your collection.

For example here’s how you would add an staff member to the collection set above. The filename is ./_staff_members/jane.md with the following content:

---
name: Jane Doe
position: Developer
---
Jane has worked on Jekyll for the past *five years*.
Be sure to name your directories correctly

The folder must be named identically to the collection you defined in your _config.yml file, with the addition of the preceding _ character.

Output

Now you can iterate over site.staff_members on a page and output the content for each staff member. Similar to posts, the body of the document is accessed using the content variable:

{% for staff_member in site.staff_members %}
  <h2>{{ staff_member.name }} - {{ staff_member.position }}</h2>
  <p>{{ staff_member.content | markdownify }}</p>
{% endfor %}

If you’d like Jekyll to create a rendered page for each document in your collection, you can set the output key to true in your collection metadata in _config.yml:

collections:
  staff_members:
    output: true

You can link to the generated page using the url attribute:

{% for staff_member in site.staff_members %}
  <h2>
    <a href="{{ staff_member.url }}">
      {{ staff_member.name }} - {{ staff_member.position }}
    </a>
  </h2>
  <p>{{ staff_member.content | markdownify }}</p>
{% endfor %}

There are special permalink variables for collections to help you control the output url for the entire collection.

Liquid Attributes

Collections

Collections are also available under site.collections, with the metadata you specified in your _config.yml (if present) and the following information:

Variable Description

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 Hard-Coded Collection

In addition to any collections you create yourself, the posts collection is hard-coded into Jekyll. It exists whether you have a _posts directory or not. This is something to note when iterating through site.collections as you may need to filter it out.

You may wish to use filters to find your collection: {{ site.collections | where: "label", "myCollection" | first }}

Collections and Time

Except for documents in hard-coded default collection posts, all documents in collections you create, are accessible via Liquid irrespective of their assigned date, if any, and therefore renderable.

However documents are attempted to be written to disk only if the concerned collection metadata has output: true. Additionally, future-dated documents are only written if site.future is also true.

More fine-grained control over documents being written to disk can be exercised by setting published: false (true by default) in the document's front matter.

Documents

In addition to any front matter provided in the document’s corresponding file, each document has the following attributes:

Variable Description

content

The (unrendered) content of the document. If no front matter is provided, Jekyll will not generate the file in your collection. If 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.