Developer docs

Implementing redirects in Ghost

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 redirects.yaml file 🙃
  • Accessing the redirects.yaml 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.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 redirects.yaml 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.yaml file is located in content/data/redirects.yaml and can be downloaded and uploaded in the settings in Ghost admin.

File structure

The file has two keys: 301 and 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.yaml

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

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 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.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/ ,/OSX/ ,/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 </> 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.yaml 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.