Avoid broken links by redirecting old URLs to new ones. In this tutorial, learn everything you need to know about Ghost's redirect process.
Redirects forward one URL to another. They are commonly used when removing or moving content on your site, fixing broken links, or migrating content between different domains.
In Ghost, redirects are configured by adding rules to the
redirects.yaml file. The basic process is to download this file from Ghost Admin, edit the file in a code editor, and then re-upload it to the admin interface.
This tutorial will walk you through:
- When not to use the
- Accessing the
redirects.yamlfile and its basic structure
- How to create your own redirects with common examples for reference
- Implementing your new redirects
- Some tips for getting started with regular expressions
When not to use redirects.yaml
Before we get started, make sure you are not trying to implement some common patterns where it is not necessary or advised to use the
- Page rules for www or HTTP/HTTPS redirection should always be implemented with your DNS provider.
- Ghost automatically forces trailing slashes, so you do not need to write any page rules to accommodate for duplicate content caused by this.
- Use dynamic routing to change the URL structure of your publication, for example, to change
Accessing the redirect file in Ghost
If you're creating redirects for the first time, create a file called
redirects.yaml in your code editor. Upload (and download) the
redirects.yaml file from Ghost Admin (Settings → Labs).
redirects.yaml has two keys:
302. Each key contains a list of redirects. The
301 key contains the permanent 301 redirects. The
302 key contains the temporary 302 redirects. A new Ghost publication has no redirects by default.
Entries to the redirects file follow this structure:
301: /permanent-redirect-from: /permanent-redirect-to /permanent-redirect-from-2: /permanent-redirect-to-2 302: /temporary-redirect-from: /temporary-redirect-to
Enter multiple entries on separate lines. Redirecting to external URLs is possible. It's also possible to use regular expressions.
Creating redirects in
Create redirects by listing the source URL and the destination URL, separated by a colon.
The following examples demonstrate common use cases for redirects in Ghost.
⚡️ Redirect an old URL to a new one
If you update or remove a URL, it's best practice to redirect it. This prevents broken links and your visitors from landing on error pages. It also informs search engines that a page has changed, which is beneficial for your site's SEO.
For example, to redirect
domain.com/new-postname/, include the following in
301: /old-postname/: /new-postame/
⚡️ Redirect your post structure from an existing domain
Redirects are a good option if you're migrating content over from an existing site that used a different post structure than Ghost does.
Here are some common examples of restructuring a Ghost publication:
Category to tag
301: domain.com/category/category-slug/: domain.com/tag/tag-slug/
Date to post name
301: domain.com/blog/year/month/day/post-slug/: domain.com/post-slug/
301: domain.com/search/label/: domain.com/tag/tag-name
With these redirects, someone following an old link will still end up in the right place because they'll be redirected to the new content.
⚡️ Fixing URL discrepancies
As a site grows, content can be duplicated and URLs can change. Consolidate multiple versions of the same URL with redirects. In the example below, we redirect the old URLs
editing, the new one.
301: /editing-a-post: /editing /editing-posts: /editing
Implementing redirects in Ghost
Once you have created your redirects by editing your
redirects.yaml file, upload it in Ghost Admin.
Once the file is in place, test your redirects by visiting any URL that you redirected. Using the example above, visiting
/editing-posts will take you to
/editing in the browser.
Using regular expressions
Use regular expressions (or regex) to write redirects with advanced pattern matching.
A common use case is when migrating content from a platform with a different URL structure. For example, let's say posts used to live on
/blog/post-slug but now in Ghost live at
/posts-slug. While it's possible to write each redirect on a new line, we can use regular expressions to match all possibilities in one line.
The regex matches what comes after
post-1 and redirects to it (
$1 represents the match). With this in place, you can redirect all existing URLs without writing them out one by one.
To remove redirects that aren't working as expected, upload an empty
redirects.yaml file like in the example below.
This will remove all existing redirects on your site.
That’s it. You have discovered the recommended process for implementing redirects in Ghost:
- Create a
redirects.yamlfile or download it from Ghost Admin
- Edit the file to add new redirection rules
- Upload the file in Ghost Admin
This process can be repeated as often as required. All of your redirects will always be stored in one accessible place and are always managed and owned by you.
Have questions about more complex redirects or want to show off some crazy regex you wrote? Come on over to our Forum and have a chat.