@docusaurus/plugin-content-docs 3.0.0-alpha.0 → 3.0.0-rc.0

package/lib/cli.js

@@ -21,7 +21,7 @@ async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, vers
     // Note: we don't need the sidebars file to be normalized: it's ok to let
     // plugin option changes to impact older, versioned sidebars
     // We don't validate here, assuming the user has already built the version
-    const sidebars = await (0, sidebars_1.loadSidebarsFileUnsafe)(sidebarPath);
+    const sidebars = await (0, sidebars_1.loadSidebarsFile)(sidebarPath);
     // Do not create a useless versioned sidebars file if sidebars file is empty
     // or sidebars are disabled/false)
     const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;

package/lib/docs.d.ts

@@ -18,10 +18,9 @@ export declare function processDocMetadata(args: {
     options: MetadataOptions;
     env: DocEnv;
 }): Promise<DocMetadataBase>;
-export declare function addDocNavigation({ docs, sidebarsUtils, sidebarFilePath, }: {
+export declare function addDocNavigation({ docs, sidebarsUtils, }: {
     docs: DocMetadataBase[];
     sidebarsUtils: SidebarsUtils;
-    sidebarFilePath: string;
 }): LoadedVersion['docs'];
 /**
  * The "main doc" is the "version entry point"
@@ -40,10 +39,8 @@ export declare const isCategoryIndex: CategoryIndexMatcher;
  *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
 export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): Parameters<CategoryIndexMatcher>[0];
-export declare function getDocIds(doc: DocMetadataBase): [string, string];
 export declare function createDocsByIdIndex<Doc extends {
     id: string;
-    unversionedId: string;
 }>(docs: Doc[]): {
     [docId: string]: Doc;
 };

package/lib/docs.js

@@ -6,15 +6,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDocsByIdIndex = exports.getDocIds = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+exports.createDocsByIdIndex = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const lastUpdate_1 = require("./lastUpdate");
 const slug_1 = tslib_1.__importDefault(require("./slug"));
-const constants_1 = require("./constants");
 const numberPrefix_1 = require("./numberPrefix");
 const frontMatter_1 = require("./frontMatter");
 const utils_2 = require("./sidebars/utils");
@@ -90,12 +90,6 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
     // prefix or front matter
     const sidebarPosition = frontMatter.sidebar_position ?? numberPrefix;
     // TODO legacy retrocompatibility
-    // The same doc in 2 distinct version could keep the same id,
-    // we just need to namespace the data by version
-    const versionIdPrefix = versionMetadata.versionName === constants_1.CURRENT_VERSION_NAME
-        ? undefined
-        : `version-${versionMetadata.versionName}`;
-    // TODO legacy retrocompatibility
     // I think it's bad to affect the front matter id with the dirname?
     function computeDirNameIdPrefix() {
         if (sourceDirName === '.') {
@@ -106,12 +100,7 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
             ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, options.numberPrefixParser)
             : sourceDirName;
     }
-    const unversionedId = [computeDirNameIdPrefix(), baseID]
-        .filter(Boolean)
-        .join('/');
-    // TODO is versioning the id very useful in practice?
-    // legacy versioned id, requires a breaking change to modify this
-    const id = [versionIdPrefix, unversionedId].filter(Boolean).join('/');
+    const id = [computeDirNameIdPrefix(), baseID].filter(Boolean).join('/');
     const docSlug = (0, slug_1.default)({
         baseID,
         source,
@@ -168,7 +157,6 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
     // Adding properties to object after instantiation will cause hidden
     // class transitions.
     return {
-        unversionedId,
         id,
         title,
         description,
@@ -202,15 +190,13 @@ exports.processDocMetadata = processDocMetadata;
 function getUnlistedIds(docs) {
     return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
 }
-function addDocNavigation({ docs, sidebarsUtils, sidebarFilePath, }) {
+function addDocNavigation({ docs, sidebarsUtils, }) {
     const docsById = createDocsByIdIndex(docs);
     const unlistedIds = getUnlistedIds(docs);
-    sidebarsUtils.checkSidebarsDocIds(docs.flatMap(getDocIds), sidebarFilePath);
     // Add sidebar/next/previous to the docs
     function addNavData(doc) {
         const navigation = sidebarsUtils.getDocNavigation({
-            unversionedId: doc.unversionedId,
-            versionedId: doc.id,
+            docId: doc.id,
             displayedSidebar: doc.frontMatter.displayed_sidebar,
             unlistedIds,
         });
@@ -258,12 +244,11 @@ function getMainDocId({ docs, sidebarsUtils, }) {
             return versionHomeDoc;
         }
         else if (firstDocIdOfFirstSidebar) {
-            return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar ||
-                doc.unversionedId === firstDocIdOfFirstSidebar);
+            return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar);
         }
         return docs[0];
     }
-    return getMainDoc().unversionedId;
+    return getMainDoc().id;
 }
 exports.getMainDocId = getMainDocId;
 // By convention, Docusaurus considers some docs are "indexes":
@@ -298,22 +283,8 @@ function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
     };
 }
 exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
-// Return both doc ids
-// TODO legacy retro-compatibility due to old versioned sidebars using
-// versioned doc ids ("id" should be removed & "versionedId" should be renamed
-// to "id")
-function getDocIds(doc) {
-    return [doc.unversionedId, doc.id];
-}
-exports.getDocIds = getDocIds;
-// Docs are indexed by both versioned and unversioned ids at the same time
-// TODO legacy retro-compatibility due to old versioned sidebars using
-// versioned doc ids ("id" should be removed & "versionedId" should be renamed
-// to "id")
+// Docs are indexed by their id
 function createDocsByIdIndex(docs) {
-    return Object.fromEntries(docs.flatMap((doc) => [
-        [doc.unversionedId, doc],
-        [doc.id, doc],
-    ]));
+    return lodash_1.default.keyBy(docs, (d) => d.id);
 }
 exports.createDocsByIdIndex = createDocsByIdIndex;

package/lib/globalData.js

@@ -12,7 +12,7 @@ const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const docs_1 = require("./docs");
 function toGlobalDataDoc(doc) {
     return {
-        id: doc.unversionedId,
+        id: doc.id,
         path: doc.permalink,
         // optimize global data size: do not add unlisted: false/undefined
         ...(doc.unlisted && { unlisted: doc.unlisted }),
@@ -37,7 +37,7 @@ function toGlobalSidebars(sidebars, version) {
             link: {
                 path: firstLink.type === 'generated-index'
                     ? firstLink.permalink
-                    : version.docs.find((doc) => doc.id === firstLink.id || doc.unversionedId === firstLink.id).permalink,
+                    : version.docs.find((doc) => doc.id === firstLink.id).permalink,
                 label: firstLink.label,
             },
         };
@@ -53,7 +53,7 @@ function toGlobalDataVersion(version) {
         docs: version.docs
             .map(toGlobalDataDoc)
             .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
-        draftIds: version.drafts.map((doc) => doc.unversionedId),
+        draftIds: version.drafts.map((doc) => doc.id),
         sidebars: toGlobalSidebars(version.sidebars, version),
     };
 }

package/lib/index.js

@@ -103,12 +103,22 @@ async function pluginContentDocs(context, options) {
                     categoryLabelSlugger: (0, utils_1.createSlugger)(),
                 });
                 const sidebarsUtils = (0, utils_2.createSidebarsUtils)(sidebars);
+                const docsById = (0, docs_1.createDocsByIdIndex)(docs);
+                const allDocIds = Object.keys(docsById);
+                sidebarsUtils.checkLegacyVersionedSidebarNames({
+                    sidebarFilePath: versionMetadata.sidebarFilePath,
+                    versionMetadata,
+                });
+                sidebarsUtils.checkSidebarsDocIds({
+                    allDocIds,
+                    sidebarFilePath: versionMetadata.sidebarFilePath,
+                    versionMetadata,
+                });
                 return {
                     ...versionMetadata,
                     docs: (0, docs_1.addDocNavigation)({
                         docs,
                         sidebarsUtils,
-                        sidebarFilePath: versionMetadata.sidebarFilePath,
                     }),
                     drafts,
                     sidebars,

package/lib/props.d.ts

@@ -9,7 +9,7 @@ import type { SidebarItemDoc } from './sidebars/types';
 import type { PropSidebars, PropVersionMetadata, PropTagDocList, PropTagsListPage, PropSidebarItemLink, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
 export declare function toSidebarDocItemLinkProp({ item, doc, }: {
     item: SidebarItemDoc;
-    doc: Pick<DocMetadata, 'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter' | 'unversionedId'>;
+    doc: Pick<DocMetadata, 'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter'>;
 }): PropSidebarItemLink;
 export declare function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars;
 export declare function toVersionMetadataProp(pluginId: string, loadedVersion: LoadedVersion): PropVersionMetadata;

package/lib/props.js

@@ -11,14 +11,14 @@ const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const docs_1 = require("./docs");
 function toSidebarDocItemLinkProp({ item, doc, }) {
-    const { title, permalink, frontMatter: { sidebar_label: sidebarLabel, sidebar_custom_props: customProps, }, unlisted, unversionedId, } = doc;
+    const { id, title, permalink, frontMatter: { sidebar_label: sidebarLabel, sidebar_custom_props: customProps, }, unlisted, } = doc;
     return {
         type: 'link',
         label: sidebarLabel ?? item.label ?? title,
         href: permalink,
         className: item.className,
         customProps: item.customProps ?? customProps,
-        docId: unversionedId,
+        docId: id,
         unlisted,
     };
 }
@@ -95,9 +95,9 @@ Available document ids are:
 exports.toSidebarsProp = toSidebarsProp;
 function toVersionDocsProp(loadedVersion) {
     return Object.fromEntries(loadedVersion.docs.map((doc) => [
-        doc.unversionedId,
+        doc.id,
         {
-            id: doc.unversionedId,
+            id: doc.id,
             title: doc.title,
             description: doc.description,
             sidebar: doc.sidebar,

package/lib/sidebars/generator.js

@@ -91,7 +91,7 @@ Available doc IDs:
      */
     function generateSidebar(fsModel) {
         function createDocItem(id, fullPath, fileName) {
-            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className }, } = getDoc(id);
+            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className, sidebar_custom_props: customProps, }, } = getDoc(id);
             return {
                 type: 'doc',
                 id,
@@ -101,6 +101,7 @@ Available doc IDs:
                 // sidebar
                 ...(label !== undefined && { label }),
                 ...(className !== undefined && { className }),
+                ...(customProps !== undefined && { customProps }),
             };
         }
         function createCategoryItem(dir, fullPath, folderName) {

package/lib/sidebars/index.d.ts

@@ -9,5 +9,5 @@ import type { SidebarsConfig, Sidebars, SidebarProcessorParams } from './types';
 export declare const DefaultSidebars: SidebarsConfig;
 export declare const DisabledSidebars: SidebarsConfig;
 export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];
-export declare function loadSidebarsFileUnsafe(sidebarFilePath: string | false | undefined): Promise<SidebarsConfig>;
+export declare function loadSidebarsFile(sidebarFilePath: string | false | undefined): Promise<SidebarsConfig>;
 export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/index.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadSidebars = exports.loadSidebarsFileUnsafe = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
+exports.loadSidebars = exports.loadSidebarsFile = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
@@ -15,7 +15,6 @@ const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const js_yaml_1 = tslib_1.__importDefault(require("js-yaml"));
 const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
-const import_fresh_1 = tslib_1.__importDefault(require("import-fresh"));
 const validation_1 = require("./validation");
 const normalization_1 = require("./normalization");
 const processor_1 = require("./processor");
@@ -72,9 +71,16 @@ async function loadSidebarsFileUnsafe(sidebarFilePath) {
         return exports.DisabledSidebars;
     }
     // We don't want sidebars to be cached because of hot reloading.
-    return (0, import_fresh_1.default)(sidebarFilePath);
+    const module = await (0, utils_1.loadFreshModule)(sidebarFilePath);
+    // TODO unsafe, need to refactor and improve validation
+    return module;
 }
-exports.loadSidebarsFileUnsafe = loadSidebarsFileUnsafe;
+async function loadSidebarsFile(sidebarFilePath) {
+    const sidebars = await loadSidebarsFileUnsafe(sidebarFilePath);
+    // TODO unsafe, need to refactor and improve validation
+    return sidebars;
+}
+exports.loadSidebarsFile = loadSidebarsFile;
 async function loadSidebars(sidebarFilePath, options) {
     try {
         const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);

package/lib/sidebars/postProcessor.js

@@ -10,7 +10,6 @@ exports.postProcessSidebars = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
-const docs_1 = require("../docs");
 function normalizeCategoryLink(category, params) {
     if (category.link?.type === 'doc' && params.draftIds.has(category.link.id)) {
         return undefined;
@@ -73,7 +72,7 @@ function postProcessSidebarItem(item, params) {
     return item;
 }
 function postProcessSidebars(sidebars, params) {
-    const draftIds = new Set(params.drafts.flatMap(docs_1.getDocIds));
+    const draftIds = new Set(params.drafts.map((d) => d.id));
     return lodash_1.default.mapValues(sidebars, (sidebar) => sidebar
         .map((item) => postProcessSidebarItem(item, { ...params, draftIds }))
         .filter((v) => Boolean(v)));

package/lib/sidebars/processor.js

@@ -16,7 +16,6 @@ const docs_1 = require("../docs");
 function toSidebarItemsGeneratorDoc(doc) {
     return lodash_1.default.pick(doc, [
         'id',
-        'unversionedId',
         'title',
         'frontMatter',
         'source',

package/lib/sidebars/types.d.ts

@@ -146,7 +146,7 @@ export type CategoryMetadataFile = {
         [key: string]: unknown;
     };
 };
-export type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'unversionedId' | 'title' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
+export type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'title' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
 export type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
 export type SidebarItemsGeneratorArgs = {
     /** The sidebar item with type "autogenerated" to be transformed. */

package/lib/sidebars/utils.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig, SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
-import type { DocMetadataBase, PropNavigationLink } from '@docusaurus/plugin-content-docs';
+import type { DocMetadataBase, PropNavigationLink, VersionMetadata } from '@docusaurus/plugin-content-docs';
 export declare function isCategoriesShorthand(item: SidebarItemConfig): item is SidebarCategoriesShorthand;
 export declare function transformSidebarItems(sidebar: Sidebar, updateFn: (item: SidebarItem) => SidebarItem): Sidebar;
 export declare function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[];
@@ -30,8 +30,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;
@@ -51,7 +50,15 @@ export type SidebarsUtils = {
         permalink: string;
         label: string;
     } | 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 declare function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;
 export declare function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink;

package/lib/sidebars/utils.js

@@ -110,16 +110,10 @@ function createSidebarsUtils(sidebars) {
             next: undefined,
         };
     }
-    function getDocNavigation({ unversionedId, versionedId, displayedSidebar, unlistedIds, }) {
-        // TODO legacy id retro-compatibility!
-        let docId = unversionedId;
-        let sidebarName = displayedSidebar === undefined
+    function getDocNavigation({ docId, displayedSidebar, unlistedIds, }) {
+        const sidebarName = displayedSidebar === undefined
             ? getSidebarNameByDocId(docId)
             : displayedSidebar;
-        if (sidebarName === undefined) {
-            docId = versionedId;
-            sidebarName = getSidebarNameByDocId(docId);
-        }
         if (!sidebarName) {
             return emptySidebarNavigation();
         }
@@ -186,16 +180,73 @@ function createSidebarsUtils(sidebars) {
             next: navigationItems[currentItemIndex + 1],
         };
     }
-    function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
+    // TODO remove in Docusaurus v4
+    function getLegacyVersionedPrefix(versionMetadata) {
+        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, }) {
+        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 "${(0, utils_1.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, }) {
+        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 "${(0, utils_1.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, }) {
         const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
-        const invalidSidebarDocIds = lodash_1.default.difference(allSidebarDocIds, validDocIds);
-        if (invalidSidebarDocIds.length > 0) {
+        const invalidDocIds = lodash_1.default.difference(allSidebarDocIds, allDocIds);
+        if (invalidDocIds.length > 0) {
+            handleLegacyVersionedDocIds({
+                invalidDocIds,
+                sidebarFilePath,
+                versionMetadata,
+            });
             throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
 These sidebar document ids do not exist:
-- ${invalidSidebarDocIds.sort().join('\n- ')}
+- ${invalidDocIds.sort().join('\n- ')}
 
 Available document ids are:
-- ${lodash_1.default.uniq(validDocIds).sort().join('\n- ')}`);
+- ${lodash_1.default.uniq(allDocIds).sort().join('\n- ')}
+`);
         }
     }
     function getFirstLink(sidebar) {
@@ -237,6 +288,7 @@ Available document ids are:
         getDocNavigation,
         getCategoryGeneratedIndexList,
         getCategoryGeneratedIndexNavigation,
+        checkLegacyVersionedSidebarNames,
         checkSidebarsDocIds,
         getFirstLink: (id) => getFirstLink(sidebars[id]),
     };

package/lib/translations.js

@@ -20,16 +20,6 @@ function getVersionFileName(versionName) {
     // but it's for consistency with site/versioned_docs
     return `version-${versionName}`;
 }
-// TODO legacy, the sidebar name is like "version-2.0.0-alpha.66/docs"
-// input: "version-2.0.0-alpha.66/docs"
-// output: "docs"
-function getNormalizedSidebarName({ versionName, sidebarName, }) {
-    if (versionName === constants_1.CURRENT_VERSION_NAME || !sidebarName.includes('/')) {
-        return sidebarName;
-    }
-    const [, ...rest] = sidebarName.split('/');
-    return rest.join('/');
-}
 function getSidebarTranslationFileContent(sidebar, sidebarName) {
     const categories = (0, utils_2.collectSidebarCategories)(sidebar);
     const categoryContent = Object.fromEntries(categories.flatMap((category) => {
@@ -127,21 +117,12 @@ function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
     });
 }
 function getSidebarsTranslations(version) {
-    return (0, utils_1.mergeTranslations)(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
-        const normalizedSidebarName = getNormalizedSidebarName({
-            sidebarName,
-            versionName: version.versionName,
-        });
-        return getSidebarTranslationFileContent(sidebar, normalizedSidebarName);
-    }));
+    return (0, utils_1.mergeTranslations)(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => getSidebarTranslationFileContent(sidebar, sidebarName)));
 }
 function translateSidebars(version, sidebarsTranslations) {
     return lodash_1.default.mapValues(version.sidebars, (sidebar, sidebarName) => translateSidebar({
         sidebar,
-        sidebarName: getNormalizedSidebarName({
-            sidebarName,
-            versionName: version.versionName,
-        }),
+        sidebarName,
         sidebarsTranslations,
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-rc.0",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,22 +35,21 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.0.0-alpha.0",
-    "@docusaurus/logger": "3.0.0-alpha.0",
-    "@docusaurus/mdx-loader": "3.0.0-alpha.0",
-    "@docusaurus/module-type-aliases": "3.0.0-alpha.0",
-    "@docusaurus/types": "3.0.0-alpha.0",
-    "@docusaurus/utils": "3.0.0-alpha.0",
-    "@docusaurus/utils-validation": "3.0.0-alpha.0",
-    "@types/react-router-config": "^5.0.6",
+    "@docusaurus/core": "3.0.0-rc.0",
+    "@docusaurus/logger": "3.0.0-rc.0",
+    "@docusaurus/mdx-loader": "3.0.0-rc.0",
+    "@docusaurus/module-type-aliases": "3.0.0-rc.0",
+    "@docusaurus/types": "3.0.0-rc.0",
+    "@docusaurus/utils": "3.0.0-rc.0",
+    "@docusaurus/utils-validation": "3.0.0-rc.0",
+    "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
-    "fs-extra": "^11.1.0",
-    "import-fresh": "^3.3.0",
+    "fs-extra": "^11.1.1",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
-    "tslib": "^2.5.0",
+    "tslib": "^2.6.0",
     "utility-types": "^3.10.0",
-    "webpack": "^5.76.0"
+    "webpack": "^5.88.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.5",
@@ -64,7 +63,7 @@
     "react-dom": "^18.0.0"
   },
   "engines": {
-    "node": ">=16.14"
+    "node": ">=18.0"
   },
-  "gitHead": "7327f7ff880ed97ad7855744e59c9c55d467a950"
+  "gitHead": "e66dfe04d2972edce66f431908470c61340f8ffc"
 }

package/src/cli.ts

@@ -17,7 +17,7 @@ import {
   readVersionsFile,
 } from './versions/files';
 import {validateVersionName} from './versions/validation';
-import {loadSidebarsFileUnsafe} from './sidebars';
+import {loadSidebarsFile} from './sidebars';
 import {CURRENT_VERSION_NAME} from './constants';
 import type {PluginOptions} from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
@@ -37,7 +37,7 @@ async function createVersionedSidebarFile({
   // Note: we don't need the sidebars file to be normalized: it's ok to let
   // plugin option changes to impact older, versioned sidebars
   // We don't validate here, assuming the user has already built the version
-  const sidebars = await loadSidebarsFileUnsafe(sidebarPath);
+  const sidebars = await loadSidebarsFile(sidebarPath);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty
   // or sidebars are disabled/false)

package/src/docs.ts

@@ -7,6 +7,7 @@
 
 import path from 'path';
 import fs from 'fs-extra';
+import _ from 'lodash';
 import logger from '@docusaurus/logger';
 import {
   aliasedSitePath,
@@ -24,7 +25,6 @@ import {
 
 import {getFileLastUpdate} from './lastUpdate';
 import getSlug from './slug';
-import {CURRENT_VERSION_NAME} from './constants';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './frontMatter';
 import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
@@ -188,14 +188,6 @@ async function doProcessDocMetadata({
   const sidebarPosition: number | undefined =
     frontMatter.sidebar_position ?? numberPrefix;
 
-  // TODO legacy retrocompatibility
-  // The same doc in 2 distinct version could keep the same id,
-  // we just need to namespace the data by version
-  const versionIdPrefix =
-    versionMetadata.versionName === CURRENT_VERSION_NAME
-      ? undefined
-      : `version-${versionMetadata.versionName}`;
-
   // TODO legacy retrocompatibility
   // I think it's bad to affect the front matter id with the dirname?
   function computeDirNameIdPrefix() {
@@ -208,13 +200,7 @@ async function doProcessDocMetadata({
       : sourceDirName;
   }
 
-  const unversionedId = [computeDirNameIdPrefix(), baseID]
-    .filter(Boolean)
-    .join('/');
-
-  // TODO is versioning the id very useful in practice?
-  // legacy versioned id, requires a breaking change to modify this
-  const id = [versionIdPrefix, unversionedId].filter(Boolean).join('/');
+  const id = [computeDirNameIdPrefix(), baseID].filter(Boolean).join('/');
 
   const docSlug = getSlug({
     baseID,
@@ -281,7 +267,6 @@ async function doProcessDocMetadata({
   // Adding properties to object after instantiation will cause hidden
   // class transitions.
   return {
-    unversionedId,
     id,
     title,
     description,
@@ -332,22 +317,17 @@ function getUnlistedIds(docs: DocMetadataBase[]): Set<string> {
 export function addDocNavigation({
   docs,
   sidebarsUtils,
-  sidebarFilePath,
 }: {
   docs: DocMetadataBase[];
   sidebarsUtils: SidebarsUtils;
-  sidebarFilePath: string;
 }): LoadedVersion['docs'] {
   const docsById = createDocsByIdIndex(docs);
   const unlistedIds = getUnlistedIds(docs);
 
-  sidebarsUtils.checkSidebarsDocIds(docs.flatMap(getDocIds), sidebarFilePath);
-
   // Add sidebar/next/previous to the docs
   function addNavData(doc: DocMetadataBase): DocMetadata {
     const navigation = sidebarsUtils.getDocNavigation({
-      unversionedId: doc.unversionedId,
-      versionedId: doc.id,
+      docId: doc.id,
       displayedSidebar: doc.frontMatter.displayed_sidebar,
       unlistedIds,
     });
@@ -412,16 +392,12 @@ export function getMainDocId({
     if (versionHomeDoc) {
       return versionHomeDoc;
     } else if (firstDocIdOfFirstSidebar) {
-      return docs.find(
-        (doc) =>
-          doc.id === firstDocIdOfFirstSidebar ||
-          doc.unversionedId === firstDocIdOfFirstSidebar,
-      )!;
+      return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar)!;
     }
     return docs[0]!;
   }
 
-  return getMainDoc().unversionedId;
+  return getMainDoc().id;
 }
 
 // By convention, Docusaurus considers some docs are "indexes":
@@ -465,25 +441,9 @@ export function toCategoryIndexMatcherParam({
   };
 }
 
-// Return both doc ids
-// TODO legacy retro-compatibility due to old versioned sidebars using
-// versioned doc ids ("id" should be removed & "versionedId" should be renamed
-// to "id")
-export function getDocIds(doc: DocMetadataBase): [string, string] {
-  return [doc.unversionedId, doc.id];
-}
-
-// Docs are indexed by both versioned and unversioned ids at the same time
-// TODO legacy retro-compatibility due to old versioned sidebars using
-// versioned doc ids ("id" should be removed & "versionedId" should be renamed
-// to "id")
-export function createDocsByIdIndex<
-  Doc extends {id: string; unversionedId: string},
->(docs: Doc[]): {[docId: string]: Doc} {
-  return Object.fromEntries(
-    docs.flatMap((doc) => [
-      [doc.unversionedId, doc],
-      [doc.id, doc],
-    ]),
-  );
+// Docs are indexed by their id
+export function createDocsByIdIndex<Doc extends {id: string}>(
+  docs: Doc[],
+): {[docId: string]: Doc} {
+  return _.keyBy(docs, (d) => d.id);
 }

package/src/globalData.ts

@@ -21,7 +21,7 @@ import type {Sidebars} from './sidebars/types';
 
 function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
-    id: doc.unversionedId,
+    id: doc.id,
     path: doc.permalink,
 
     // optimize global data size: do not add unlisted: false/undefined
@@ -56,10 +56,7 @@ function toGlobalSidebars(
         path:
           firstLink.type === 'generated-index'
             ? firstLink.permalink
-            : version.docs.find(
-                (doc) =>
-                  doc.id === firstLink.id || doc.unversionedId === firstLink.id,
-              )!.permalink,
+            : version.docs.find((doc) => doc.id === firstLink.id)!.permalink,
         label: firstLink.label,
       },
     };
@@ -76,7 +73,7 @@ export function toGlobalDataVersion(version: FullVersion): GlobalVersion {
     docs: version.docs
       .map(toGlobalDataDoc)
       .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
-    draftIds: version.drafts.map((doc) => doc.unversionedId),
+    draftIds: version.drafts.map((doc) => doc.id),
     sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }

package/src/index.ts

@@ -26,6 +26,7 @@ import {
   processDocMetadata,
   addDocNavigation,
   type DocEnv,
+  createDocsByIdIndex,
 } from './docs';
 import {readVersionsMetadata, toFullVersion} from './versions';
 import {cliDocsVersionCommand} from './cli';
@@ -179,12 +180,24 @@ export default async function pluginContentDocs(
 
         const sidebarsUtils = createSidebarsUtils(sidebars);
 
+        const docsById = createDocsByIdIndex(docs);
+        const allDocIds = Object.keys(docsById);
+
+        sidebarsUtils.checkLegacyVersionedSidebarNames({
+          sidebarFilePath: versionMetadata.sidebarFilePath as string,
+          versionMetadata,
+        });
+        sidebarsUtils.checkSidebarsDocIds({
+          allDocIds,
+          sidebarFilePath: versionMetadata.sidebarFilePath as string,
+          versionMetadata,
+        });
+
         return {
           ...versionMetadata,
           docs: addDocNavigation({
             docs,
             sidebarsUtils,
-            sidebarFilePath: versionMetadata.sidebarFilePath as string,
           }),
           drafts,
           sidebars,

package/src/plugin-content-docs.d.ts

@@ -414,17 +414,11 @@ declare module '@docusaurus/plugin-content-docs' {
   };
 
   export type DocMetadataBase = LastUpdateData & {
-    // TODO
     /**
-     * Legacy versioned ID. Will be refactored in the future to be unversioned.
+     * The document id.
+     * Multiple documents can have the same id, when in different versions.
      */
     id: string;
-    // TODO
-    /**
-     * Unversioned ID. Should be preferred everywhere over `id` until the latter
-     * is refactored.
-     */
-    unversionedId: string;
     /** The name of the version this doc belongs to. */
     version: string;
     /**

package/src/props.ts

@@ -35,10 +35,11 @@ export function toSidebarDocItemLinkProp({
   item: SidebarItemDoc;
   doc: Pick<
     DocMetadata,
-    'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter' | 'unversionedId'
+    'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter'
   >;
 }): PropSidebarItemLink {
   const {
+    id,
     title,
     permalink,
     frontMatter: {
@@ -46,7 +47,6 @@ export function toSidebarDocItemLinkProp({
       sidebar_custom_props: customProps,
     },
     unlisted,
-    unversionedId,
   } = doc;
   return {
     type: 'link',
@@ -54,7 +54,7 @@ export function toSidebarDocItemLinkProp({
     href: permalink,
     className: item.className,
     customProps: item.customProps ?? customProps,
-    docId: unversionedId,
+    docId: id,
     unlisted,
   };
 }
@@ -151,9 +151,9 @@ Available document ids are:
 function toVersionDocsProp(loadedVersion: LoadedVersion): PropVersionDocs {
   return Object.fromEntries(
     loadedVersion.docs.map((doc) => [
-      doc.unversionedId,
+      doc.id,
       {
-        id: doc.unversionedId,
+        id: doc.id,
         title: doc.title,
         description: doc.description,
         sidebar: doc.sidebar,

package/src/sidebars/generator.ts

@@ -138,7 +138,11 @@ Available doc IDs:
     ): WithPosition<SidebarItemDoc> {
       const {
         sidebarPosition: position,
-        frontMatter: {sidebar_label: label, sidebar_class_name: className},
+        frontMatter: {
+          sidebar_label: label,
+          sidebar_class_name: className,
+          sidebar_custom_props: customProps,
+        },
       } = getDoc(id);
       return {
         type: 'doc',
@@ -149,6 +153,7 @@ Available doc IDs:
         // sidebar
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
+        ...(customProps !== undefined && {customProps}),
       };
     }
     function createCategoryItem(

package/src/sidebars/index.ts

@@ -9,10 +9,9 @@ import fs from 'fs-extra';
 import path from 'path';
 import _ from 'lodash';
 import logger from '@docusaurus/logger';
-import {Globby} from '@docusaurus/utils';
+import {loadFreshModule, Globby} from '@docusaurus/utils';
 import Yaml from 'js-yaml';
 import combinePromises from 'combine-promises';
-import importFresh from 'import-fresh';
 import {validateSidebars, validateCategoryMetadataFile} from './validation';
 import {normalizeSidebars} from './normalization';
 import {processSidebars} from './processor';
@@ -68,7 +67,7 @@ async function readCategoriesMetadata(contentPath: string) {
   );
 }
 
-export async function loadSidebarsFileUnsafe(
+async function loadSidebarsFileUnsafe(
   sidebarFilePath: string | false | undefined,
 ): Promise<SidebarsConfig> {
   // false => no sidebars
@@ -89,7 +88,19 @@ export async function loadSidebarsFileUnsafe(
   }
 
   // We don't want sidebars to be cached because of hot reloading.
-  return importFresh(sidebarFilePath);
+  const module = await loadFreshModule(sidebarFilePath);
+
+  // TODO unsafe, need to refactor and improve validation
+  return module as SidebarsConfig;
+}
+
+export async function loadSidebarsFile(
+  sidebarFilePath: string | false | undefined,
+): Promise<SidebarsConfig> {
+  const sidebars = await loadSidebarsFileUnsafe(sidebarFilePath);
+
+  // TODO unsafe, need to refactor and improve validation
+  return sidebars as SidebarsConfig;
 }
 
 export async function loadSidebars(

package/src/sidebars/postProcessor.ts

@@ -7,7 +7,6 @@
 
 import _ from 'lodash';
 import {normalizeUrl} from '@docusaurus/utils';
-import {getDocIds} from '../docs';
 import type {
   SidebarItem,
   Sidebars,
@@ -102,7 +101,7 @@ export function postProcessSidebars(
   sidebars: ProcessedSidebars,
   params: SidebarProcessorParams,
 ): Sidebars {
-  const draftIds = new Set(params.drafts.flatMap(getDocIds));
+  const draftIds = new Set(params.drafts.map((d) => d.id));
 
   return _.mapValues(sidebars, (sidebar) =>
     sidebar

package/src/sidebars/processor.ts

@@ -33,7 +33,6 @@ function toSidebarItemsGeneratorDoc(
 ): SidebarItemsGeneratorDoc {
   return _.pick(doc, [
     'id',
-    'unversionedId',
     'title',
     'frontMatter',
     'source',

package/src/sidebars/types.ts

@@ -235,7 +235,6 @@ export type CategoryMetadataFile = {
 export type SidebarItemsGeneratorDoc = Pick<
   DocMetadataBase,
   | 'id'
-  | 'unversionedId'
   | 'title'
   | 'frontMatter'
   | 'source'

package/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]!),
   };

package/src/translations.ts

@@ -40,23 +40,6 @@ function getVersionFileName(versionName: string): string {
   return `version-${versionName}`;
 }
 
-// TODO legacy, the sidebar name is like "version-2.0.0-alpha.66/docs"
-// input: "version-2.0.0-alpha.66/docs"
-// output: "docs"
-function getNormalizedSidebarName({
-  versionName,
-  sidebarName,
-}: {
-  versionName: string;
-  sidebarName: string;
-}): string {
-  if (versionName === CURRENT_VERSION_NAME || !sidebarName.includes('/')) {
-    return sidebarName;
-  }
-  const [, ...rest] = sidebarName.split('/');
-  return rest.join('/');
-}
-
 function getSidebarTranslationFileContent(
   sidebar: Sidebar,
   sidebarName: string,
@@ -199,13 +182,9 @@ function getSidebarsTranslations(
   version: LoadedVersion,
 ): TranslationFileContent {
   return mergeTranslations(
-    Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
-      const normalizedSidebarName = getNormalizedSidebarName({
-        sidebarName,
-        versionName: version.versionName,
-      });
-      return getSidebarTranslationFileContent(sidebar, normalizedSidebarName);
-    }),
+    Object.entries(version.sidebars).map(([sidebarName, sidebar]) =>
+      getSidebarTranslationFileContent(sidebar, sidebarName),
+    ),
   );
 }
 function translateSidebars(
@@ -215,10 +194,7 @@ function translateSidebars(
   return _.mapValues(version.sidebars, (sidebar, sidebarName) =>
     translateSidebar({
       sidebar,
-      sidebarName: getNormalizedSidebarName({
-        sidebarName,
-        versionName: version.versionName,
-      }),
+      sidebarName,
       sidebarsTranslations,
     }),
   );