Home link to versioned URL

[timothymamo]

Current State

We are currently migrating our documentation from Sphinx to Docusaurus. We've deployed our test site, e.g. https://docs-site-test.com, on S3 served via CloudFront as described here (CloudFront Function and all).

Our current documentation is served at https://docs-site.com/latest/ (with versioning served at https://docs-site.com/<version-number>/) and uses S3 and CloudFront as hosting. Linking to https://docs-site.com redirects to https://docs-site.com/latest/. This isn't done via CloudFront but is by default with Sphinx.

When deploying our Docusaurus test site, everything works as if on localhost but if I enter the base url https://docs-site-test.com I get a blank page with the navbar and footer only. This also happens when running locally, i.e. if I point my browser to http://localhost:3000 I have the same blank page. If I directly point to http://localhost:3000/latest/ I get the docs as desired.

We are using Docs Only mode and have a intro.md file for the homepage and removed the ./src/pages/index.js as pointed out in the documentation.

Wanted Outcome

We would like to have the site serve http://localhost:3000/latest/ when calling http://localhost:3000. We tried changing the baseURL and/or the routeBasePath options in our docusaurus.config.ts file but this arises in 2 issues:

1. versioned documentation is served at http://localhost:3000/latest/<version-number> (tried hacking it by adding path: '../<version-number> in our versions file but this throws a warning that links are broken for the version when a build occurs
2. CloudFront causes a rendering issue similar to what is described in the second portion of this blog post

Question

What's the correct configuration to do this (assuming this is possible)?
I tried the fix suggested in the following comment but http://localhost:3000 doesn't redirect to http://localhost:3000/latest. Unsure if it's outdated and/or if there is a more straight forward option to do this.

---

Below are snippets of our docusaurus.config.ts file:

...
import { globalVariables, versions } from './constants'
...
const config: Config = {
  url: 'https://docs.kasten.io',
  baseUrl: '/',
...
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          routeBasePath: '/',
          versions: versions,
          lastVersion: '1.0.1',
          includeCurrentVersion: false
        },
...
      } satisfies Preset.Options,
    ],
  ],

  markdown: {
    preprocessor: ({filePath, fileContent}) => {
      var key = '';
      var found = false;
      for (key in globalVariables) {
        let folderName = (key == 'current' ? 'current' : `version-${key}`);
        if (filePath.includes(`/${folderName}/`)) {
          found = true;
          break;
        }
      }
      if (key == '' || !found) {
        key = 'current';
      }
      let content = fileContent;
      for (const variable in globalVariables[key]) {
        content = content.replaceAll('@'+variable+'@', globalVariables[key][variable]);
      }
      return content
    },
  },

  themeConfig: {
...
    navbar: {
      title: 'Our Docs',
      logo: {
        alt: 'Our Docs',
        href: '/latest/',
      },
      items: [
...
        {
          type: 'docsVersionDropdown',
          position: 'right',
          dropdownActiveClassDisabled: true,
        },
...
    },
    footer: {
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Docs',
              to: '/latest/',
            },
          ],
        },
...
    },
...
  } satisfies Preset.ThemeConfig,
};

with the following files:
constants.ts

export const globalVariables = {
  '1.0.1': {
    'version': '1.0.1',
    'displayVersion': '1.0.1',
...
  },
  '1.0.0': {
    'version': '1.0.0',
    'displayVersion': '1.0.0',
  }
}

export const versions = {
  '1.0.1': {
    label: '1.0.1',
    path: 'latest'
  },
  '1.0.0': {
    label: '1.0.0',
  },
}

and versions.json

[
  "1.0.1",
  "1.0.0"
]

[slorber]

It's impossible to help you without a runnable repro. If your site contains sensitive data, you can still remove that data and create a similar setup. Also if you choose to use CloudFront (which is not the ideal host for static sites) it's your responsibility to make it work. I'm not a CloudFront expert and can't troubleshoot it for you. Assume that the community blog posts you read may be wrong.

---

That being said, if you only have the docs plugin enabled, with baseUrl: '/', routeBasePath: '/' and latestVersion.lastest.path: 'latest', then you have the wrong expectation.

Docusaurus responsibility is only to build a static site. If your site's setup makes it so that there is no website/build/index.html file being produced, but only a website/build/latest/index.html, then it's normal that you can't "browse" the root of your site, because there's nothing at that address.

What happens when you access https://example.com/ when there's no /index.html is a hosting concern. Depending on your host, you should configure server-side behaviors so that it either serves /latest/index.html or redirects to /latest. Some hosts (GitHub pages) do not allow to configure such behavior, but I'm pretty sure CloudFront does.

Docusaurus has no "server runtime". It can only emit files at build time. It can't "redirect" a request. At best it could emit a /index.html file that will only perform the redirect client-side (which is what our client redirect plugin does, but it is not ideal and you'd rather use server redirects instead)

---

TLDR: to help you more than that, we need a runnable minimal repro

We'll only troubleshoot using docusaurus serve, or look at files produced on the file system.

[timothymamo]

Hi @slorber, thanks for the reply. If I could, I would have shared the repo, but unfortunately the documentation is in a private repo. At times you have to work with what you are given, like deploying on S3 and CloudFront (which has been used to serve static sites for a fair few years now, even more so with the introduction of CloudFront Functions/Lamda@Edge). The community blog post linked is correct (the vast community Docusaurus has was one of the reasons we chose to use it).

Though your explanation did trigger me to look into what was being built (as I was creating a dummy minimal repo as suggested), and obviously there was no /index.html file in the build director as I had removed it from the ./src/pages directory. Adding the same intro.md file used in latest in ./src/pages did create a homepage. at times you need to rubber duck the problem.

This though didn't do exactly what I wanted. I managed to achieve what I wanted by adding the following tag in the intro.md file

<head>
  <meta http-equiv="Refresh" content="0; url='/latest/'" />
</head>

Wanted to comment should anyone find this useful. I've closed the Discussion as I've solved my problem.

[slorber]

Yes, this works and is a client-side redirect. Note that it's preferable to use server-side redirects, whenever possible to only use this as a workaround when you can't easily create server redirects for various reasons.