Developer docs

Change the URL for tags and authors in Ghost

A taxonomy is used to group things together based on a common relation. In Ghost, a taxonomy is used to group posts together by the author of the post, or the tags used for a post and you can adjust the URL structure of your taxonomy with a few lines of code ⚡


By default, Ghost will create permalinks for each taxonomy value, so there is be a unique URL for each author and for each tag, featuring all of the content that matches the slug.

Taxonomies are also mapped to generic handlebars templates by default, but you can create custom ones if required.

This tutorial shows you how to customise your taxonomy structure and templates.

If you want to merge content that matches more than one tag or author, or divide content into subsets and supersets, check out how to create a content hub using channels.

Define your taxonomies 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 sections, and for this tutorial you’ll be using the “taxonomies” section - read more about dynamic routing.

The default taxonomy configuration routes.yaml file looks like this:

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

This standard configuration must be present in the taxonomy configuration in order for these pages to work, and will return 404 errors when removed.

The taxonomies can be adjusted to suit your publication’s needs by changing the permalink structure. In the following example, the publication is a podcast focussed website:

  tag: /topic/{slug}
  author: /host/{slug}

Create custom templates in your theme

Depending on which theme you are using, your taxonomies will use the available standard template to render each taxonomy permalink. This is usually index.hbs or default.hbs.

Following the previous example, it may be more fitting to create entirely customised handlebars templates determine what data to fetch and how to render each taxonomy in a unique way.

In this case, create new theme templates using the file name: tag-technology.hbs or author-lewis-carroll.hbs. The URL is rendered like so:

This gives you the flexibility to completely customise the index page for any particular tag or author within your publication.

For more information about handlebars themes and creating a custom template, check out the theme documentation to find out more!

Implement your taxonomies and templates

Once you’ve finished working on the routes.yaml file, your handlebars templates and any necessary adjustments to your CSS files, upload your work in Ghost admin for it to take effect.

  1. Upload your edited routes.yaml file containing new taxonomy configuration
  2. Upload your new theme files including CSS in a .zip
  3. Visit one of your new taxonomy URLs and check they render correctly


You’ve successfully updated your taxonomies and permalinks for tags and authors on your Ghost publication. Don’t forget that custom templates and CSS can be used to render unique content for any particular tag or author that you use now and in the future!