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

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*.
Be sure to name your folders correctly

The folder must be named identically to the collection you defined in your bridgetown.config.yml file, with the addition of the preceding _ character.

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.

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:

Variable Description

label

The name of your collection, e.g. my_collection.

docs

An array of documents.

files

An array of static files in the collection.

relative_directory

The path to the collection's source folder, relative to the site source.

directory

The full path to the collections's source folder.

output

Whether the collection's documents will be output as individual files.

Posts: a Built-in Collection

In addition to any collections you create yourself, the posts collection is hard-coded into Bridgetown. 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.

Documents

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

Variable Description

content

The content of the document (including transformations if the format is, say, Markdown). If no front matter is provided, Bridgetown will not generate the file in your collection.

output

The final rendered output of the document (HTML for example), based on the content.

relative_path

The path to the document's source file relative to the site source.

url

The URL of the rendered document. The file is only written to the destination when the collection to which it belongs has output: true in the site's configuration.

collection

The document's collection object.

date

The date of the document's collection (usually the time the site was regenerated), unless a document date is provided via front matter.

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 }}
Top Top: You can relocate your collections

It's possible to optionally specify a folder to store all your collections in a centralized folder with collections_dir: my_collections.

Then Bridgetown will look in my_collections/_books for the books collection, and in my_collections/_recipes for the recipes collection.

Be sure to move posts into custom collections folder

If you specify a folder to store all your collections in the same place with collections_dir: my_collections, then you will need to move your _posts folder to my_collections/_posts. Note that the name of your collections directory cannot start with an underscore (`_`).

Next: Data Files