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 JSON file redirects.json in Ghost admin. This file can be downloaded, edited with code and reimported into the admin interface.

This tutorial will walk you through:

  • When not to use the redirects.json file 🙃
  • Accessing the redirects.json file 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.json

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 redirects.json file:

  • 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.yaml file. However, you may still need to redirect existing content following this tutorial.

Accessing the redirect file in Ghost

The redirects.json file is located in content/data/redirects.json and can be downloaded and uploaded in the settings in Ghost admin.

File structure

This file always starts with a [ and ends with a ]. A new ghost publication will have an empty redirect file containing[]. It can be edited in any source code editor.

Entries to the redirects file follow this structure:

{
  "from": "/url/" ,
  "to":  "/url/",
  "permanent": true | false
}

Multiple entries are separated by , and the last entry does not have the ,. It is also possible to use regular expressions.

Creating redirects in redirects.json

Redirects can be created using the three fields in the file structure and regex can be used to determine incoming URL patterns, or dynamic values for the final destination.

  • The from field you defines the incoming URL or pattern (regex)
  • The to field defines where the incoming traffic should be redirected to, which can be a static URL, or a dynamic value using regex (example: "to": "/$1/").
  • The permanent field can be defined with true for a permanent 301 redirect, or false for a temporary 302 redirect.

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/old-postname/ to domain.com/new-postname/, include the following in the redirects.json field:

[{
    "from": "/old-postname/",
    "to": "/new-postname/",
    "permanent": true
}]

It is also possible to use regex to find URL patterns and redirect all URLs that match that pattern. For example:

[{
    "from": "^\\/blog/old(\\/?)$",
    "to": "/blog/new-postname",
    "permanent": true
}]

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 routes.yaml file.

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 domain.com/blog/post-name/ to /domain.com/news/post-name/
  • Date - from domain.com/blog/year/post-name/ to domain.com/postname/
  • Author - from domain.com/author/author-name/ to domain.com/host/author-name/
  • Tag - from domain.com/tag/post/ to domain.com/topic/post/
  • Search labels - from domain.com/search/label/ to domain.com/tag/tag-name

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.json 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/ ,/OSX/ ,/OsX/. These can all be redirected to /MacOS/ using regex like so:

{
    "from": "/\\/osx/i",
    "to": "/MacOS/"
}

Implementing redirects in Ghost

Once you have created your redirects by editing your redirects.json file, upload it in Ghost admin in the Labs menu. This is the recommended method.

If you would like to replace the JSON file on the server it should exist in content/data/redirects.json 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 </> javascript option.

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.

Summary

That's it. You have discovered the recommended process to implementing redirects for your Ghost publication:

1. Download the redirects.json file from Ghost admin
2. Edit the file and use code to add new redirection rules
3. 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.