Redirects

How to add redirects to your Ghost install

Use Nginx or Apache if you can

If you have access to your web server, and can add your redirects there, we'd always recommend doing this instead, as it's more performant and standardised.
If you don't have access to your webserver, Ghost's redirects are the next best thing 🙂

New redirects.json upload/download interface in Ghost 1.9.0+

As of Ghost 1.9.0 there is a new Labs feature where you can download and upload your redirects.json file within the admin interface. When using the admin interface there's no need to edit the file directly on your server or to restart Ghost after uploading.

Warning: Uploading a redirects.json file using the admin interface will overwrite any existing redirects.json file. Ensure you download the current redirects and edit the file before re-uploading to avoid accidental removal of existing redirect rules.

Purpose

You can define your own HTTP redirects for your Ghost blog.

File Structure

The redirects file is a JSON file and needs to be located in content/data/redirects.json.

The file starts with a [, ends with a ] and each entry in the redirects file has the following structure (with multiple entries separated by , and the last entry without the ,):

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

from

With the from field you can define the incoming url pattern. The value is in most of the cases a regular expression.

For example from: \/blog/([a-z0-9-]+)\/ means: Match all urls starting with /blog/ and is followed by numbers and letters e.g. /blog/new-york1998. So regular expressions can help you matching a group of urls.

But you can also just a define a static url like from: /my-post/.

to

With the to field you can define where the incoming traffic should be redirected to. It can be a static url e.g. redirect to /my-blog/.

If your from field contains a dynamic value, you have access to this value using regex groups.

For example:

"from": "^/post/[0-9]+/([a-z0-9\\-]+)",
"to": "/$1/"

$1 represents the value between the two round braces.

permanent

Is a Boolean. Permanent redirects (301) can be defined with permanent: true, otherwise we use 302 redirects as the default configuration.

Full Example:

Common patterns/examples

With or without trailing slash

code: (\\/?)$

For example redirecting /recipes/ with or without the trailing slash, to /tag/recipes/.

[{
    "from": "^\\/recipes(\\/?)$",
    "to": "/recipes/"
}]

Redirect your post structure from domain.com/post/year/post-name/ to domain.com/postname/

[{
    "from": "^/post/[0-9]+/([a-z0-9\\-]+)",
    "to": "/$1/"
}]

Redirect your domain.com/old-postname/ to your domain.com/new-postname/

[{
    "permanent": true,
    "from": "/my-old-blog-post/",
    "to": "/revamped-url/"
},
{
    "from": "^\\/what(\\/?)$",
    "to": "/what-does-god-say/"
},
{
    "from": "/something/",
    "to": "/what-does-god-say/"
}]

Redirect your search label URL (/domain.com/search/label/label-name/) to your new tag URL (domain.com/tag/tag-name/)

[{
    "from": "^\\/search\\/label\\/([^\\%20]+)$",
    "to": "/tag/$1/"
}]

Redirect a category (/domain.com/category/) to the root URL (domain.com/)

[{
    "from": "^\\/topic\\/",
    "to": "/"
}]

Redirect from a blog, year, month & day URL structure (/domain.com/blog/2018/01/post-name.html) to the same format Ghost story URL (domain.com/2018/01/post-name/)

    {
        "from": "^\/blog\/([0-9]{4})\/([0-9]{2})\/([a-z0-9-]+)(.html)?(\/)?$",
        "to": "/$1/$2/$3/"
    }

Other examples

    {
        "from": "^/resources\\/download(\\/?)$",
        "to": "/shubal-stearns/"
    },
    {
        "from": "^\\/[0-9]{4}\\/[0-9]{2}\\/([a-z0-9\\-]+)(\\.html)?(\\/)?$",
        "to": "/$1/"
    },
    {
        "from": "^/prefix/([a-z0-9\\-]+)?",
        "to": "/blog/$1/"
    },

If you uploaded the .json file through the Ghost Labs admin interface, your changes have already applied and your redirects should already be working.

If you modified the .json file on the server (not recommended), restart ghost for the changes to take effect.


ghost restart

Not sure about regular expressions (regex) ?

The best resource on the web to help with designing regular expressions is https://regex101.com/.

Once on the page, click "javascript" on the left hand side to use the most compatible mode. Then, in the top bar click the flag icon and also select "multiline".

Now, you can enter your pattern in the top bar, and then enter the paths you want to match, one-per-line, in the box below to check that your pattern works.

On the bottom right-hand-side, you'll find the "Quick Reference" with many examples of useful building blocks.

Redirects

How to add redirects to your Ghost install