Redirects to static content don't redirect

[marikaner]

🐛 Bug Report

In our docs, we have API docs listed by version. I wanted to add a link that always points to the latest version of the API docs, aka: api/latest/ should redirect to api/1.28.1/ e. g.
The url is correctly replaced, but the redirect does not happen and I am left with a "Page not found" error. The status code is 200, while I would expect a 301. When reloading the page I am actually presented with the correct document.

Have you read the Contributing Guidelines on issues?

Yes.

To Reproduce

1. Have a redirect to static content.

Expected behavior

Redirects to the linked page and status code 301.

Actual Behavior

Replaces link correctly, but has status code 200 and content is "Page not found".

Your Environment

• Docusaurus version used: 2.0.0-alpha.63
• Environment name and version (e.g. Chrome 78.0.3904.108, Node.js 10.17.0): Chrome 85.0.4183.83
• Operating system and version (desktop or mobile): macOS 10.15.6

Reproducible Demo

Speaking in docs sources

This is the file that is supposed to induce the redirection:
https://github.com/SAP/cloud-sdk/blob/documentation/src/pages/api/latest.mdx

to e. g. this file https://github.com/SAP/cloud-sdk/blob/documentation/static/api/1.28.1/index.html

Speaking in links

https://sap.github.io/cloud-sdk/api/latest/ should redirect to https://sap.github.io/cloud-sdk/api/1.28.1/

[slorber]

Hi

What you are looking for is the "version alias" feature, that I plan to implement as part of this RFC, probably in October: #3285

We also have a redirect plugin BTW, maybe it will work better for your use case, as it will be able to redirect URLs like /docs/latest/myDoc too, not just /docs/latest/
https://v2.docusaurus.io/docs/using-plugins/#docusaurusplugin-client-redirects

I think your solution looks fin, and wonder if it does not work because of the trailing slash. Maybe you should try to remove the trailing slash and see if it works better?

<Redirect to={useBaseUrl(`api/${latestJsRelease}`)} />

I don't know what is happening, but Redirect is the raw redirect from ReactRouter, it does not do anything special so this is weird.

[slorber]

Ohhh but wait, this page is not managed at all by docusaurus right?

https://sap.github.io/cloud-sdk/api/1.28.1/

Docusaurus/React won't even be able to render such an external page, that's why it shows Docusaurus 404

You can't Redirect to external pages with the Redirect component, this is for redirecting client-side with SPA-like navigation (based on history.push("")). If you want to redirect to another page, you have to do something like window.location.href = "myExterrnalUrl". The redirect plugin can help you doing so, but you can probably inline a js script that do so too.

Also worth mentioning that if you can afford it, you'd rather perform redirects at the server level (http status 302 etc). Unfortunately it is not possible with Github but it is easy on other hosts like Netlify or Vercel that I'd recommend you to adopt, as they are very easy to setup and will give you a much better experience (including deploy previews in each doc modification PR)

[marikaner]

Hey @slorber,

thank you for your response. I tried various combinations of the urls - with slashes, without and also linking to the index.html directly. I think you are right, this is not managed by docusaurus, because we had a similar issue before, when we tried linking to the api docs from a different page. This resulted in a broken link error, which we were only able to solve by using the absolute link.

I think I got some inspiration from your comments on how to solve this symptom, but I would actually like to have these pages managed by docusaurus as well. Is there a recommended way on how to include generated api documentation? We currently add it as static content.

[slorber]

Hey @marikaner, I understand that it might be useful that Docusaurus is aware of this /docs/latest route, otherwise it will be reported as a broken link if you try to link to it, right?

I was able to do something like this, but it's a bit hacky:

---
id: redirect
title: redirect
---

import {Route} from '@docusaurus/router';

<Route
  path={'/*'}
  component={() => {
    global.window && (global.window.location.href = '/docs/v123');
    return null;
  }}
/>

The problem is that you first have to navigate to an empty doc page before being redirected so the user feedback feels a bit weird.

---

But your problem is actually that you want to navigate to a path of the subdomain, but that Docusaurus don't know about.

Unfortunately, we don't have yet a good API surface to solve this problem, but this is related to other issues:

• Links validation failures after updating to 2.0.0-alpha.61 #3303
• Unability to link to an internal non-SPA link #3309

So, technically, you should be able to link to your version using something like [latest docs](pathname:///api/1.28.1) (pathname is the escape hatch). This wouldn't be reported as a broken link. Unfortunately this wouldn't be dynamic, so if you want an dynamic like, the best could be to implement a LatestVersionLink component or something, and use it in mdx files.

---

My suggestion for your usecase would be:

• link to this page: [latest docs](pathname:///api/latest)
• use preferably a server 302 http code to redirect /api/latest to /api/1.28.1
• fallback: use the redirect plugin to redirect /api/latest to /api/1.28.1

I don't think the latest page should be managed as a docusaurus document, as it involves the tradeoff of loading React, hydrating, displaying an empty doc even before being to navigate, so this gives a weird UX.

[marikaner]

Hey @slorber,

I was able to use the workaround for links unknown to docusaurus, when linking directly. In the second step I tried to follow your suggestion and redirect using the redirect plugin (server redirects are unrealistic right now).
Unfortunately I am unable to make it work with paths that are unknown to docusaurus:

Error: You are trying to create client-side redirections to paths that do not exist:
- /api/1.28.1/

This is my configuration:

plugins: [
    [
      '@docusaurus/plugin-client-redirects', {
        redirects: [
          {
            from: '/api/latest',
            to: `/api/${latestJsRelease}/`
          }
        ]
      }
    ]
  ]

I cannot use the pathname workaround here as it gives me this error:

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

[slorber]

Oh you are right, the redirect plugin is made to redirect to existing docusaurus pages. And when I said to use pathname:// it was for markdown links, not

The solution could be to add this redirect in ./static/api/latest/index.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
  </head>
  <script>
    window.location.href = 'api/1.28.1';
  </script>
</html>

If you need it to be dynamic, you should generate this file as a build step and put it in the generated /build folder.

As long as at the end of the build, you have an HTML file that redirects (in ./build/api/latest/index.html or ./build/api/latest.html), this should work, there are just many ways to ensure this file exist ;)

[Josh-Cena]

Closing as it seems to be rather a question... window.location.href would just work.