Creating content hubs with Ghost

The dynamic routing configuration layer in Ghost unlocks the ability to create paginated content hubs called channels. These can be implemented without changing the individual URL of the posts, and provide an efficient way to divide or combine existing tagged content on your Ghost publication with a few lines of code.

Overview

Content views are created using the controller property in the routes.yaml file. The controller property has one supported value: channel.

A filter is used in combination with the controller: channel configuration to select a specific list of posts for display using the {{posts}} template variable.

This tutorial goes through the steps required to create a content view or “channel” using the controller property.

Building content views with controller: channel does not change the individual URL of any posts or pages. To create a content collection with unique URL structures, check out this tutorial!

Create routes and channels in the routes.yaml file

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 areas, and for this tutorial you’ll be using the “routes” section - read more about dynamic routing and the routes.yaml file.

First of all, create new routes from which you want your content view to be indexed, and then use the controller and filter properties to define those routes. Use the following structure:

routes:
  /route/description/:
    controller: channel
    filter: tag:x+tag:y

Using filters

Filters can be used in numerous ways to divide or combine both the tags and authors of a post or page. Here’s a full guide of the parameters for the filter property:

filter: tag:x+tag:y # must have both "x" and "y" tags (+ = AND)
filter: tag:x,tag:y # can have either "x" or "y" tags (, = OR)
filter: tag:-x+tag:y # must have tag "y" but not tag "x" (- = NOT)
filter: tag:[x,y,z] # must have either "x", "y", or "z" tags ([] = IN)
filter: tag:-[x,y,z] # must not have any one of "x", "y", or "z" tags (-[] = NOT IN)
filter: author:steve+tag:x # must be written by "steve" and have tag "x"

Example

In the following example, two content hubs are being created for /reviews/mobile/ and /reviews/photography/. Let’s imagine this publication posts reviews, news and other content about technology, and they want to create two views of content for reviews of phones and reviews of photography gear:

routes:
  /reviews/mobile/:
    controller: channel
    ilter: tag:review+tag:mobile
  /reviews/photography/:
    controller: channel
    filter: tag:review+tag:camera

In this case, all posts or pages tagged with review and mobile will appear on /reviews/mobile/ and all posts or pages tagged with review and camera will appear on /reviews/photography/. Individual posts will still keep their original URL, for example, example.com/post-name or example.com/blog/post-name/ depending on the configuration of any other routes or collections.

This is just one working example for the purposes of the tutorial. You can divide or combine content on your site in almost any way you need using tags, authors and the filter property.

Map your channels to a template

Once you are happy with your new routes and filters, the last thing you’ll need to add to routes.yaml is the template property, to map your new content hub(s) to a handlebars template within your theme.

Following the same example from above, the structure would be:

routes:
  /reviews/mobile/:
    controller: channel
    filter: tag:review+tag:mobile
    template: reviews
  /reviews/photography/:
    controller: channel
    filter: tag:review+tag:camera
    template: reviews

This would map both of the new channel routes to the template called reviews.hbs, which could be a custom template specifically the purposes of featuring reviews in their own content hub.

Create a custom template for your channel

If you’d like to use custom data and styling on your new content hub, you’ll need to create a new template from scratch. For further information about creating custom templates, visit the handlebars theme documentation!

If you don’t want to use a custom template, you can use your theme’s default template for an index page or list of posts, which is usually called index.hbs.

Navigation

In order to add a feature a link to your new content hubs from your site, try adding some links into the navigation, which can be found in the “design” menu in Ghost admin. Alternatively, you may want to provide links to your new pages from a custom home page or a static page on your site directly in the page’s template.

Implement your channels and templates

Almost at the finish line. Once you’ve finished editing your routes.yaml file, created optional handlebars templates and made any necessary adjustments to your CSS files, you can upload your work to your site in Ghost admin.

1. Upload your edited routes.yaml file
2. Upload your new theme .zip containing any new templates and CSS
3. Visit the new routes you created and ensure your content is rendering correctly and your filters are passing through the correct posts and pages

Summary

In this tutorial you have created one or more channels for your publication that can be viewed like content hubs at a designated route. Each new content view has its own paginated index page and optional custom template, while the URL structure for individual posts remains the same.

Now you know the most efficient way to build a content hub on your site without altering the URL structure, and you can replicate this with new filter combinations and templates as required.