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.
To start using collections, follow these 3 steps:
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 thebooks
collection, and inmy_collections/_recipes
for therecipes
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 tomy_collections/_posts
. Note that, the name of your collections directory cannot start with an underscore (`_`).
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.
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.
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
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 ...
Variable | Description |
---|---|
| Label of the containing collection. |
| Path to the document relative to the collection's directory. |
| The document's base filename, with every sequence of spaces and non-alphanumeric characters replaced by a hyphen. |
| The |
| Extension of the output file. (Included by default and usually unnecessary.) |
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 |
---|---|
| The name of your collection, e.g. |
| An array of documents. |
| An array of static files in the collection. |
| The path to the collection's source directory, relative to the site source. |
| The full path to the collections's source directory. |
| 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 throughsite.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 }}
In addition to any YAML Front Matter provided in the document’s corresponding file, each document has the following attributes:
Variable | Description |
---|---|
| 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. |
| The rendered output of the document, based on the |
| The full path to the document's source file. |
| The path to the document's source file relative to the site source. |
| The URL of the rendered collection. The file is only written to the destination when the collection to which it belongs has |
| The name of the document's collection. |
| The date of the document's collection. |
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 %}
© 2008–2018 Tom Preston-Werner and Jekyll contributors
Licensed under the MIT license.
https://jekyllrb.com/docs/collections/