Support permanent versioned URLs for "current" version

[rikoe]

🚀 Feature

Docusaurus should support version-based permalinks for the current version of the documentation.

The current version does not have a versioned link until it becomes a previous version, meaning that it is not possible to provide a permalink to the current version.

E.g. docs/doc1.html points to version 2.0.0 (the current), and docs/1.0.1/doc1.html points to the previous version, but there is no docs/2.0.0/doc1.html until a new version comes around.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

Not being able to provide a permalink to a particular version of the documentation from the start is problematic. The unversioned URLs (e.g. docs/doc1.html) could be pointing to version 2.0.0 now, but in a few months' time could be pointing to version 2.0.1 or 3.0.

We have worked around this with the current version of Docusaurus by introducing a "hidden" version at the top of versions.json, but using defaultVersionShown to pick a later version.

This means that the "current version" has versioned URLs, but it also means that there are no default "unversioned" URLs, which is a bit of a pain. The reason we had to do this is because of related communications that need to refer to the current version (1.0 in our case) specifically, not "any" version.

See https://fdc3.finos.org for the Docusaurus-based website where we used this workaround.

Pitch

The pitch is that for the current version there should be two valid ways to address it: with unversioned URLs, which are the default when browsing to the website, and which change version over time.

But there should also be versioned URLs that work correctly for the current version. Effectively the "unversioned URLs" becomes aliases for the versioned URLs of the current version - they are a "pointer" that moves on to the next version, while the versioned URL always stays fixed.

[amimas]

I was going to raise this request soon. Glad to see someone else opened it already.

[rikoe]

@endiliey If I wanted to add a PR for this, would it be better to wait for v2?

[endiliey]

cc @yangshun

i dont recommend having new feature like this because we plan to rework on our versioned docs for v2 and it will make it harder to migrate later on

[rikoe]

@endiliey shouldn't we keep this open though, or recreate the same issue for v2? Quite a few people have expressed interest in the same feature. Otherwise we may lose track.

[endiliey]

File it here https://v2.docusaurus.io/feedback

[amimas]

@rikoe - would you be able to share some details on how you've worked around it in V1?

[sonicdoe]

To follow up, this feature request has been filed with Docusaurus v2.

[Marcono1234]

The feature request mentioned above says this is "Complete", but without providing any additional comment.

Does someone know how exactly has this been implemented? Is the intended solution to use lastVersion: 'current'?
But if I understand it correctly (and as described in facebookresearch/hydra#2321), that means there won't be a /next/ version URL anymore and instead that version becomes the one shown by default, which might not be desired either if that represents the documentation for the not yet released upcoming version.

[Josh-Cena]

@Marcono1234, this issue is for Docusaurus v1. In v2+, the easiest solution is to add a redirect. As mentioned above: #1312 (comment), there's also a feature request for v2 already.

[Marcono1234]

As mentioned above: #1312 (comment), there's also a feature request for v2 already

@Josh-Cena, yes I was referring to that feature request but the state there just says "Complete" without providing any additional information about how this was implemented.

Regarding configuring a redirect, that would have to be done manually though (and updated whenever you release a new version), right? But there is no feature to automatically add a permalink and redirect for the current version?

[slorber]

@Marcono1234 I don't remember why I marked that feature request as completed. Maybe I thought it was just about adding a permalink metadata 🤷‍♂️

Anyway, the issue to track for v2 is: #9049

But there is no feature to automatically add a permalink and redirect for the current version?

No, but you can easily automate this with a pre or post build script. Generating redirects with code remains achievable.