plugin-client-redirects should allow fully resolved URIs

[zpao]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Prerequisites

• [X] I'm using the latest version of Docusaurus.
• [ ] I have tried the npm run clear or yarn clear command.
• [ ] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• [ ] I have tried creating a repro with https://new.docusaurus.io.
• [ ] I have read the console error message carefully (if applicable).

Description

It can be useful for several reasons to have redirects off of the website. That requires using a fully resolved URI. While HTTP redirects are generally preferred it's not always an option.

Reproducible demo

No response

Steps to reproduce

Configure plugin-client-redirects with a to that includes a fully resolved URI (protocol & domain)

Expected behavior

Build succeeds

Actual behavior

Error: Invalid @docusaurus/plugin-client-redirects options: "redirects[0].to" is not a valid pathname. Pathname should start with slash and not contain any domain or query string.

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• [ ] I'd be willing to fix this bug myself.

[Josh-Cena]

Technically we can allow queries and fragments as well. No idea why that isn't the case

[slorber]

Yes we could allow external URLs

@zpao what are you trying to do exactly?

This redirect plugin is a best-effort but it's preferable to use server-side redirects if your host supports it (and Netlify/Vercel do), so I'd only recommend this plugin for GitHub Pages users

---

Technically we can allow queries and fragments as well.

@Josh-Cena what do you mean here? ?query=string#hash?

---

I don't remember exactly but I think my initial goal 2 years ago was to ensure that the redirect destination exists to prevent possible user mistakes

[Josh-Cena]

Yes, like to: "/theme#swizzling". Use-case is when multiple pages are combined into one page under different headings. It could also happen that one page is split into multiple ones and we want to redirect each fragment to a page, but that's much harder, so just focusing on the simple case here.

I think the schema only allowing pathnames for to is a bit weird. We should have allowed any valid URL in the first place

[zpao]

I don't remember exactly but I think my initial goal 2 years ago was to ensure that the redirect destination exists to prevent possible user mistakes

That's a good goal, but feels overly prescriptive. People may split sites or things something an need to redirect some parts of content. Do you actually ensure the destination exists or is it just a check that it stays within

This redirect plugin is a best-effort but it's preferable to use server-side redirects if your host supports it (and Netlify/Vercel do), so I'd only recommend this plugin for GitHub Pages users

Fair! I feel the same, but also wanted something quick to just work, even if hosted on a service that supports it. Another thing worth thinking about is making the plugin the place to store this data and having it generate different output targets. That way switching between gh-pages, netlify, vercel, etc can be a single line change in the docusaurus config. But that's beyond the scope of the issue here (and maybe doesn't fit with the name client-redirection).

[slorber]

Do you actually ensure the destination exists or is it just a check that it stays within

It ensures that it redirects to a valid SPA Docusaurus route afaik but we can remove those restrictions

---

Another thing worth thinking about is making the plugin the place to store this data and having it generate different output targets. That way switching between gh-pages, netlify, vercel, etc can be a single line change in the docusaurus config.

That's what Gatsby does with its createRedirect api and its dedicated Vercel / Netlify / Gatsby... plugins, outputting vercel.json or Netlify _redirects files...

IMHO that's convenient for simple cases, but it can get quite complicated fast, as each host has a different behavior, capabilities, and syntax (edge vs serverless, ability to redirect subdomains, syntax to redirect many subroutes, conditional redirects...)

If we do this we should decide on a limited set of supported hosts and abstraction to cover only the most simple cases.

I'm not sure it's a good idea to invest time in this abstraction now. Having a good documentation page about redirects (server or client) may be good enough: it's easy to create a website/static/_redirects or website/vercel.json file if it's what we advise with links to the respective official docs.

[qrkourier]

website/static/_redirects appears to be CloudFlare Pages-specific. I'm still looking for a Docusaurus way of configuring arbitrary server-side redirects. My use case is that I want to provide a short, convenient URL in my Docusaurus site that redirects to a much longer external URL that works with cURL.

[qrkourier]

I failed to mention I'm using GitHub Pages. I see it was mentioned that GH Pages doesn't support server-side redirects, hence the need for the redirects plugin. I think this means there's not a way to create arbitrary server-side redirects with Docusaurus + GH Pages unless the redirect's target is internal to the Docusaurus site.

[slorber]

_redirects is used by Netlify and Cloudflare Pages (more recent). Vercel has vercel.json, and other hosts have similar settings.

There is no way (even for internal site links) to add server-side redirects using GitHub Pages (unless they decide to evolve the service). The client-redirect plugin can only create client-redirects.

Even if we add a Docusaurus feature some day, it will not support all target platforms (ie GitHub pages), and will have to limit itself to the common ground that most of these platforms support (ie simple redirect syntax with an exhaustive list of from/to URLs).

It's quite common to redirect things like /docs/v12/* => /docs/*` and already outside of the subset we can support. So really you'd rather use host-specific config instead of expecting Docusaurus to provide an abstraction

[inconshreveable]

Just chiming in that we could really us fragments as part of the target for exactly the mentioned use case of combining multiple pages into one. Anything I can do to help? Is it more complicated than making the validation less prescriptive?

[siilike]

This would be very useful. For example, when adding documentation links to an application it is a good idea to add them as redirects, so the documentation team can manage the links destination without having to update the application.

Here's at least a partial solution: https://github.com/facebook/docusaurus/commit/efbcedd28c252a17d5f717266c1eb180f1d0aa49

[inconshreveable]

😍 😍 thank you so much @slorber!