Ghost CMS Dynamic Routing & routes.yaml

Ghost first started as just a blogging platform, but slowly it evolved into something bigger. After some major updates to Ghost's API, during the years, Ghost can be used as a fully-fledged CMS.

One of the main features making Ghost an extremely powerful publishing platform and CMS is Dynamic Routing. Routing is the system that maps URL patterns to data and templates within Ghost, which can be used to build custom site structures. The routes.yaml file contains the default Ghost configuration.

## routes.yaml

routes:

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

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

You can download this file from the Admin, going to Settings » Labs and press Download current routes.yaml, you can make changes then upload it by pressing Upload routes YAML

If you want a simple landing page and posts under the /blog/ route, or you want to change the URL structure, or you want to split the posts into different content collections, then dynamic routing is what you need.

Routes

A route will match a specific URL to a template. Routes are useful for creating static pages outside of Ghost Admin, when you don’t want them to be editable, they use lots of custom code, or you need to create a specific custom URL with more than a basic slug.

For example, if you want to create a page called About with custom HTML and a more advanced layout, you can add your code in a new file about.hbs and then point a route to it:

routes:
  /about/: about

The first part is the URL: yoursite.com/about/ - the second part is the template which will be used, in this case about.hbs, the extension is not needed, Ghost takes care of that.

We defined a static page, but you might want to have at least some control over this page from the Admin, and for this, we can use the data property. Change the routes like this:

routes:
  /about/:
    template: about
    data: page.about

This will assign all of the data from a Ghost page with a slug of about to the new route, all properties of the page will be available inside the {{#page}}  block helper in a custom team.hbs . Not only you can have access to the feature image, title, content, and other properties but this will also take care of the meta properties as well for this page.

Besides generating a single page, it's possible to output anything, for example, a list of filtered posts with custom formatting. Generally, routes render HTML, but you can override that by specifying a content_type property with a custom mime-type (text/xml, json).

Collections

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. It's how posts are organized on a Ghost site.

By default, there is one collection that contains all posts, but you can define as many as you like for different topics or content types.

Collections can have the following properties:

• permalink - you can define a custom URL structure for posts within a collection
• template - this will be used to render the collection
• filter - you can set up filtering to be able to assign posts to a collection by t

Example of a routes file structure with a custom home page and two content collections:

routes:
  /: home

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

In this case, the home page will be rendered from the home.hbs file, and then two collections are set up.

The /blog/ collection:

• will appear on yoursite.com/blog/ rendered by the blog.hbs template
• contains posts with a primary_tag of blog
• The posts URL will be: yoursite.com/blog/{post-name}

The /portfolio/ collection:

• will appear on yoursite.com/blog/ rendered by the portfolio.hbs template
• contains posts with a primary_tag of portfolio
• The posts URL will be: yoursite.com/portfolio/{post-name}

Taxonomies

In Ghost, taxonomies are used to group posts by author or tag. Using taxonomies, Ghost will automatically generate post archives for tags and authors. Important to note that posts can appear in multiple taxonomies.

Default taxonomies settings:

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

Currently, it's not possible to define new taxonomies, but you can change the URL prefix for the existing tag and author if you prefer to have something else:

taxonomies:
  tag: /category/{slug}/
  author: /writer/{slug}/

Channels

A channel is a paginated content matching a specific filter, so you can create subsets of content.

Channels are defined using the controller property and do not influence over a post’s URL, so posts can belong to any number of channels.

The controller property only accepts one value currently: channel. Example of channel definition:

routes:
  /news/:
    controller: channel
		template: news
    filter: tag:[news]

In the example above, a new channel is defined which will contain all posts tagged news and will be rendered by the news.hbs template. This channel will live under yoursite.com/news/.

This would be the overview of the routes feature in Ghost CMS, but we plan to create some more specific tutorials expanding and going into more details on some aspects.