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.
- Upload your edited
routes.yaml
file - Upload your new theme
.zip
containing any new templates and CSS - 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.