Collections

Collections are defined using the collections group in the configuration file. This is a key/value group where the key is the name of the collection and the value is the settings for this collection.

In the following sections we will explain the settings used in the following example:

collections:
  sigpipe:
    sort_by: date
    sort_descending: true
    drafts_dir: _sigpipe_drafts
    defaults:
      permalink: /:year/:title/
      layout: sigpipe-post
    categories:
      permalink: /categories/:slug/
      layout: sigpipe-category

Sorting

Sorting of the collection is controlled using sort_by and sort_descending.

In the example above we have set the collection to use (reverse) chronological sort by sorting it by date.

Drafts

Each collection can have a drafts directory set using drafts_dir. This directory is relative to the collection_dir setting.

A draft post will be written to disk but excluded from the collection’s docs array unless show_drafts is set to true (e.g. by invoking glim with -D/--drafts). The page itself will have draft set to true so it is possible to indicate in the layout, that it is a draft post.

Categories & Tags

In this section we explain how to enable categories, but everything applies to tags as well.

Enabling category pages for a collection is done by setting permalink and layout under the collection’s categories key.

This will generate a new page for each category using the specified layout and permalink.

The page’s layout can access page.title, which will be the category name, and page.posts for the posts in that category.

A simple layout showing all posts for the page’s category would therefor be:

<h1>{{ page.title }}</h1>
<ul>
  {%- for post in page.posts %}
      <li><a href="{{ post.url }}">{{ post.title | escape }}</a></li>
  {%- endfor %}
</ul>

All generated pages are available as site.collections.«collection».categories. This container is indexed by the category name and the value is the page object for the respective category.

This means that if we wish to link directly to the list of posts in the General category of our sigpipe collection we can use: <a href="{{ site.collections.sigpipe.categories['General'].url }}">General</a>.

If permalink and layout is not set under categories then no pages are generated, but it is still possible to access site.collections.sigpipe.categories['General'].posts for the list of posts in that category.

So listing pages grouped by category on a single page is possible using the following:

{%- for category in site.collections.sigpipe.categories %}
  <h1>{{ category | escape }}</h1>
  <ul>
  {%- for post in categories[category].posts %}
    <li><a href="{{ post.url }}">{{ post.title | escape }}</a></li>
  {%- endfor %}
  </ul>
{%- endfor %}

Defaults

It is possible to set default values for the pages in the collection which goes under the defaults key.

In the example at the start of this chapter we set permalink here. It is worth noting that Jekyll allows setting it directly under the collection, which we also allow for backwards compatibility, but the setting belongs under defaults as it relates to the individual pages.