Content Collections
Table of contents

Collections are the backbone of how posts on a Ghost site are organised, as well as what URLs they live on. You can think of collections as major sections of a site which represent distinct and separate types of content, for example: blog and podcast.

Collections serve two main purposes:

  1. To display all posts contained within them on a paginated index route
  2. To determine the URL structure of their posts and where they 'live' on the site. For this reason, posts can only ever be in one collection.

A post must either be a blog or a podcast, it can't be both.

The default collection

The default routes.yaml file which comes with Ghost contains just a single collection on the root / URL which defines the entire structure of the site.

collections:
  /:
    permalink: /{slug}/
    template: index

Here, the home route of site.com will display all posts, using the index.hbs template file, and render each post on a URL determined by the {slug} created in the Ghost editor.

In short: This is exactly how+why Ghost works by default!

Using a custom homepage

One of the most minimal examples of editing the default collection is to move it to a new location, and make room for a custom home page.

routes:
  /: home

collections:
  /blog/:
    permalink: /blog/{slug}/
    template: index

Using an example from the previous section on custom routes, the home / route is now pointing at a static template called home.hbs — and the main collection has now been moved to load on site.com/blog/. Each post URL is also prefixed with /blog/.

Filtering collections

Much like the {{#get}} helper, collections can be filtered to contain only a subset of content on your site, rather than all of it.

collections:
  /blog/:
    permalink: /blog/{slug}/
    template: blog
    filter: primary_tag:blog
  /podcast/:
    permalink: /podcast/{slug}/
    template: podcast
    filter: primary_tag:podcast

Returning to the earlier example, all of the posts within Ghost here are divided into two collections of blog and podcast.

Blog collection

  • Appears on: site.com/blog/
  • Post URLs: site.com/blog/my-story/
  • Contains posts with: a primary_tag of blog

Podcast collection

  • Appears on: site.com/podcast/
  • Post URLs: site.com/podcast/my-episode/
  • Contains posts with: a primary_tag of podcast

The primary_tag property is simply the first tag which is entered in the tag list inside Ghost's editor. It's useful to filter against the primary tag because it will always be unique.

If posts match the filter property for multiple collections this can lead to problems with post rendering and collection pagination, so it's important to try and always keep collection filters unique from one another. More info here »