facebook / facebook/docusaurus
Output directory of versioning - `{PLUGIN_INSTANCE_ID}_versioned-docs` should be configurable
- 主要言語
- 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 はまだ評価されていません。