集合(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:

collections:
  - staff_members

In this case collections is defined as a sequence (i.e., array) with no additional metadata defined for each collection. You can optionally specify metadata for your collection by defining collections as a mapping (i.e., hashmap) instead of sequence, and then defining additional fields in it:

collections:
  staff_members:
    people: true

When defining a collection as a sequence, its pages will not be rendered by default. To enable this, output: true must be specified on the collection, which requires defining the collection as a mapping. For more information, see the section Output.

Add content

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 consider it to be a static file and the contents will not undergo further processing. If front matter is provided, Jekyll will process the file contents into the expected output.

Regardless of whether front matter exists or not, Jekyll will write to the destination directory (e.g. _site) only if output: true has been set in the collection’s metadata.

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

Do note that in spite of being considered as a collection internally, the above doesn’t apply to posts. Posts with a valid filename format will be marked for processing even if they do not contain front matter.

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:

{% 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 %}

Permalinks

There are special permalink variables for collections to help you control the output url for the entire collection.

Custom Sorting of Documents4.0

By default, two documents in a collection are sorted by their date attribute when both of them have the date key in their front matter. However, if either or both documents do not have the date key in their front matter, they are sorted by their respective paths.

You can control this sorting via the collection’s metadata.

Sort By Front Matter Key

Documents can be sorted based on a front matter key by setting a sort_by metadata to the front matter key string. For example, to sort a collection of tutorials based on key lesson, the configuration would be:

collections:
  tutorials:
    sort_by: lesson

The documents are arranged in the increasing order of the key’s value. If a document does not have the front matter key defined then that document is placed immediately after sorted documents. When multiple documents do not have the front matter key defined, those documents are sorted by their dates or paths and then placed immediately after the sorted documents.

Manually Ordering Documents

You can also manually order the documents by setting an order metadata with the filenames listed in the desired order. For example, a collection of tutorials would be configured as:

collections:
  tutorials:
    order:
      - hello-world.md
      - introduction.md
      - basic-concepts.md
      - advanced-concepts.md

Any documents with filenames that do not match the list entry simply gets placed after the rearranged documents. If a document is nested under subdirectories, include them in entries as well:

collections:
  tutorials:
    order:
      - hello-world.md
      - introduction.md
      - concepts/basics.md
      - concepts/advanced.md

If both metadata keys have been defined properly, order list takes precedence.

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:

Documents

In addition to any front matter provided in the document’s corresponding file, each document has the following attributes: