
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:
- To display all posts contained within them on a paginated index route
- 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
ofblog
Podcast collection
- Appears on:
site.com/podcast/
- Post URLs:
site.com/podcast/my-episode/
- Contains posts with: a
primary_tag
ofpodcast
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 »
Leave a comment