facebook / facebook/docusaurus

Output directory of versioning - `{PLUGIN_INSTANCE_ID}_versioned-docs` should be configurable

オープン
#8,061 コメント 22 件 リアクション 1 件 担当者 0 名 GitHub で見る
domain: content plugin feature
主要言語
TypeScript
スター
66.2k
フォーク
10k
平均マージ
1日 3時間
マージ済み PR(30日)
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#reporting-new-issues).

### Description

I want to organize the project to place the docs Markdown directories outside of Docusaurus root. .
```
/my-project
/my-docs-outside
/main.md
/docusaurus-website
/docusaurus.config.js
```

I configure docs location in`docusaurus.config.js`:
```
...
presets: [
[
'classic',
({
docs: {
// ...
path: '../my-docs-outside', // <<===
},
],
],
```

To tag and create a copy of the current version I run
`docusaurus docs:version v2`

It creates the versions in Docusaurus root, and I can't configure it otherwise.
```
/my-project
/my-docs-outside
/main.md
/docusaurus-website
/docusaurus.config.js

//*** new files: ***
/versions.json
/versioned_docs
/version-v2
/main.md
/versioned_sidebars
/version-v2-sidebars.json
```

It makes sense to have `versions.json` in Docusaurus root as it is a configuration file, but the actual Markdowns should at least consider the configured location of the other Markdowns, or be configurable.

### Has this been requested on Canny?

_No response_

### Motivation

It's reasonable to assume that all files input and output entires would be configurable.

It makes sense that `versions.json` and `{PLUGIN_INSTANCE_ID}_versions.json` to reside in Docusaurus root, as it is configuration, but placing copies of docs (which can be huge) upon every version tagging in root it not acceptable. I might want to have them in a separate repo.

This is solvable with symlinks, but that's just fragile and doesn't always 100% work.

### API design

Implementation probably should adjust this `getVersionDocsDirPath` function:

https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/versions/files.ts#L32

#### Default unconfigured behaviour

Keep it as it is now, create versioned content in Docusaurus root.

#### Configurable for all versions

The user should have an setting `versionedDocsPath`.

```
// docusaurus.config.js
presets: [
[
'classic',
({
docs: {
// ...
path: '../my-docs-outside',
versionedDocsPath: '../my-vers-outside'
},
],
],
```

Running `docusaurus docs:version v2` should produce the tree below.
`versions.json` is in Docusaurus root, the versioned copy is under `../my-vers-outside`
```
/my-project
/docusaurus-website
/docusaurus.config.js

//*** new file: ***
/versions.json

/docs-outside
/main.md

//*** new files: ***
/my-vers-outside
/versioned_docs
/version-v2
/main.md
/versioned_sidebars
/version-v2-sidebars.json
```

#### Even more configurable for each version separately

Config type `VersionConfig` should have an additional (optional) property. It should be named `path` to be consistent with other `path`s that set the directories' location, but `VersionConfig.path` is already in use for URL path.
Ideally that current `path` should be named `routePath` and `path` to be used for directory path, but it's a breaking change, so maybe it can be called `versionedDocsPath` to be clear it overrides the default `versionedDocsPath`.

Running the tagging script will still output files in directory configured under `docs.versionedDocsPath`.
Then the user can manually move the files and set `versionedDocsPath` for specific versions separately.

```
// docusaurus.config.js
presets: [
[
'classic',
({
docs: {
path: '../my-docs-outside',
versionedDocsPath: '../my-vers-outside',
versions: {
current: {
// for current version, `versionedDocsPath` is ignored because it's actually `path` from above
},
'v2': {
versionedDocsPath: '../version2',
// ^^^ optional path for a specific version
},
},
},
],
],
```

#### Multi intstance configuration

Project structure:
```
/my-project
/docusaurus-website
/docusaurus.config.js
/docs-outside
/main.md
/other-section-docs <<=== a versioned section of the site
/v-doc.md
```

`docusaurus.config.js`:
```
...
presets: [
[
'classic',
({
docs: {
path: '../docs-outside',
},
],

],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'my-instance-id',
path: '../other-section-docs',
versionedDocsPath: '../my-versions',
},
],
],
```

After running `docusaurus docs:version:my-instance-id v2`, file tree:
```
/my-project
/docusaurus-website
/docusaurus.config.js

/my-instance-id_versions.json

/docs-outside
/main.md
/other-section-docs
/v-doc.md

/my-versions
/my-instance-id_versioned_docs
/version-v2
/v-doc.md
/my-instance-id_versioned_sidebars
/version-v2-sidebars.json
```

To customize `v2` directory the user should move files manually.
Say we make more versions `v3` and `v4`: `docusaurus docs:version:my-instance-id v3 && docusaurus docs:version:my-instance-id v4`.
After tagging, manually moving files around and configuring the versions, result may look like this:

`docusaurus.config.js`:
```
...
presets: [
[
'classic',
({
docs: {
path: '../docs-outside',
},
],

],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'my-instance-1',
path: '../other-section-docs',
versionedDocsPath: '../my-versions',
versions: {
// v2 stays in place
'v3': {
versionedDocsPath: '../v34-dir
},
'v4': {
versionedDocsPath: '../v34-dir
}
}
},
],
],
```

```
/my-project
/docusaurus-website
/docusaurus.config.js
/my-instance-1_versions.json

/docs-outside
/main.md
/other-section-docs
/v-doc.md

/my-versions
/my-instance-1_versioned_docs
/version-v2
/v-doc.md
/my-instance-1_versioned_sidebars
/version-v2-sidebars.json
/v34-dir
/my-instance-1_versioned_docs
/version-v3
/v-doc.md
/version-v4
/v-doc.md
/my-instance-1_versioned_sidebars
/version-v3-sidebars.json
/version-v4-sidebars.json
```

### Have you tried building it?

_No response_

### Self-service

- [X] I'd be willing to contribute this feature to Docusaurus myself.

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。