Collections

Collections are the perfect way to group resource-based content, such as blog posts, team members, talks at a conference, products to sell, upcoming events, and so forth. Bridgetown comes with a few built-in collections, and you can add new collections to support all sorts of content structures and hierarchies. All of the documentation pages on this very website are contained within a docs collection for example.

Let’s dive into how you can put collections to work for your content.

Table of Contents #

• Builtin Collections
• Custom Collections
• Adding Content
• Accessing Collection Content
• Output
  • Permalinks
• Custom Metadata
• Liquid Attributes

Builtin Collections #

Bridgetown comes with three collections configured out of the box. These are

• data, located in the src/_data folder
• pages, located in either the src top-level folder or the src/_pages folder
• posts, located in the src/_posts folder

The data collection doesn’t output to any URL and is used strictly to provide a complete merged dataset via the site.data variable. Learn more about data files here.

Pages are for generic, standalone (aka not dated) pages which will output at a URL similar to their file path. So src/i/am/a-page.html will end up with the URL /i/am/a-page/.

Posts are for dated articles which will output at a URL based on the configured permalink style which might include category and date information. Posts are typically saved in a YYYY-MM-DD-slug-goes-here.EXT format which will cause the date to be extracted from the filename prefix. Posts can be saved in an arbitrary folder structure that makes the most sense for your content (as long as they’re contained within src/_posts).

Custom Collections #

You’re by no means limited to the builtin collections. You can create custom collections with any name you choose. By default they will behave similar to standalone pages, but you can configure them to behave in other ways (maybe like posts). For example, you could create an events collection which would function similar to posts, and you could even allow future-dated content to publish (unlike what’s typical for posts).

# bridgetown.config.yml

collections:
  events:
    output: true
    permalink: pretty
    future: true

Thus an event saved at src/_events/2021-12-15-merry-christmas.md would output to the URL /events/2021/12/15/merry-christmas/.

You can control the way a collection is sorted by specifying the front matter key (default is either filename or date if present) as well as the direction as either ascending (default) or descending.

collections:
  reverse_ordered:
    output: true
    sort_by: order
    sort_direction: descending

Adding Content #

When setting up a custom collection, you’ll want to create a corresponding folder (e.g. src/_staff_members) and then add your resource files (aka files which include front matter). If no front matter is provided in a file, Bridgetown will consider it to be a static file and the contents will not undergo further processing. Otherwise, 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.

Accessing Collection Content #

Bridgetown provides the collections object to your templates, with the various collections available as keys. For example, you can iterate over collections.staff_members.resources on a page and display the content for each staff member. The main body of the resource is accessed using the content variable:

{% for staff_member in collections.staff_members.resources %}
  <h2>{{ staff_member.data.name }} - {{ staff_member.data.position }}</h2>
  <p>{{ staff_member.content | markdownify }}</p>
{% endfor %}

Output #

If you’d like Bridgetown to create a rendered page for each resource in your collection, make sure the output key is set to true in your collection metadata in bridgetown.config.yml:

collections:
  staff_members:
    output: true

You can link to the generated page using the relative_url attribute.

{% assign staff_member = collections.staff_members.resources[0] %}

<a href="{{ staff_member.relative_url }}">
  {{ staff_member.name }} - {{ staff_member.position }}
</a>

Permalinks #

There are special permalink variables for collections to help you control the output URL for the collection. Each collection can be configured with its own permalink style. Of course you’re always welcome to override that permalink on a individual resource-by-resource basis, or by using front matter defaults.

Custom 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 templates. For example, if you specify this:

collections:
  tutorials:
    output: true
    name: Terrific Tutorials

Then you could access the name value in a template:

{{ collections.tutorials.name }}

or if you’re accessing a resource within the collection:

{{ resource.collection.name }}

Liquid Attributes #

Collection objects are available under collections with the following information:

Prototype Pages