Intermediate
How to customize routing and URLs on Ghost
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.
Prerequisites
- Admin access to Ghost dashboard
- Basic understanding of YAML syntax
- FTP or file manager access to Ghost installation
1
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.
Tip
Always backup your current routes.yaml before making changes
2
Understand Routes.yaml Structure
Open the downloaded routes.yaml file in a text editor. The file contains three main sections:
routes:- Custom route mappingscollections:- Post collections with custom URLstaxonomies:- Tag and author page structures
Tip
Use proper YAML indentation (2 spaces) to avoid syntax errors
3
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/blog/ collection with posts accessible at /blog/post-name/. You can use variables like {slug}, {year}, {month}, and {day}.Tip
Test URL changes on a staging site first to avoid breaking existing links
4
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.portfoliotemplate property specifies which Handlebars template file to use, and data can inject specific content.Tip
Custom templates must exist in your theme's template directory
5
Configure Taxonomy URLs
Customize tag and author page URLs in the taxonomies section:
taxonomies:
tag: /topic/{slug}/
author: /writers/{slug}//tag/example/ to /topic/example/ and author pages to /writers/author-name/.Tip
Consider SEO implications when changing existing taxonomy URLs
6
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/'301 redirects for permanent moves to preserve SEO value.Tip
Use external redirect tools for complex redirect patterns
7
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.
Tip
Check your site's navigation and internal links after uploading
8
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
Tip
Update your sitemap and internal links to reflect the new URL structure
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).Ready to get started with Ghost?
Put this tutorial into practice. Visit Ghost and follow the steps above.
Visit Ghost →