-
-
Notifications
You must be signed in to change notification settings - Fork 8.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs version aliases #9049
Comments
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)). |
Hmmm no, React-Router only sees the request once it is served from the redirected-to route.
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 If it's unclear to users how to add the appropriate client-side redirects using |
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. |
@hexsecs you can decide to be explicit and set a version in the url for the current version. IE you can make the 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. |
@hexsecs yes you can setup a server redirect from 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 |
Have you read the Contributing Guidelines on issues?
Motivation
As part of #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 URLFor the "aliased docs", it's possible to use multiple strategies:
/docs/3.2.5/myDoc
contains the same html as/docs/myDoc
/docs/3.2.5/myDoc
contains a client-side redirect (not ideal, would be better handled by a server redirect)More context here: #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
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: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
The text was updated successfully, but these errors were encountered: