facebook
Docs version aliases
Have you read the Contributing Guidelines on issues?
- [X] I have read the Contributing Guidelines on issues.
Motivation
As part of https://github.com/facebook/docusaurus/issues/3285, it was suggested to give the ability to users to create docs version aliases.
The idea is that a versioned docs set could be made accessible from multiple URLs at once.
The main use-case for this is when you want your upstream docs to be both available on an unversioned and versioned URL at the same time so that external sites can link to the upstream version, or a fixed version depending on context.
For example, /docs/3.2.5/ could be an alias of the "latest version" hosted at /docs/, so that the same doc could be accessed
/docs/myDoc: the canonical URL of the doc/docs/3.2.5/myDoc: the duplicate URL of the doc, referencing the original doc as the canonical URL
For the "aliased docs", it's possible to use multiple strategies:
- duplicate:
/docs/3.2.5/myDoccontains the same html as/docs/myDoc - redirect:
/docs/3.2.5/myDoccontains a client-side redirect (not ideal, would be better handled by a server redirect)
More context here: https://github.com/facebook/docusaurus/issues/3285
Workarounds
Do we need first-class support for this?
For the duplicate strategy
Maybe a postBuild step could be enough to create the aliases? Eventually that could be
cp -R build/docs build/docs/3.2.5
Eventually, this can be implemented in the docs plugin. Does it require any theme code change?
For the redirect strategy
The client-side redirect can probably be used to emit the client-side redirect files already
In any case, it is preferable to use server redirects. Most CDNs allow this (but not GitHub Pages)
Netlify/Cloudflare for example with _redirects file:
/docs/3.5.2/* /docs/:splat 301
You can even implement the "duplicate" strategy this way by using code 200 (rewrite URL) instead of doing a 301 redirect.
As the original issue is much broader and now closed, I'd like to re-open the discussions.
Who needs this, and why?
Aren't the existing workarounds good enough?
Please detail your use-case and give motivations for us to implement this as a first-class feature.
Self-service
- [X] I'd be willing to do some initial work on this proposal myself.
Aren't the existing workarounds good enough?
I'm coming for upstream here to share my request is because I assume this is under the domain of React Route and thus something managed by Docusaurus.
Even with server-side redirections, IIRC, React Route applied first - unexpected 404 can occur. In my use case reported in #3285, it takes some efforts to ensure that links under server-side redirections only available by directly accessing (or open in new tab (_blank)).
Even with server-side redirections, IIRC, React Route applied first - unexpected 404 can occur.
Hmmm no, React-Router only sees the request once it is served from the redirected-to route.
it takes some efforts to ensure that links under server-side redirections only available by directly accessing (or open in new tab (_blank)).
I'm not sure to understand. If you can provide a repro with a concrete example that would help.
Don't duplicate pages have a negative impact on SEO? We shouldn't encourage this strategy.
As for redirects, I agree that server-side redirects are the best solution. If those aren't possible due to the host, then @docusaurus/plugin-client-redirects should be able to address this need?
If it's unclear to users how to add the appropriate client-side redirects using @docusaurus/plugin-client-redirects, we can add example rules to support this specific use case to the documentation.
Don't duplicate pages have a negative impact on SEO? We shouldn't encourage this strategy.
Duplicate pages are fine if you add the canonical URL meta tag, which we would do of course.
Anyway, there are always possible duplicates because sometimes URLs can work with both trailing slash or not, or with lowercase/uppercase chars: different URLs all serving the same HTML file.
Crawlers are not totally stupid, and in our case, 99% of the HTML would be the same so it's not like we are publishing the same content on different domains on 2 sites with very distinct layouts. I'm pretty sure Google wouldn't even penalize us if we had duplicates without the canonical tag.
Note: versioning is also a form of duplicate. Sometimes v1.0.0 and v1.0.1 docs are exactly the same, and have distinct canonical URLs, and that's fine (we have that case on our own website). Unfortunately, as far as I know, there's no SEO meta-tag to indicate versioning to crawlers.
This feature would be much appreciated. To help understand why someone would want this, we use docusaurus for an open security standard for OTA updates. If someone were to reference our standard in their specifications, there are permalinks to older versions, however the latest version is only served as an unversioned URL. So in effect, someone can use a link to an over version, but never directly reference to a pinned version of the current version. So as a specification designer, If 2.1.0 is the current latest version, I have no way to access this version directly, only "latest" or <2.1.0 version. If the document is updated to 3.0.0 and it was a breaking change, previous references to 2.1.0 (because it was the unversioned URLs) no point to an incompatible version hosted at 3.0.0.
Current workaround is the duplicate solution, however there is the flag the permalink version saying that it isn't the latest version.
A better solution is to have the unversioned URL serve up the same content as the versioned section at both the unversioned "latest" and versioned URLs.
So in effect, someone can use a link to an over version, but never directly reference to a pinned version of the current version. So as a specification designer, If 2.1.0 is the current latest version, I have no way to access this version directly, only "latest" or <2.1.0 version. If the document is updated to 3.0.0 and it was a breaking change, previous references to 2.1.0 (because it was the unversioned URLs) no point to an incompatible version hosted at 3.0.0.
@hexsecs you can decide to be explicit and set a version in the url for the current version.
IE you can make the docs folder be served at /docs/1.0.0 instead of /docs
This is documented here: https://docusaurus.io/docs/versioning#configuring-versioning-behavior
@slorber That works for versioning the latest version, but then it creates the opposite problem where I don't have a permanent link for the "latest" version. I have a use case where a user needs to link to both the latest as an unversioned /docs link (so permanently pointing to the latest version) and in other cases point to a pinned version that happens to be the most recent.
Is there a way to make the /docs path link redirect to a particular version? In that case this might be a suitable workaround.
Is there a way to make the /docs path link redirect to a particular version? In that case this might be a suitable workaround.
@hexsecs yes you can setup a server redirect from /docs/xyz to /docs/1.0.0/xyz, and have both links be valid. You can swap the redirect to a newer version when needed.
This is not a Docusaurus feature because it's always better to use server redirects for that instead of redirecting with JavaScript.
This would be a very helpful feature! Our organization has had to do very little tinkering to get Docusaurus to work how we like, but the server side workaround is one quirk that requires some - albeit minor - outside configuration to get working, so it would be great if Docusaurus had first-class support for aliasing.
Thanks Docusaurus team for building such an amazing tool! Y'all are awesome
