--- title: Collections permalink: /docs/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](#step1) * [Step 2: Add your content](#step2) * [Step 3: Optionally render your collection's documents into independent files](#step3) ### Step 1: Tell Jekyll to read in your collection {#step1} Add the following to your site's `_config.yml` file, replacing `my_collection` with the name of your collection: ```yaml collections: - my_collection ``` You can optionally specify metadata for your collection in the configuration: ```yaml collections: my_collection: foo: bar ``` Default attributes can also be set for a collection: ```yaml defaults: - scope: path: "" type: my_collection values: layout: page ```
Gather your collections

From v3.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.

### Step 2: Add your content {#step2} Create a corresponding folder (e.g. `/_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 {#step3} 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`: ```yaml 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 `/my_collection/some_subdir/some_doc.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.

## Configuring permalinks for collections {#permalinks} 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](../permalinks/): ```yaml 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
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 :title template variable will take the slug front matter variable value if any is present in the document; if none is defined then :title will be equivalent to :name, aka the slug generated from the filename.

:output_ext

Extension of the output file. (Included by default and usually unnecessary.)
## 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:
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 %}

### 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 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.

## 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): ```yaml 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: ```liquid {% raw %} {% for album in site.albums %}

{{ album.title }}

Performed by {{ album.artist }}{% if album.director %}, directed by {{ album.director }}{% endif %}

{% for work in album.works %}

{{ work.title }}

Composed by {{ work.composer }}

{% endfor %} {% endfor %} {% endraw %} ```