Improve this page

Collections

Collections support is unstable and may change

This is an experimental feature and the API may change until the feature stabilizes.

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

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

Step 2: Add your content

Create a corresponding folder (e.g. <source>/_my_collection) and add documents. YAML Front Matter is read in as data if it exists, and everything after it is stuck in 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.

As for posts with Permalinks, the document URL can be customized by setting permalink metadata for the collection:

collections:
  my_collection:
    output: true
    permalink: /awesome/:path/

For example, if you have _my_collection/some_subdir/some_doc.md, it will be written out to <dest>/awesome/some_subdir/some_doc/index.html.

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.

Variable	Description
collection	Label of the containing collection.
path	Path to the document relative to the collection's directory.
name	The document's base filename, with every sequence of spaces and non-alphanumeric characters replaced by a hyphen.
title	The document's lowercase title (as defined in its front matter), with every sequence of spaces and non-alphanumeric characters replaced by a hyphen. If the document does not define a title in its front matter, this is equivalent to name.
output_ext	Extension of the output file.

Liquid Attributes

Collections

Each collection is accessible via the site Liquid 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 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:

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.

Documents

In addition to any YAML 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 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 name of the collection to which it belongs is included in the render key in the site's configuration file.
collection	The name of the document's collection.

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, one 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 %}

Back

Next