3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-13 00:57:53 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(v2): docs version configuration: lastVersion, version.{path,label} (#3357)

Browse source 
* add new docs versioning options

* Add some tests for new versioning options

* Add some docs for version configurations

* try to fix broken link detection after /docs/ root paths have been removed on deploy previews

* improve dev/deploypreview versioning configurations

* disable custom current version path, as it produces broken links

* readVersionDocs should not be order sensitive

* fix versions page according to versioning config

* fix versions page according to versioning config
This commit is contained in:
Sébastien Lorber 2020-08-28 18:37:49 +02:00 • committed by GitHub
parent 4bfc3bbbe7
commit ae877f2990
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 387 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

64
packages/docusaurus-plugin-content-docs/src/versions.ts
View file

@ -7,7 +7,12 @@
import path from 'path';
import fs from 'fs-extra';
import {PluginOptions, VersionMetadata} from './types';
import {
PluginOptions,
VersionMetadata,
VersionOptions,
VersionsOptions,
} from './types';
import {
VERSIONS_JSON_FILE,
VERSIONED_DOCS_DIR,
@ -18,6 +23,7 @@ import {
import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
import {LoadContext} from '@docusaurus/types';
import {normalizeUrl} from '@docusaurus/utils';
import {difference} from 'lodash';
// retro-compatibility: no prefix for the default plugin id
function addPluginIdPrefix(fileOrDir: string, pluginId: string): string {
@ -161,7 +167,10 @@ function createVersionMetadata({
versionName: string;
isLast: boolean;
context: Pick<LoadContext, 'siteDir' | 'baseUrl'>;
options: Pick<PluginOptions, 'id' | 'path' | 'sidebarPath' | 'routeBasePath'>;
options: Pick<
PluginOptions,
'id' | 'path' | 'sidebarPath' | 'routeBasePath' | 'versions'
>;
}): VersionMetadata {
const {sidebarFilePath, docsDirPath} = getVersionMetadataPaths({
versionName,
@ -169,16 +178,20 @@ function createVersionMetadata({
options,
});
// TODO hardcoded for retro-compatibility
// TODO Need to make this configurable
const versionLabel =
// retro-compatible values
const defaultVersionLabel =
versionName === CURRENT_VERSION_NAME ? 'Next' : versionName;
const versionPathPart = isLast
const defaultVersionPathPart = isLast
? ''
: versionName === CURRENT_VERSION_NAME
? 'next'
: versionName;
const versionOptions: VersionOptions = options.versions[versionName] ?? {};
const versionLabel = versionOptions.label ?? defaultVersionLabel;
const versionPathPart = versionOptions.path ?? defaultVersionPathPart;
const versionPath = normalizeUrl([
context.baseUrl,
options.routeBasePath,
@ -219,7 +232,7 @@ function checkVersionMetadataPaths({
// TODO for retrocompatibility with existing behavior
// We should make this configurable
// "last version" is not a very good concept nor api surface
function getLastVersionName(versionNames: string[]) {
function getDefaultLastVersionName(versionNames: string[]) {
if (versionNames.length === 1) {
return versionNames[0];
} else {
@ -229,6 +242,34 @@ function getLastVersionName(versionNames: string[]) {
}
}
function checkVersionsOptions(
availableVersionNames: string[],
options: VersionsOptions,
) {
const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(
', ',
)}`;
if (
options.lastVersion &&
!availableVersionNames.includes(options.lastVersion)
) {
throw new Error(
`Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
);
}
const unknownVersionNames = difference(
Object.keys(options.versions),
availableVersionNames,
);
if (unknownVersionNames.length > 0) {
throw new Error(
`Docs versions option provided configuration for unknown versions: ${unknownVersionNames.join(
',',
)}. ${availableVersionNamesMsg}`,
);
}
}
export function readVersionsMetadata({
context,
options,
@ -242,10 +283,17 @@ export function readVersionsMetadata({
| 'routeBasePath'
| 'includeCurrentVersion'
| 'disableVersioning'
| 'lastVersion'
| 'versions'
>;
}): VersionMetadata[] {
const versionNames = readVersionNames(context.siteDir, options);
const lastVersionName = getLastVersionName(versionNames);
checkVersionsOptions(versionNames, options);
const lastVersionName =
options.lastVersion ?? getDefaultLastVersionName(versionNames);
const versionsMetadata = versionNames.map((versionName) =>
createVersionMetadata({
versionName,