Collections
Collections are a great way to group related content like members of a team or talks at a conference.
SetupPermalink
To use a Collection you first need to define it in your _config.yml
. For
example here’s a collection of staff members:
collections:
- staff_members
You can optionally specify metadata for your collection in the configuration:
collections:
staff_members:
people: true
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 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 contentPermalink
Create a corresponding folder (e.g. <source>/_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 a staff member to the collection set above.
The filename is ./_staff_members/jane.md
with the following content:
---
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.
OutputPermalink
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:
{% for staff_member in site.staff_members %}
<h2>{{ staff_member.name }} - {{ staff_member.position }}</h2>
<p>{{ staff_member.content | markdownify }}</p>
{% endfor %}
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
:
collections:
staff_members:
output: true
You can link to the generated page using the url
attribute:
{% for staff_member in site.staff_members %}
<h2>
<a href="{{ staff_member.url }}">
{{ staff_member.name }} - {{ staff_member.position }}
</a>
</h2>
<p>{{ staff_member.content | markdownify }}</p>
{% endfor %}
PermalinksPermalink
There are special permalink variables for collections to help you control the output url for the entire collection.
Liquid AttributesPermalink
CollectionsPermalink
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 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 }}
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.
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.
DocumentsPermalink
In addition to any 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 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. |
|
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. |