facebook / facebook/docusaurus

Allow to set custom path for versioned docs

Open
#11,288 11 comments 0 reactions 0 assignees View on GitHub
proposal status: needs triage
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

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

This issue is a continuation of the discussion started in https://github.com/facebook/docusaurus/pull/10852#issuecomment-2913291211.

I would like to generate my own `versioned_docs` and `versions.json` out of my release branches like `v1` and `v2` instead of maintaining them all in the main branch.

Take my sample repository: https://github.com/felipecrs/docusaurus-sample-branched-versions

```console
$ git clone https://github.com/felipecrs/docusaurus-sample-branched-versions
$ cd docusaurus-sample-branched-versions
$ npm install
$ npm start
```

`npm start` will also execute `./prepare_versioned_docs.sh` which in turn will generate `versioned_docs/` and `versions.json`.

Each directory inside `versioned_docs/` will be a copy of the current repository at the specific release branch.

Right now, it does not work because it expects the `docs` directory to be the root of the _versioned_ doc.

And even if it worked, edit URLs would not, as they are not within the same branch as the current docs.

Thus, I think the only thing I really need to make this work is being able to override the versioned docs path and their edit URLs through the `versions.json`. Something like:

```json
[
"v2": {
"docsPath": "./versioned_docs/version-v2/docs",
"editUrl": "https://github.com/felipecrs/docusaurus-sample-branched-versions/tree/v2/"
},
"v1": {
"docsPath": "./versioned_docs/version-v1/docs",
"editUrl": "https://github.com/felipecrs/docusaurus-sample-branched-versions/tree/v1/"
}
]
```

### Self-service

- [ ] I'd be willing to do some initial work on this proposal myself.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.