How to customize routing and URLs on Ghost

intermediate 12 min read Updated 2026-03-18

Quick Answer

Ghost allows you to customize routing and URLs through the routes.yaml file, which controls how your content is structured and accessed. You can modify permalinks, create custom collections, and set up redirects to match your specific site architecture needs.

Try Ghost Full Ghost Review

Prerequisites

Admin access to Ghost dashboard
Basic understanding of YAML syntax
FTP or file manager access to Ghost installation

Step-by-Step Instructions

Access the Routes Configuration

Navigate to your Ghost admin dashboard and go to Settings → Labs. Scroll down to find the Routes section. Click Download current routes.yaml to get your existing configuration file as a starting point.

Always backup your current routes.yaml before making changes

Understand Routes.yaml Structure

Open the downloaded routes.yaml file in a text editor. The file contains three main sections:

routes: - Custom route mappings
collections: - Post collections with custom URLs
taxonomies: - Tag and author page structures

Each section controls different aspects of your URL structure.

Use proper YAML indentation (2 spaces) to avoid syntax errors

Customize Post Collection URLs

To change your post URL structure, modify the collections section. For example:

collections:
  /blog/:
    permalink: /blog/{slug}/
    template: index
    filter: tag:-hash-hidden

This creates a /blog/ collection with posts accessible at /blog/post-name/. You can use variables like {slug}, {year}, {month}, and {day}.

Test URL changes on a staging site first to avoid breaking existing links

Create Custom Routes

Add custom routes in the routes section to map specific URLs to templates:

routes:
  /custom-page/:
    template: custom-page
  /portfolio/:
    template: portfolio
    data: page.portfolio

The template property specifies which Handlebars template file to use, and data can inject specific content.

Custom templates must exist in your theme's template directory

Configure Taxonomy URLs

Customize tag and author page URLs in the taxonomies section:

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

This changes tag pages from /tag/example/ to /topic/example/ and author pages to /writers/author-name/.

Consider SEO implications when changing existing taxonomy URLs

Set Up Redirects

Add redirects in the routes section to handle old URLs:

routes:
  /old-page/:
    template: index
    redirect: '/new-page/'
  /legacy-blog/:
    redirect: '/blog/'

Use 301 redirects for permanent moves to preserve SEO value.

Use external redirect tools for complex redirect patterns

Upload and Test Configuration

Save your modified routes.yaml file and return to Settings → Labs in your Ghost admin. In the Routes section, click Upload routes YAML and select your file. Ghost will validate the syntax and apply the changes immediately.

Check your site's navigation and internal links after uploading

Verify URL Changes

Test your new URL structure by:

Visiting updated collection pages
Checking individual post URLs
Testing custom routes and redirects
Verifying tag and author page URLs

Use browser developer tools to confirm proper HTTP status codes (200 for pages, 301 for redirects).

Update your sitemap and internal links to reflect the new URL structure

Common Issues & Troubleshooting

YAML syntax error prevents upload

Check for proper indentation using 2 spaces (not tabs) and ensure colons have spaces after them. Use a YAML validator to identify syntax issues.

Custom routes return 404 errors

Verify that the specified template files exist in your active theme's directory. Template names must match exactly, including file extensions.

Redirects not working properly

Ensure redirect URLs start with / for internal redirects or include http:///https:// for external redirects. Check for conflicting routes.

Collection filters not displaying expected posts

Review your filter syntax - use tag:example to include posts with a tag, tag:-example to exclude them. Combine filters with + (AND) or , (OR).

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official Ghost website before purchasing.

Visit Ghost View Ghost Pricing