Ghost redirect doc suggestions

[ErisDS]

Based on 1) experience of cloudflares page rules guide and 2) John asking whether multi-wildcard was supported in Ghost and 3) planning an update to our redirects feature and not finding all the features documented, I would like to propose some changes to the redirects guide.

I'm starting by proposing problems 😬

Issues I think exist:

1. "regex" could be considered a bit vague (there are different flavours)
2. there's no clarity around double escaping (I still am not sure myself what the rules are)
3. We don't make it clear that "multi wildcard" is supported E.g. you can use $1, $2
4. Case insensitive matching with the i flag is not mentioned
5. It's not clear that temporary redirects are the default
6. Text around the required JSON format could be more explicit
7. Minor Typo: the from field text has an additional word "you"

Possible solutions?

I think there are a couple of small changes that could be made to the text to resolve these things. E.g. using more explicit technical language in a summary somewhere like:

"The from and to fields work exactly the same as javascript's replace function, with full support for regex patterns, the i case insensitivity flag, and multiple matches using $1, $2. "

and also including the phrase "The file must be valid JSON", with the words "valid JSON" being a link to https://jsonlint.com/ (This linter gives clarity on why a file is not uploading). I think some of the text about how JSON works could also be removed or grouped together.

I would also like to propose that we include one advanced example. I'm happy to be shot down for this, but I think a lot of us like to see a super complex example to see what we can achieve (thinking about the trouble with the page rules guide)

My proposed advanced example is similar to our docs redirect, but we could probably find a better one:

{
   "from": "^/(v.*?)/docs/([a-z0-9_\-]+)(\\/)?$/i",
    "to": "/$1/$2/"
}

It includes: advanced pattern matching in JS, the need for double-escaping when using regex, 2 wildcards and the i flag all in one fell swoop, but note that I'm not really sure where and when I need to use a double backslash escape here.

It maybe that all this is waaaay to technical for the 90%. My main suggestion is really to either use more explicit language to be clearer what does and doesn't work e.g. say "valid JSON" and "javascript regex" and let people use the rest of the internet to determine what those phrases mean.

Happy to have a stab at a PR for this if folks agree.

[kymellis]

@ErisDS

I think there’s definitely room for more technical information about redirects in Ghost on the concepts page - seems like there is some missing information based on your list of issues. I rewrote this page during the docs project to the best of my knowledge using old docs as reference. I don’t fully understand the missing issues - so do you want to submit a PR and we can work on improving it together?

We do also have a tutorial for redirects, which is more of a getting started/implementation guide. The two should probably link to each other, but the article in Concepts should include any technical references that cover a wide range of use-cases.

If you have any improvement suggestions for the tutorial then you can send those to me either in this issue or another channel, the content exists in Ghost.

[ErisDS]

o_0 I totally missed that there was a tutorial! I was referring only to the concepts page. Seems like a lot of the info that I thought was missing is actually in the tutorial. l

I'll review both properly, and then come back with any recommendations 👍