Collections

Not everything is a post or a page. Maybe you want to document the various methods in your open source project, members of a team, or talks at a conference. Collections allow you to define a new type of document that behave like Pages or Posts do normally, but also have their own unique properties and namespace.

Using Collections

To start using collections, follow these 3 steps:

• Step 1: Tell Jekyll to read in your collection
• Step 2: Add your content
• Step 3: Optionally render your collection’s documents into independent files

Step 1: Tell Jekyll to read in your collection

Add the following to your site’s _config.yml file, replacing my_collection with the name of your collection:

collections:
- my_collection

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

collections:
  my_collection:
    foo: bar

Default attributes can also be set for a collection:

defaults:
  - scope:
      path: ""
      type: my_collection
    values:
      layout: page

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 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 _posts directory to my_collections/_posts. Note that, the name of your collections directory cannot start with an underscore (`_`).

Step 2: Add your content

Create a corresponding folder (e.g. <source>/_my_collection) and add documents. YAML 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 YAML front matter is provided, Jekyll will not generate the file in your collection.

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.

Step 3: Optionally render your collection’s documents into independent files

If you’d like Jekyll to create a public-facing, rendered version of each document in your collection, set the output key to true in your collection metadata in your _config.yml:

collections:
  my_collection:
    output: true

This will produce a file for each document in the collection. For example, if you have _my_collection/some_subdir/some_doc.md, it will be rendered using Liquid and the Markdown converter of your choice and written out to <dest>/my_collection/some_subdir/some_doc.html.

If you wish a specific page to be shown when accessing /my_collection/, simply add permalink: /my_collection/index.html to a page. To list items from the collection, on that page or any other, you can use:

{% for item in site.my_collection %}
  <h2>{{ item.title }}</h2>
  <p>{{ item.description }}</p>
  <p><a href="{{ item.url }}">{{ item.title }}</a></p>
{% endfor %}

Don't forget to add YAML for processing

Files in collections that do not have front matter are treated as static files and simply copied to their output location without processing.

Configuring permalinks for collections

If you wish to specify a custom pattern for the URLs where your Collection pages will reside, you may do so with the permalink property:

collections:
  my_collection:
    output: true
    permalink: /:collection/:name

Examples

For a collection with the following source file structure,

_my_collection/
└── some_subdir
    └── some_doc.md

each of the following permalink configurations will produce the document structure shown below it.

• Default Same as permalink: /:collection/:path.

  _site/
  ├── my_collection
  │   └── some_subdir
  │       └── some_doc.html
  ...
  

• permalink: pretty Same as permalink: /:collection/:path/.

  _site/
  ├── my_collection
  │   └── some_subdir
  │       └── some_doc
  │           └── index.html
  ...
  

• permalink: /doc/:path

  _site/
  ├── doc
  │   └── some_subdir
  │       └── some_doc.html
  ...
  

• permalink: /doc/:name

  _site/
  ├── doc
  │   └── some_doc.html
  ...
  

• permalink: /:name

  _site/
  ├── some_doc.html
  ...
  

Template Variables

Liquid Attributes

Collections

Each collection is accessible as a field on the site variable. For example, if you want to access the albums collection found in _albums, you’d use site.albums.

Each collection is itself an array of documents (e.g., site.albums is an array of documents, much like site.pages and site.posts). See the table below for how to access attributes of those documents.

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

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 }}

Documents

In addition to any YAML Front Matter provided in the document’s corresponding file, each document has the following attributes:

Accessing Collection Attributes

Attributes from the YAML front matter can be accessed as data anywhere in the site. Using the above example for configuring a collection as site.albums, you might have front matter in an individual file structured as follows (which must use a supported markup format, and cannot be saved with a .yaml extension):

title: "Josquin: Missa De beata virgine and Missa Ave maris stella"
artist: "The Tallis Scholars"
director: "Peter Phillips"
works:
  - title: "Missa De beata virgine"
    composer: "Josquin des Prez"
    tracks:
      - title: "Kyrie"
        duration: "4:25"
      - title: "Gloria"
        duration: "9:53"
      - title: "Credo"
        duration: "9:09"
      - title: "Sanctus & Benedictus"
        duration: "7:47"
      - title: "Agnus Dei I, II & III"
        duration: "6:49"

Every album in the collection could be listed on a single page with a template:

{% for album in site.albums %}
  <h2>{{ album.title }}</h2>
  <p>Performed by {{ album.artist }}{% if album.director %}, directed by {{ album.director }}{% endif %}</p>
  {% for work in album.works %}
    <h3>{{ work.title }}</h3>
    <p>Composed by {{ work.composer }}</p>
    <ul>
    {% for track in work.tracks %}
      <li>{{ track.title }} ({{ track.duration }})</li>
    {% endfor %}
    </ul>
  {% endfor %}
{% endfor %}