Split your site into distinct sections to support different content types or topics using collections.

Overview

Collections allow you to create groups of posts that match a filter, with unique permalinks, and an index URL where all posts within that collection are listed and paginated.

It's possible to have a single collection that contains all posts, or multiple collections for distinct areas, content types or topics.

Content collections are created using the dynamic routing configuration layer, and allow you to create unique areas within your publication that have entirely different URL structures, templates, RSS feeds, design and behaviour.

This can be achieved by editing the routes.yaml file, creating new handlebars templates in your theme, and using tags in your post content to determine which collection each piece of content lives in.

This tutorial walks you through the process of setting up custom collections.

If you want to build custom views of content on your publication without changing the route, learn how create content hubs using channels in this tutorial.

Create collections in the routes.yaml file

A collection can be defined in the flexible dynamic routing layer in Ghost. Download your routes.yaml file from the settings in Ghost admin or locate the file on your server and open it in any code editor.

This file is split into three sections, and for this tutorial you'll be using the "collections" section – read more about dynamic routing.

In this example, two collections are being created for /blog/ and /podcast/ collections.

Collections are mapped to a permalink, for example:

collections:
  /blog/:
    permalink: /blog/{slug}/  
  /podcast/:
    permalink: /podcast/{slug}/

Filters

In order to ensure content can be tagged effectively, use the filter property, for example:

collections:
  /blog/:
    permalink: /blog/{slug}/
    filter: tag:blog+tag:-podcast
  /podcast/:
    permalink: /podcast/{slug}/
    filter: tag:podcast+tag:-blog

This configuration will allow you to filter your posts and pages that you would like to belong in a particular collection using tags in the editor.

Tip: you can use the full range of data properties to fetch resources using Ghost’s API.

When a post matches the filter property in a collection, it will define the routing or the URL for that post or page. For example, if a post has the tag blog then the URL for the post will become yoursite.com/blog/{post-name}. When it matches the podcast filter it will become yoursite.com/podcast/{post-name}.

In the current beta version of Dynamic Routing, it's necessary to specify the inverse of filters using -.

Templates

Each collection can be completely unique in terms of what data is used and how the content is rendered on your site using the Ghost theme layer. If no template property is specified in the routes.yaml file, then it will default to the name of the collection.

It is also possible to map collection to a template using the property, which is useful if you want to use a partial template to render a collection, for example:

collections:
  /blog/:
    permalink: /blog/{slug}/
    filter: tag:blog+tag:-podcast
  /podcast/:
    permalink: /podcast/{slug}/
    filter: tag:podcast+tag:-blog
    template: podcast/video

Create a template for your collection

To render unique content on your static pages, create different templates for each page. In the collections example above, the outcome would be to render the templates like so:

  • https://yoursite.com/blog πŸ‘‰ blog.hbs
  • https://yoursite.com/podcast/ πŸ‘‰ podcast/video.hbs

If the template is not found then the fallback template is used instead, for example post.hbs or default.hbs.

Create new templates for your new collections, using the name of the collection for the template file name. If you need further help creating a custom template, visit the handlebars theme documentation to find out more!

This method of mapping content in a collection to a template gives you the flexibility to create content within the Ghost editor and then use tags to define the collection, and render each section on your site in any way you like.

Since each collection that you create is going to have it's own index URL, such as yoursite.com/podcast, you will need to ensure that you create a navigation item for your collection so that it appears on your site. The navigation for Ghost content can be edited in the "design" menu in Ghost admin.

Use tags to define a collection for your posts

In order for content to appear inside each of your collections, you'll need to tag some posts or pages in the editor with the correct tags.

Using the tags you specified earlier using the filter property in your routes.yaml file, tag some of your posts so that you can test that your collections are working as expected in the next step.

The order that collections are listed in routes.yaml is important. Posts will only exist in one collection, which is always the first filter it matches with. Be mindful of this when creating three or more collections for your site.

Implement your collections and templates

Great work! Once you've finished editing your routes.yaml file with new collections, created some handlebars templates and made any necessary adjustments to your CSS files, the final thing to do is to get your new collections live on your site πŸŽ‰

  1. Upload your edited routes.yaml file in Ghost admin
  2. Upload your new theme .zip containing new templates and CSS in Ghost admin
  3. Visit your site and ensure your new collections render correctly

Summary

In this tutorial you have created one or more custom collections of content that will live inside their own unique section on your site, and be rendered using individual templates. Use this process to set up as many collections as required!