feat(v2): docs options.onlyIncludeVersions (#3373)

* docs options.onlyIncludeVersions

* adapt docsVersionDropdown if we render a single version

* fix bad error message

* fix netlify deploy when versioning is disabled

packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts

@@ -146,7 +146,7 @@ describe('simple site', () => {
         context: defaultContext,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Docs versions option provided configuration for unknown versions: unknownVersionName1,unknownVersionName2. Available version names are: current"`,
+      `"Bad docs options.versions: unknown versions found: unknownVersionName1,unknownVersionName2. Available version names are: current"`,
     );
   });
 
@@ -297,6 +297,19 @@ describe('versioned site, pluginId=default', () => {
     ]);
   });
 
+  test('readVersionsMetadata versioned site with onlyIncludeVersions option', () => {
+    const versionsMetadata = readVersionsMetadata({
+      options: {
+        ...defaultOptions,
+        // Order reversed on purpose: should not have any impact
+        onlyIncludeVersions: [vwithSlugs.versionName, v101.versionName],
+      },
+      context: defaultContext,
+    });
+
+    expect(versionsMetadata).toEqual([v101, vwithSlugs]);
+  });
+
   test('readVersionsMetadata versioned site with disableVersioning', () => {
     const versionsMetadata = readVersionsMetadata({
       options: {...defaultOptions, disableVersioning: true},
@@ -323,6 +336,49 @@ describe('versioned site, pluginId=default', () => {
     );
   });
 
+  test('readVersionsMetadata versioned site with empty onlyIncludeVersions', () => {
+    expect(() =>
+      readVersionsMetadata({
+        options: {
+          ...defaultOptions,
+          onlyIncludeVersions: [],
+        },
+        context: defaultContext,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Bad docs options.onlyIncludeVersions: an empty array is not allowed, at least one version is needed"`,
+    );
+  });
+
+  test('readVersionsMetadata versioned site with unknown versions in onlyIncludeVersions', () => {
+    expect(() =>
+      readVersionsMetadata({
+        options: {
+          ...defaultOptions,
+          onlyIncludeVersions: ['unknownVersion1', 'unknownVersion2'],
+        },
+        context: defaultContext,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Bad docs options.onlyIncludeVersions: unknown versions found: unknownVersion1,unknownVersion2. Available version names are: current, 1.0.1, 1.0.0, withSlugs"`,
+    );
+  });
+
+  test('readVersionsMetadata versioned site with lastVersion not in onlyIncludeVersions', () => {
+    expect(() =>
+      readVersionsMetadata({
+        options: {
+          ...defaultOptions,
+          lastVersion: '1.0.1',
+          onlyIncludeVersions: ['current', '1.0.0'],
+        },
+        context: defaultContext,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Bad docs options.lastVersion: if you use both the onlyIncludeVersions and lastVersion options, then lastVersion must be present in the provided onlyIncludeVersions array"`,
+    );
+  });
+
   test('readVersionsMetadata versioned site with invalid versions.json file', () => {
     const mock = jest.spyOn(JSON, 'parse').mockImplementationOnce(() => {
       return {

packages/docusaurus-plugin-content-docs/src/options.ts

@@ -68,6 +68,7 @@ export const OptionsSchema = Joi.object({
   includeCurrentVersion: Joi.bool().default(
     DEFAULT_OPTIONS.includeCurrentVersion,
   ),
+  onlyIncludeVersions: Joi.array().items(Joi.string().required()).optional(),
   disableVersioning: Joi.bool().default(DEFAULT_OPTIONS.disableVersioning),
   lastVersion: Joi.string().optional(),
   versions: VersionsOptionsSchema,

packages/docusaurus-plugin-content-docs/src/types.ts

@@ -47,6 +47,7 @@ export type VersionOptions = {
 export type VersionsOptions = {
   lastVersion?: string;
   versions: Record<string, VersionOptions>;
+  onlyIncludeVersions?: string[];
 };
 
 export type PluginOptions = MetadataOptions &

packages/docusaurus-plugin-content-docs/src/versions.ts

@@ -257,17 +257,60 @@ function checkVersionsOptions(
       `Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
     );
   }
-  const unknownVersionNames = difference(
+  const unknownVersionConfigNames = difference(
     Object.keys(options.versions),
     availableVersionNames,
   );
-  if (unknownVersionNames.length > 0) {
+  if (unknownVersionConfigNames.length > 0) {
     throw new Error(
-      `Docs versions option provided configuration for unknown versions: ${unknownVersionNames.join(
+      `Bad docs options.versions: unknown versions found: ${unknownVersionConfigNames.join(
         ',',
       )}. ${availableVersionNamesMsg}`,
     );
   }
+
+  if (options.onlyIncludeVersions) {
+    if (options.onlyIncludeVersions.length === 0) {
+      throw new Error(
+        `Bad docs options.onlyIncludeVersions: an empty array is not allowed, at least one version is needed`,
+      );
+    }
+    const unknownOnlyIncludeVersionNames = difference(
+      options.onlyIncludeVersions,
+      availableVersionNames,
+    );
+    if (unknownOnlyIncludeVersionNames.length > 0) {
+      throw new Error(
+        `Bad docs options.onlyIncludeVersions: unknown versions found: ${unknownOnlyIncludeVersionNames.join(
+          ',',
+        )}. ${availableVersionNamesMsg}`,
+      );
+    }
+    if (
+      options.lastVersion &&
+      !options.onlyIncludeVersions.includes(options.lastVersion)
+    ) {
+      throw new Error(
+        `Bad docs options.lastVersion: if you use both the onlyIncludeVersions and lastVersion options, then lastVersion must be present in the provided onlyIncludeVersions array`,
+      );
+    }
+  }
+}
+
+// Filter versions according to provided options
+// Note: we preserve the order in which versions are provided
+// the order of the onlyIncludeVersions array does not matter
+function filterVersions(
+  versionNamesUnfiltered: string[],
+  options: Pick<PluginOptions, 'onlyIncludeVersions'>,
+) {
+  if (options.onlyIncludeVersions) {
+    return versionNamesUnfiltered.filter((name) =>
+      options.onlyIncludeVersions!.includes(name),
+    );
+  } else {
+    return versionNamesUnfiltered;
+  }
 }
 
 export function readVersionsMetadata({
@@ -285,11 +328,14 @@ export function readVersionsMetadata({
     | 'disableVersioning'
     | 'lastVersion'
     | 'versions'
+    | 'onlyIncludeVersions'
   >;
 }): VersionMetadata[] {
-  const versionNames = readVersionNames(context.siteDir, options);
+  const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
 
-  checkVersionsOptions(versionNames, options);
+  checkVersionsOptions(versionNamesUnfiltered, options);
+
+  const versionNames = filterVersions(versionNamesUnfiltered, options);
 
   const lastVersionName =
     options.lastVersion ?? getDefaultLastVersionName(versionNames);