--- title: Collections permalink: /docs/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: ```yaml collections: - staff_members ``` You can optionally specify metadata for your collection in the configuration: ```yaml collections: staff_members: people: true ```

Gather your collections {%- include docs_version_badge.html version="3.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. `/_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: ```markdown --- 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: {% raw %} ```liquid {% for staff_member in site.staff_members %}

{{ staff_member.name }} - {{ staff_member.position }}

{% endfor %} ``` {% endraw %} 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`: ```yaml collections: staff_members: output: true ``` You can link to the generated page using the `url` attribute: {% raw %} ```liquid {% for staff_member in site.staff_members %}

{{ staff_member.name }} - {{ staff_member.position }}

{% endfor %} ``` {% endraw %} ## Permalinks There are special [permalink variables for collections](/docs/permalinks/) 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: {% raw %}{{ site.collections | where: "label", "myCollection" | first }}{% endraw %}

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.