Ghost routing explained with routes.yaml examples — routes, collections & taxonomies

In short: Ghost’s routes.yaml defines how URLs map to templates and how posts are grouped (collections, taxonomies, channels). You edit it by downloading and uploading the file from Settings » Labs in Ghost Admin—routing is not applied just by adding a file to your theme zip. Changing routes.yaml is how you reshape permalinks, use a custom homepage, split content into sections, and expose filtered archives.

Ghost began as a blogging platform and, over time, as its APIs and routing matured, it grew into a full-fledged CMS.

One of the main features that makes Ghost a powerful publishing platform and CMS is Dynamic Routing. Routing is the system that maps URL patterns to data and templates within Ghost, which you can use to build custom site structures. Your active routing is defined in routes.yaml: that file is where you configure URLs, collections, and related behavior. Ghost ships a starting configuration you can download from Admin, edit, and upload again (see below). For the latest properties and edge cases, see Ghost’s official routing documentation.

## routes.yaml

routes:

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

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

In Ghost Admin, open Settings » Labs. Use Download current routes.yaml to save the file, edit it locally, then upload your changes with Upload routes YAML. Routing applied this way is managed in Labs—not by dropping a file into your theme zip alone.

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

Quick checklist

1. Download the current routes.yaml from Settings » Labs.
2. Edit the YAML (indentation matters—use spaces, not tabs).
3. Upload the file and confirm URLs in the browser.

Common pitfalls

• YAML indentation — Use spaces only; tab characters often make the file invalid or silently mis-nested.
• Collection filters — Overlapping filters (the same post matching more than one collection) can cause confusing pagination and duplicates. Keep filters as distinct as practical (see the warning under Collections).
• Posts “missing” from a collection — Check the filter: e.g. primary_tag:blog only includes posts whose primary tag is blog. A tag used only as a secondary tag will not match. Typos in tag slugs also break filters.
• Trailing slashes — Ghost expects URLs with trailing slashes in many setups; inconsistent links can look like “wrong” or duplicate URLs. Align links and redirects with your live permalink style.
• Upload didn’t “take” — If Admin rejects the file, fix YAML errors and re-upload. If it accepted but the site looks unchanged, hard-refresh or bypass cache; frontline caches can briefly serve old HTML.
• Template names — The name in routes.yaml must match a template in your active theme (e.g. about → about.hbs). A typo yields missing-template errors or the wrong layout.

Routes

A route matches a specific URL to a template. Routes are useful when you want a static page outside of Ghost Admin—for example when the page should not be editable there, it relies on a lot of custom code, or you need a URL that is more than a basic slug.

For example, if you want 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 that will be used, in this case about.hbs. The extension is not needed; Ghost adds it.

We defined a static page, but you might want some control from Admin. For that, use the data property. Change the route like this:

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

This assigns all data from the Ghost page with slug about to the route. Page fields are available inside the {{#page}} block helper in about.hbs. You get the feature image, title, content, and other fields, and Ghost can use that page’s meta settings for this URL too.

Besides generating a single page, you can output other responses—for example, a list of filtered posts with custom formatting. Routes usually render HTML, but you can override that with a content_type and a custom MIME type (text/xml, application/json, and so on).

Collections

Collections are groups of posts that match a filter, each with its own permalinks and an index URL listing matching posts. They are how posts are organized on a Ghost site.

By default, one collection holds all posts; you can define more for different topics or content types.

Collections can use these properties:

• permalink — custom URL structure for posts in the collection
• template — template used for the collection index
• filter — which posts belong here (e.g. by primary tag); see Ghost filter expressions for syntax

Example routes.yaml with a custom home page and two collections:

routes:
  /: home

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

Here the home page is rendered from home.hbs, and two collections are configured.

The /blog/ collection:

• appears at yoursite.com/blog/, rendered by blog.hbs
• includes posts whose primary_tag is blog
• post URLs look like yoursite.com/blog/{post-name}/

The /portfolio/ collection:

• appears at yoursite.com/portfolio/, rendered by portfolio.hbs
• includes posts whose primary_tag is portfolio
• post URLs look like yoursite.com/portfolio/{post-name}/

Collections vs channels: A collection sets where a post “lives” in the URL scheme (permalink + index). A channel is a filtered, paginated archive at a path; it does not move posts to a different permalink. The next section covers channels.

Taxonomies

Taxonomies group posts by author or tag. Ghost generates archives for tags and authors automatically.

Note: The same post can appear in multiple taxonomies.

Default taxonomy URLs:

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

You cannot add brand-new taxonomy types today, but you can change the URL prefixes for tag and author:

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

Channels

A channel provides paginated content for posts matching a filter—a way to surface subsets of your archive.

Channels use the controller property set to channel. They do not change a post’s canonical URL; a post can appear in any number of channels.

The controller property currently accepts only channel. Example:

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

This channel lists posts tagged news, rendered with news.hbs, at yoursite.com/news/.

If you change permalink patterns or move content between collections, add 301 redirects in redirects.yaml so old links keep working. See our Ghost redirects guide and Ghost’s implementing redirects tutorial.

This overview covers the core pieces of Ghost’s routing system. The same building blocks appear in walkthroughs such as building a custom homepage (moving the post index to /blog/ and using a page at /), routes metadata and SEO for titles and meta on routed URLs, custom pages for one-off templates, and changing your site URL when you change domains.