chore(plugin-docs): remove legacy versioned prefix on doc ids and sidebar names in versioned sidebars (#9310)

packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts

@@ -23,6 +23,7 @@ import type {
 import type {
   DocMetadataBase,
   PropNavigationLink,
+  VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
 
 export function isCategoriesShorthand(
@@ -136,8 +137,7 @@ export type SidebarsUtils = {
   getFirstDocIdOfFirstSidebar: () => string | undefined;
   getSidebarNameByDocId: (docId: string) => string | undefined;
   getDocNavigation: (params: {
-    unversionedId: string;
-    versionedId: string;
+    docId: string;
     displayedSidebar: string | null | undefined;
     unlistedIds: Set<string>;
   }) => SidebarNavigation;
@@ -163,7 +163,22 @@ export type SidebarsUtils = {
       }
     | undefined;
 
-  checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
+  checkLegacyVersionedSidebarNames: ({
+    versionMetadata,
+  }: {
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) => void;
+
+  checkSidebarsDocIds: ({
+    allDocIds,
+    sidebarFilePath,
+    versionMetadata,
+  }: {
+    allDocIds: string[];
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) => void;
 };
 
 export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
@@ -194,26 +209,18 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
   }
 
   function getDocNavigation({
-    unversionedId,
-    versionedId,
+    docId,
     displayedSidebar,
     unlistedIds,
   }: {
-    unversionedId: string;
-    versionedId: string;
+    docId: string;
     displayedSidebar: string | null | undefined;
     unlistedIds: Set<string>;
   }): SidebarNavigation {
-    // TODO legacy id retro-compatibility!
-    let docId = unversionedId;
-    let sidebarName =
+    const sidebarName =
       displayedSidebar === undefined
         ? getSidebarNameByDocId(docId)
         : displayedSidebar;
-    if (sidebarName === undefined) {
-      docId = versionedId;
-      sidebarName = getSidebarNameByDocId(docId);
-    }
 
     if (!sidebarName) {
       return emptySidebarNavigation();
@@ -303,19 +310,115 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     };
   }
 
-  function checkSidebarsDocIds(validDocIds: string[], sidebarFilePath: string) {
+  // TODO remove in Docusaurus v4
+  function getLegacyVersionedPrefix(versionMetadata: VersionMetadata): string {
+    return `version-${versionMetadata.versionName}/`;
+  }
+
+  // In early v2, sidebar names used to be versioned
+  // example: "version-2.0.0-alpha.66/my-sidebar-name"
+  // In v3 it's not the case anymore and we throw an error to explain
+  // TODO remove in Docusaurus v4
+  function checkLegacyVersionedSidebarNames({
+    versionMetadata,
+    sidebarFilePath,
+  }: {
+    versionMetadata: VersionMetadata;
+    sidebarFilePath: string;
+  }): void {
+    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+    const legacySidebarNames = Object.keys(sidebars).filter((sidebarName) =>
+      sidebarName.startsWith(illegalPrefix),
+    );
+    if (legacySidebarNames.length > 0) {
+      throw new Error(
+        `Invalid sidebar file at "${toMessageRelativeFilePath(
+          sidebarFilePath,
+        )}".
+These legacy versioned sidebar names are not supported anymore in Docusaurus v3:
+- ${legacySidebarNames.sort().join('\n- ')}
+
+The sidebar names you should now use are:
+- ${legacySidebarNames
+          .sort()
+          .map((legacyName) => legacyName.split('/').splice(1).join('/'))
+          .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`,
+      );
+    }
+  }
+
+  // throw a better error message for Docusaurus v3 breaking change
+  // TODO this can be removed in Docusaurus v4
+  function handleLegacyVersionedDocIds({
+    invalidDocIds,
+    sidebarFilePath,
+    versionMetadata,
+  }: {
+    invalidDocIds: string[];
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) {
+    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+
+    // In older v2.0 alpha/betas, versioned docs had a legacy versioned prefix
+    // Example: "version-1.4/my-doc-id"
+    //
+    const legacyVersionedDocIds = invalidDocIds.filter((docId) =>
+      docId.startsWith(illegalPrefix),
+    );
+    if (legacyVersionedDocIds.length > 0) {
+      throw new Error(
+        `Invalid sidebar file at "${toMessageRelativeFilePath(
+          sidebarFilePath,
+        )}".
+These legacy versioned document ids are not supported anymore in Docusaurus v3:
+- ${legacyVersionedDocIds.sort().join('\n- ')}
+
+The document ids you should now use are:
+- ${legacyVersionedDocIds
+          .sort()
+          .map((legacyId) => legacyId.split('/').splice(1).join('/'))
+          .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`,
+      );
+    }
+  }
+
+  function checkSidebarsDocIds({
+    allDocIds,
+    sidebarFilePath,
+    versionMetadata,
+  }: {
+    allDocIds: string[];
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) {
     const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
-    const invalidSidebarDocIds = _.difference(allSidebarDocIds, validDocIds);
-    if (invalidSidebarDocIds.length > 0) {
+    const invalidDocIds = _.difference(allSidebarDocIds, allDocIds);
+
+    if (invalidDocIds.length > 0) {
+      handleLegacyVersionedDocIds({
+        invalidDocIds,
+        sidebarFilePath,
+        versionMetadata,
+      });
       throw new Error(
         `Invalid sidebar file at "${toMessageRelativeFilePath(
           sidebarFilePath,
         )}".
 These sidebar document ids do not exist:
-- ${invalidSidebarDocIds.sort().join('\n- ')}
+- ${invalidDocIds.sort().join('\n- ')}
 
 Available document ids are:
-- ${_.uniq(validDocIds).sort().join('\n- ')}`,
+- ${_.uniq(allDocIds).sort().join('\n- ')}
+`,
       );
     }
   }
@@ -369,6 +472,7 @@ Available document ids are:
     getDocNavigation,
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
+    checkLegacyVersionedSidebarNames,
     checkSidebarsDocIds,
     getFirstLink: (id) => getFirstLink(sidebars[id]!),
   };