refactor(content-docs): make readVersionsMetadata async (#6277)

* refactor(content-docs): make readVersionsMetadata async

* fix tests

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

@@ -166,7 +166,7 @@ describe('simple site', () => {
       ...DEFAULT_OPTIONS,
       ...loadSiteOptions.options,
     };
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       context,
       options,
     });
@@ -523,7 +523,7 @@ describe('versioned site', () => {
       ...DEFAULT_OPTIONS,
       ...loadSiteOptions.options,
     };
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       context,
       options,
     });

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

@@ -141,7 +141,7 @@ describe('sidebar', () => {
             Please set the docs \\"sidebarPath\\" field in your config file to:
             - a sidebars path that exists
             - false: to disable the sidebar
-            - undefined: for Docusaurus generates it automatically"
+            - undefined: for Docusaurus to generate it automatically"
           `);
   });
 

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

@@ -91,7 +91,7 @@ describe('simple site', () => {
   test('readVersionsMetadata simple site', async () => {
     const {defaultOptions, defaultContext, vCurrent} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: defaultOptions,
       context: defaultContext,
     });
@@ -102,7 +102,7 @@ describe('simple site', () => {
   test('readVersionsMetadata simple site with base url', async () => {
     const {defaultOptions, defaultContext, vCurrent} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: defaultOptions,
       context: {
         ...defaultContext,
@@ -122,7 +122,7 @@ describe('simple site', () => {
   test('readVersionsMetadata simple site with current version config', async () => {
     const {defaultOptions, defaultContext, vCurrent} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {
         ...defaultOptions,
         versions: {
@@ -155,20 +155,20 @@ describe('simple site', () => {
   test('readVersionsMetadata simple site with unknown lastVersion should throw', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {...defaultOptions, lastVersion: 'unknownVersionName'},
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"Docs option lastVersion=unknownVersionName is invalid. Available version names are: current"`,
+      `"Docs option lastVersion: unknownVersionName is invalid. Available version names are: current"`,
     );
   });
 
   test('readVersionsMetadata simple site with unknown version configurations should throw', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {
           ...defaultOptions,
@@ -180,7 +180,7 @@ describe('simple site', () => {
         },
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
       `"Invalid docs option \\"versions\\": unknown versions (unknownVersionName1,unknownVersionName2) found. Available version names are: current"`,
     );
   });
@@ -188,26 +188,26 @@ describe('simple site', () => {
   test('readVersionsMetadata simple site with disableVersioning while single version should throw', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {...defaultOptions, disableVersioning: true},
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"Docs: using \\"disableVersioning=true\\" option on a non-versioned site does not make sense."`,
+      `"Docs: using \\"disableVersioning: true\\" option on a non-versioned site does not make sense."`,
     );
   });
 
   test('readVersionsMetadata simple site without including current version should throw', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {...defaultOptions, includeCurrentVersion: false},
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=false\\"."`,
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: false\\"."`,
     );
   });
 });
@@ -327,7 +327,7 @@ describe('versioned site, pluginId=default', () => {
     const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
       await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: defaultOptions,
       context: defaultContext,
     });
@@ -339,7 +339,7 @@ describe('versioned site, pluginId=default', () => {
     const {defaultOptions, defaultContext, v101, v100, vwithSlugs} =
       await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {...defaultOptions, includeCurrentVersion: false},
       context: defaultContext,
     });
@@ -356,7 +356,7 @@ describe('versioned site, pluginId=default', () => {
     const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
       await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {
         ...defaultOptions,
         lastVersion: '1.0.0',
@@ -410,7 +410,7 @@ describe('versioned site, pluginId=default', () => {
     const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
       await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {
         ...defaultOptions,
         editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
@@ -454,7 +454,7 @@ describe('versioned site, pluginId=default', () => {
     const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
       await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {
         ...defaultOptions,
         editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
@@ -498,7 +498,7 @@ describe('versioned site, pluginId=default', () => {
   test('readVersionsMetadata versioned site with onlyIncludeVersions option', async () => {
     const {defaultOptions, defaultContext, v101, vwithSlugs} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {
         ...defaultOptions,
         // Order reversed on purpose: should not have any impact
@@ -513,7 +513,7 @@ describe('versioned site, pluginId=default', () => {
   test('readVersionsMetadata versioned site with disableVersioning', async () => {
     const {defaultOptions, defaultContext, vCurrent} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {...defaultOptions, disableVersioning: true},
       context: defaultContext,
     });
@@ -534,7 +534,7 @@ describe('versioned site, pluginId=default', () => {
   test('readVersionsMetadata versioned site with all versions disabled', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {
           ...defaultOptions,
@@ -543,15 +543,15 @@ describe('versioned site, pluginId=default', () => {
         },
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`,
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: true\\"."`,
     );
   });
 
   test('readVersionsMetadata versioned site with empty onlyIncludeVersions', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {
           ...defaultOptions,
@@ -559,7 +559,7 @@ describe('versioned site, pluginId=default', () => {
         },
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
       `"Invalid docs option \\"onlyIncludeVersions\\": an empty array is not allowed, at least one version is needed."`,
     );
   });
@@ -567,7 +567,7 @@ describe('versioned site, pluginId=default', () => {
   test('readVersionsMetadata versioned site with unknown versions in onlyIncludeVersions', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {
           ...defaultOptions,
@@ -575,7 +575,7 @@ describe('versioned site, pluginId=default', () => {
         },
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
       `"Invalid docs option \\"onlyIncludeVersions\\": unknown versions (unknownVersion1,unknownVersion2) found. Available version names are: current, 1.0.1, 1.0.0, withSlugs"`,
     );
   });
@@ -583,7 +583,7 @@ describe('versioned site, pluginId=default', () => {
   test('readVersionsMetadata versioned site with lastVersion not in onlyIncludeVersions', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {
           ...defaultOptions,
@@ -592,7 +592,7 @@ describe('versioned site, pluginId=default', () => {
         },
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
       `"Invalid docs option \\"lastVersion\\": if you use both the \\"onlyIncludeVersions\\" and \\"lastVersion\\" options, then \\"lastVersion\\" must be present in the provided \\"onlyIncludeVersions\\" array."`,
     );
   });
@@ -604,12 +604,12 @@ describe('versioned site, pluginId=default', () => {
       invalid: 'json',
     }));
 
-    expect(() => {
+    await expect(
       readVersionsMetadata({
         options: defaultOptions,
         context: defaultContext,
-      });
+      }),
-    }).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
       `"The versions file should contain an array of versions! Found content: {\\"invalid\\":\\"json\\"}"`,
     );
     mock.mockRestore();
@@ -682,7 +682,7 @@ describe('versioned site, pluginId=community', () => {
   test('readVersionsMetadata versioned site (community)', async () => {
     const {defaultOptions, defaultContext, vCurrent, v100} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: defaultOptions,
       context: defaultContext,
     });
@@ -693,7 +693,7 @@ describe('versioned site, pluginId=community', () => {
   test('readVersionsMetadata versioned site (community) with includeCurrentVersion=false', async () => {
     const {defaultOptions, defaultContext, v100} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {...defaultOptions, includeCurrentVersion: false},
       context: defaultContext,
     });
@@ -707,7 +707,7 @@ describe('versioned site, pluginId=community', () => {
   test('readVersionsMetadata versioned site (community) with disableVersioning', async () => {
     const {defaultOptions, defaultContext, vCurrent} = await loadSite();
 
-    const versionsMetadata = readVersionsMetadata({
+    const versionsMetadata = await readVersionsMetadata({
       options: {...defaultOptions, disableVersioning: true},
       context: defaultContext,
     });
@@ -728,7 +728,7 @@ describe('versioned site, pluginId=community', () => {
   test('readVersionsMetadata versioned site (community) with all versions disabled', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    expect(() =>
+    await expect(
       readVersionsMetadata({
         options: {
           ...defaultOptions,
@@ -737,8 +737,8 @@ describe('versioned site, pluginId=community', () => {
         },
         context: defaultContext,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion=false\\", \\"disableVersioning=true\\"."`,
+      `"It is not possible to use docs without any version. Please check the configuration of these options: \\"includeCurrentVersion: false\\", \\"disableVersioning: true\\"."`,
     );
   });
 });

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

@@ -64,7 +64,7 @@ export default async function pluginContentDocs(
 ): Promise<Plugin<LoadedContent>> {
   const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context;
 
-  const versionsMetadata = readVersionsMetadata({context, options});
+  const versionsMetadata = await readVersionsMetadata({context, options});
 
   const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
 

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

@@ -87,11 +87,13 @@ function ensureValidVersionArray(
   versionArray.forEach(ensureValidVersionString);
 }
 
-// TODO not easy to make async due to many deps
+async function readVersionsFile(
-function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
+  siteDir: string,
+  pluginId: string,
+): Promise<string[] | null> {
   const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-  if (fs.existsSync(versionsFilePath)) {
+  if (await fs.pathExists(versionsFilePath)) {
-    const content = JSON.parse(fs.readFileSync(versionsFilePath, 'utf8'));
+    const content = JSON.parse(await fs.readFile(versionsFilePath, 'utf8'));
     ensureValidVersionArray(content);
     return content;
   } else {
@@ -99,27 +101,26 @@ function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
   }
 }
 
-// TODO not easy to make async due to many deps
+async function readVersionNames(
-function readVersionNames(
   siteDir: string,
   options: Pick<
     PluginOptions,
     'id' | 'disableVersioning' | 'includeCurrentVersion'
   >,
-): string[] {
+): Promise<string[]> {
-  const versionFileContent = readVersionsFile(siteDir, options.id);
+  const versionFileContent = await readVersionsFile(siteDir, options.id);
 
   if (!versionFileContent && options.disableVersioning) {
     throw new Error(
-      `Docs: using "disableVersioning=${options.disableVersioning}" option on a non-versioned site does not make sense.`,
+      `Docs: using "disableVersioning: ${options.disableVersioning}" option on a non-versioned site does not make sense.`,
     );
   }
 
   const versions = options.disableVersioning ? [] : versionFileContent ?? [];
 
-  // We add the current version at the beginning, unless
+  // We add the current version at the beginning, unless:
-  // - user don't want to
+  // - user don't want to; or
-  // - it's been explicitly added to versions.json
+  // - it's already been explicitly added to versions.json
   if (
     options.includeCurrentVersion &&
     !versions.includes(CURRENT_VERSION_NAME)
@@ -129,7 +130,7 @@ function readVersionNames(
 
   if (versions.length === 0) {
     throw new Error(
-      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion=${options.includeCurrentVersion}", "disableVersioning=${options.disableVersioning}".`,
+      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion: ${options.includeCurrentVersion}", "disableVersioning: ${options.disableVersioning}".`,
     );
   }
 
@@ -174,13 +175,6 @@ function getVersionMetadataPaths({
 > {
   const isCurrentVersion = versionName === CURRENT_VERSION_NAME;
 
-  const contentPath = isCurrentVersion
-    ? path.resolve(context.siteDir, options.path)
-    : path.join(
-        getVersionedDocsDirPath(context.siteDir, options.id),
-        `version-${versionName}`,
-      );
-
   const contentPathLocalized = getDocsDirPathLocalized({
     siteDir: context.siteDir,
     locale: context.i18n.currentLocale,
@@ -188,21 +182,27 @@ function getVersionMetadataPaths({
     versionName,
   });
 
-  function getSidebarFilePath() {
   if (isCurrentVersion) {
-      return resolveSidebarPathOption(context.siteDir, options.sidebarPath);
+    return {
-    } else {
+      contentPath: path.resolve(context.siteDir, options.path),
-      return path.join(
+      contentPathLocalized,
-        getVersionedSidebarsDirPath(context.siteDir, options.id),
+      sidebarFilePath: resolveSidebarPathOption(
-        `version-${versionName}-sidebars.json`,
+        context.siteDir,
-      );
+        options.sidebarPath,
-    }
+      ),
+    };
   }
 
   return {
-    contentPath,
+    contentPath: path.join(
+      getVersionedDocsDirPath(context.siteDir, options.id),
+      `version-${versionName}`,
+    ),
     contentPathLocalized,
-    sidebarFilePath: getSidebarFilePath(),
+    sidebarFilePath: path.join(
+      getVersionedSidebarsDirPath(context.siteDir, options.id),
+      `version-${versionName}-sidebars.json`,
+    ),
   };
 }
 
@@ -459,7 +459,7 @@ function checkVersionMetadataPaths({
 Please set the docs "sidebarPath" field in your config file to:
 - a sidebars path that exists
 - false: to disable the sidebar
-- undefined: for Docusaurus generates it automatically`);
+- undefined: for Docusaurus to generate it automatically`);
   }
 }
 
@@ -488,7 +488,7 @@ function checkVersionsOptions(
     !availableVersionNames.includes(options.lastVersion)
   ) {
     throw new Error(
-      `Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
+      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
     );
   }
   const unknownVersionConfigNames = difference(
@@ -531,9 +531,11 @@ function checkVersionsOptions(
   }
 }
 
-// Filter versions according to provided options
+/**
-// Note: we preserve the order in which versions are provided
+ * Filter versions according to provided options.
-// the order of the onlyIncludeVersions array does not matter
+ * 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'>,
@@ -547,8 +549,7 @@ function filterVersions(
   }
 }
 
-// TODO make this async (requires plugin init to be async)
+export async function readVersionsMetadata({
-export function readVersionsMetadata({
   context,
   options,
 }: {
@@ -568,8 +569,11 @@ export function readVersionsMetadata({
     | 'editUrl'
     | 'editCurrentVersion'
   >;
-}): VersionMetadata[] {
+}): Promise<VersionMetadata[]> {
-  const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
+  const versionNamesUnfiltered = await readVersionNames(
+    context.siteDir,
+    options,
+  );
 
   checkVersionsOptions(versionNamesUnfiltered, options);