110 lines
No EOL
2.9 KiB
Markdown
110 lines
No EOL
2.9 KiB
Markdown
# Docusaurus versioning setup
|
|
|
|
Docs versioning is currently **DISABLED** but configured and ready to enable.
|
|
The configuration is found in `docusaurus.config.js` with commented-out sections.
|
|
|
|
To enable versioning, do the following:
|
|
|
|
1. Open `docusaurus.config.js`
|
|
2. Find the versioning configuration section (around line 57)
|
|
3. Uncomment the versioning configuration:
|
|
|
|
```javascript
|
|
docs: {
|
|
// ... other config
|
|
lastVersion: 'current', // Use 'current' to make ./docs the latest version
|
|
versions: {
|
|
current: {
|
|
label: 'Next (unreleased)',
|
|
path: 'next',
|
|
},
|
|
},
|
|
onlyIncludeVersions: ['current'], // Limit versions for faster builds
|
|
},
|
|
```
|
|
|
|
## Create docs versions
|
|
|
|
See the [Docusaurus docs](https://docusaurus.io/docs/versioning) for more info.
|
|
|
|
1. Use the Docusaurus CLI command to create a version.
|
|
```bash
|
|
# Create version 1.0.0 from current docs
|
|
npm run docusaurus docs:version 1.0.0
|
|
```
|
|
|
|
This command will:
|
|
- Copy the full `docs/` folder contents into `versioned_docs/version-1.0.0/`
|
|
- Create a versioned sidebar file at `versioned_sidebars/version-1.0.0-sidebars.json`
|
|
- Append the new version to `versions.json`
|
|
|
|
2. After creating a version, update the Docusaurus configuration to include multiple versions.
|
|
`lastVersion:'1.0.0'` makes the '1.0.0' release the `latest` version.
|
|
`current` is the work-in-progress docset, accessible at `/docs/next`.
|
|
To remove a version, remove it from `onlyIncludeVersions`.
|
|
|
|
```javascript
|
|
docs: {
|
|
// ... other config
|
|
lastVersion: '1.0.0', // Make 1.0.0 the latest version
|
|
versions: {
|
|
current: {
|
|
label: 'Next (unreleased)',
|
|
path: 'next',
|
|
},
|
|
'1.0.0': {
|
|
label: '1.0.0',
|
|
path: '1.0.0',
|
|
},
|
|
},
|
|
onlyIncludeVersions: ['current', '1.0.0'], // Include both versions
|
|
},
|
|
```
|
|
|
|
3. Test the deployment locally.
|
|
|
|
```bash
|
|
npm run build
|
|
npm run serve
|
|
```
|
|
|
|
4. To add subsequent versions, repeat the process, first running the CLI command then updating `docusaurus.config.js`.
|
|
|
|
```bash
|
|
# Create version 2.0.0 from current docs
|
|
npm run docusaurus docs:version 2.0.0
|
|
```
|
|
|
|
After creating a new version, update `docusaurus.config.js`.
|
|
|
|
```javascript
|
|
docs: {
|
|
lastVersion: '2.0.0', // Make 2.0.0 the latest version
|
|
versions: {
|
|
current: {
|
|
label: 'Next (unreleased)',
|
|
path: 'next',
|
|
},
|
|
'2.0.0': {
|
|
label: '2.0.0',
|
|
path: '2.0.0',
|
|
},
|
|
'1.0.0': {
|
|
label: '1.0.0',
|
|
path: '1.0.0',
|
|
},
|
|
},
|
|
onlyIncludeVersions: ['current', '2.0.0', '1.0.0'], // Include all versions
|
|
},
|
|
```
|
|
|
|
## Disable versioning
|
|
|
|
1. Remove the `versions` configuration from `docusaurus.config.js`.
|
|
2. Delete the `docs/versioned_docs/` and `docs/versioned_sidebars/` directories.
|
|
3. Delete `docs/versions.json`.
|
|
|
|
## References
|
|
|
|
- [Official Docusaurus Versioning Documentation](https://docusaurus.io/docs/versioning)
|
|
- [Docusaurus Versioning Best Practices](https://docusaurus.io/docs/versioning#recommended-practices) |