fix(redirects): add /current path support for latest version

[mnencia]

The /current and /current/* paths were not accessible, causing 404 errors for external references. This implements native Docusaurus redirects using the createRedirects function to automatically map all /current/* paths to the corresponding paths in the latest version.

Closes #24

[mnencia]

This is an explanation of how it works (thanks, Claude):

How Docusaurus Versioning Works

First, some context. When you build the site, Docusaurus creates pages for each version:

• /devel/ - current development version (from docs/ folder)
• /1.28/ - latest stable version (from versioned_docs/version-1.28/)
• /1.27/ - previous version (from versioned_docs/version-1.27/)
• etc.

The createRedirects Function

The redirect plugin works by:

1. Iterating through every page that Docusaurus generates during the build
2. Calling your createRedirects function with each page's path
3. Creating extra HTML redirect files based on what your function returns

Here's our implementation:

createRedirects(existingPath) {
    // Redirect /current/* to the latest version
    if (existingPath.startsWith(`/${lastVersion}/`)) {
        return existingPath.replace(`/${lastVersion}/`, '/current/');
    }
    return undefined;
}

Step-by-Step Example

Let's trace what happens when Docusaurus generates the page /1.28/installation_upgrade:

1. Docusaurus builds the page: Creates /1.28/installation_upgrade/index.html
2. Calls your function: createRedirects('/1.28/installation_upgrade')
3. Your function checks: Does this path start with /1.28/? → Yes!
4. Your function returns: /current/installation_upgrade (replaced /1.28/ with /current/)
5. Plugin creates redirect file: Generates /current/installation_upgrade/index.html containing:

<meta http-equiv="refresh" content="0; url=/docs/1.28/installation_upgrade">
<script>
  window.location.href = '/docs/1.28/installation_upgrade' + ...
</script>

What This Means

For every page in the /1.28/ version, a corresponding /current/ redirect is created:

• /1.28/ → creates redirect /current/ → redirects to /1.28/
• /1.28/quickstart → creates redirect /current/quickstart → redirects to /1.28/quickstart
• /1.28/installation_upgrade → creates redirect /current/installation_upgrade → redirects to /1.28/installation_upgrade
• And so on for all pages...

Why Return undefined for Other Paths?

When Docusaurus processes pages like /1.27/installation_upgrade or /devel/quickstart:

• The function checks: does it start with /1.28/? → No
• Returns undefined → No redirect is created
• We only want /current/* to point to the latest version (1.28), not older versions

When You Update Versions

When you release version 1.29 and update lastVersion = '1.29':

• All /current/* redirects automatically point to /1.29/* pages
• No code changes needed!

That's the beauty of this approach - it's declarative and automatic.

[gbartolini]

@mnencia I have not been able to make it work. can you please help me?

[mnencia]

@gbartolini i used the following command

cd website
npx yarn
npx yarn build
npx yarn serve

[gbartolini]

I am just using these: https://github.com/cloudnative-pg/docs/blob/main/README.md#installation

[mnencia]

@gbartolini That's why you don't see it. The redirect plugin is production-only and doesn't work in developer mode.

See https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects

[mnencia]

@gbartolini I've created #40 to add a note to the README.md about testing production-only features.