facebook / facebook/docusaurus
Docs version aliases
- Lingua principale
- TypeScript
- Stelle
- 66.2k
- Fork
- 10k
- Merge medio
- 1g 3h
- PR unite (30g)
- 52
Descrizione
### Have you read the Contributing Guidelines on issues?
- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#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/myDoc` contains the same html as `/docs/myDoc`
- redirect: `/docs/3.2.5/myDoc` contains 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
```bash
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.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.