Collections

Collections are a great way to group related content like members of a team or talks at a conference. Bridgetown comes with one built-in collection, posts, and you can add new collections to support all sorts of content structures and hierarchies. All of the pages on this very website, for example, are contained within a “docs” collection.

Table of Contents

• Setup
• Add content
• Output
• Permalinks
• Custom Sorting of Documents
  • Sort By Front Matter Key
• Liquid Attributes
  • Collections
  • Documents
• Collection Metadata

Setup

To use a Collection you first need to define it in your bridgetown.config.yml. For example here’s a collection of staff members:

collections:
  - staff_members

Note that by default, individual pages for collection documents won’t get rendered. 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, Bridgetown will consider it to be a static file and the contents will not undergo further processing. If front matter is provided, Bridgetown will process the file contents into the expected output.

Regardless of whether front matter exists or not, Bridgetown will write to the destination folder (e.g. output) 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 Bridgetown for the past *five years*.

Now you can iterate over site.staff_members on a page and display 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 %}

Output

If you’d like Bridgetown to create a rendered page for each document in your collection, you can set the output key to true in your collection metadata in bridgetown.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 %}

If you have a large number of documents, it’s likely you’ll want to use the Pagination feature to make it easy to browse through a limited number of documents per page.

Permalinks

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

Custom Sorting of Documents

By default, multiple documents in a collection are sorted by their date attribute when they have the date key in their front matter. However, if 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.

Liquid Attributes

Collections

Collections objects are available under site.collections with the following information:

Documents

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

Collection Metadata

It’s also possible to add custom metadata to a collection. You simply add additional keys to the collection config and they’ll be made available in the Liquid context. For example, if you specify this:

collections:
  tutorials:
    output: true
    name: Terrific Tutorials

Then you could access the name value in a template:

{{ site.tutorials.name }}

or if you’re on a document page within the collection:

{{ page.collection.name }}