When managing a website of any nature, implementing URL redirects is a commonly used practice. Redirection is the process of forwarding one URL to a different URL. They are most commonly used when removing or moving content on your site, to fix broken links, or to migrate content between different domains.
In Ghost, implementing redirects can be done by accessing a simple YAML file
redirects.yaml in Ghost Admin. This file can be downloaded, edited with code and reimported into the admin interface.
If you’ve updated your site from an earlier version (prior to 4.0), your redirects may be in JSON format. Both formats are still supported, but JSON support will be removed in a later version.
This tutorial will walk you through:
- When not to use the
- Accessing the
redirects.yamlfile and the basics of it’s structure
- How to create your own redirects with code with common examples to 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.
- If you are trying to change the URL structure of your publication, the recommended way to do this is with dynamic routing and the
routes.yamlfile. However, you may still need to redirect existing content following this tutorial.
Accessing the redirect file in Ghost
redirects.yaml file is located in
content/data/redirects.yaml and can be downloaded and uploaded in the settings in Ghost admin.
The file has two keys:
302. Each key contains a list of redirection. The
301 key contains the permanent 301 redirects. The
302 key contains the temporary 302 redirects. A new ghost publication will have an empty redirect file. It can be edited in any source code editor.
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
Multiple entries are separated by a line return. Redirecting to external URLs is possible. It is also possible to use regular expressions.
Creating redirects in
Redirects can be created by listing the source url and then destination url separated by a colon. Regular expressions (regex) can be used to determine incoming URL patterns, or dynamic values for the final destination.
The following examples are some common use cases of redirects for a Ghost publication.
⚡️ Redirect an old URL to a new one
If you update or remove a URL it is best practice to redirect it. This prevents broken links and your visitors landing on error pages, and is beneficial for SEO if the search engines have indexed that page(s) that you have removed or changed.
For example, to redirect
domain.com/new-postname/, include the following in the
301: /old-postname/: /new-postame/
It is also possible to use regex to find URL patterns and redirect all URLs that match that pattern. For example:
301: ^\\/blog/old(\\/?)$: /blog/new-postname
This is useful if you need to redirect several versions of the same URL, or have patterns of posts which have a common string.
⚡️ Redirect your post structure
There are lots of examples where you may want to redefine the URL structure of the content on your site. The recommended way to do this is with dynamic routing in your
One of the benefits of using an open source platform like Ghost is that there are almost infinite ways to customise your publication. You have the ultimate flexibility. Here are some common examples of restructuring a Ghost publication:
- Category - from
- Date - from
- Author - from
- Tag - from
- Search labels - from
For examples like this, dynamic routing is recommended because it will enforce the desired structure for all new content on your site. However, if you already have existing content or are migrating content from another platform, then you
then you can use the
redirect.yaml file to ensure all existing content is properly redirected too.
⚡️ Fixing URL discrepancies
Sometimes there can be multiple versions of the same URL that need to be consolidated.
For example, in some cases there may be a problem with upper and lower case in a URL, such as
/OsX/. These can all be redirected to
/MacOS/ using regex like so:
302: /\/osx/i: /MacOS/
Implementing redirects in Ghost
Once you have created your redirects by editing your
redirects.yaml file, upload it in Ghost admin in the Labs menu. This is the recommended method.
If you would like to replace the YAML file on the server it should exist in
content/data/redirects.yaml and you’ll need to run
ghost restart for your changes to take effect.
Once the file is in place you can test your redirects by visiting any URL that you are redirecting in your browser and ensuring it is being redirected as you would expect.
Using regular expressions
There are lots of different ways to implement redirects using regex. The best resource to assist with designing regular expressions for a wide variety of use cases is regex101. Using this tool you can select the
This tool allows you to enter your pattern in the top bar, and then the paths you want to match (one per line) and also provides useful building blocks and suggestions.
That’s it. You have discovered the recommended process to implementing redirects for your Ghost publication:
- Download the
redirects.yamlfile from Ghost admin
- Edit the file and use code 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.