facebook / facebook/docusaurus

Docs version aliases

未关闭
#9,049 10 条评论 5 个 reaction 已指派 0 人 在 GitHub 查看
proposal
主要语言
TypeScript
星标
66.2k
派生
10k
平均合并
1 天 3 小时
30 天内合并 PR
52

描述

### 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.

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。