@docusaurus/plugin-content-docs 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/lib/versions.js

@@ -6,23 +6,19 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDocsDirPaths = exports.readVersionsMetadata = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = void 0;
+exports.getDocsDirPaths = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = 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 constants_1 = require("./constants");
-const constants_2 = require("@docusaurus/core/lib/constants");
 const utils_1 = require("@docusaurus/utils");
-const lodash_1 = require("lodash");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const sidebars_1 = require("./sidebars");
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir, pluginId) {
-    if (pluginId === constants_2.DEFAULT_PLUGIN_ID) {
-        return fileOrDir;
-    }
-    else {
-        return `${pluginId}_${fileOrDir}`;
-    }
+    return pluginId === utils_1.DEFAULT_PLUGIN_ID
+        ? fileOrDir
+        : `${pluginId}_${fileOrDir}`;
 }
 function getVersionedDocsDirPath(siteDir, pluginId) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId));
@@ -51,39 +47,37 @@ function ensureValidVersionArray(versionArray) {
     }
     versionArray.forEach(ensureValidVersionString);
 }
-// TODO not easy to make async due to many deps
-function readVersionsFile(siteDir, pluginId) {
+async function readVersionsFile(siteDir, pluginId) {
     const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-    if (fs_extra_1.default.existsSync(versionsFilePath)) {
-        const content = JSON.parse(fs_extra_1.default.readFileSync(versionsFilePath, 'utf8'));
+    if (await fs_extra_1.default.pathExists(versionsFilePath)) {
+        const content = JSON.parse(await fs_extra_1.default.readFile(versionsFilePath, 'utf8'));
         ensureValidVersionArray(content);
         return content;
     }
-    else {
-        return null;
-    }
+    return null;
 }
-// TODO not easy to make async due to many deps
-function readVersionNames(siteDir, options) {
-    const versionFileContent = readVersionsFile(siteDir, options.id);
+exports.readVersionsFile = readVersionsFile;
+async function readVersionNames(siteDir, options) {
+    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.`);
+        throw new Error(`Docs: using "disableVersioning: ${options.disableVersioning}" option on a non-versioned site does not make sense.`);
     }
-    const versions = options.disableVersioning ? [] : versionFileContent !== null && versionFileContent !== void 0 ? versionFileContent : [];
-    // We add the current version at the beginning, unless
-    // - user don't want to
-    // - it's been explicitly added to versions.json
+    const versions = options.disableVersioning ? [] : versionFileContent ?? [];
+    // We add the current version at the beginning, unless:
+    // - user don't want to; or
+    // - it's already been explicitly added to versions.json
     if (options.includeCurrentVersion &&
         !versions.includes(constants_1.CURRENT_VERSION_NAME)) {
         versions.unshift(constants_1.CURRENT_VERSION_NAME);
     }
     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}".`);
+        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}".`);
     }
     return versions;
 }
+exports.readVersionNames = readVersionNames;
 function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
-    return utils_1.getPluginI18nPath({
+    return (0, utils_1.getPluginI18nPath)({
         siteDir,
         locale,
         pluginName: 'docusaurus-plugin-content-docs',
@@ -97,27 +91,23 @@ function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
 }
 function getVersionMetadataPaths({ versionName, context, options, }) {
     const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    const contentPath = isCurrentVersion
-        ? path_1.default.resolve(context.siteDir, options.path)
-        : path_1.default.join(getVersionedDocsDirPath(context.siteDir, options.id), `version-${versionName}`);
     const contentPathLocalized = getDocsDirPathLocalized({
         siteDir: context.siteDir,
         locale: context.i18n.currentLocale,
         pluginId: options.id,
         versionName,
     });
-    function getSidebarFilePath() {
-        if (isCurrentVersion) {
-            return sidebars_1.resolveSidebarPathOption(context.siteDir, options.sidebarPath);
-        }
-        else {
-            return path_1.default.join(getVersionedSidebarsDirPath(context.siteDir, options.id), `version-${versionName}-sidebars.json`);
-        }
+    if (isCurrentVersion) {
+        return {
+            contentPath: path_1.default.resolve(context.siteDir, options.path),
+            contentPathLocalized,
+            sidebarFilePath: (0, sidebars_1.resolveSidebarPathOption)(context.siteDir, options.sidebarPath),
+        };
     }
     return {
-        contentPath,
+        contentPath: path_1.default.join(getVersionedDocsDirPath(context.siteDir, options.id), `version-${versionName}`),
         contentPathLocalized,
-        sidebarFilePath: getSidebarFilePath(),
+        sidebarFilePath: path_1.default.join(getVersionedSidebarsDirPath(context.siteDir, options.id), `version-${versionName}-sidebars.json`),
     };
 }
 function getVersionEditUrls({ contentPath, contentPathLocalized, context: { siteDir, i18n }, options: { id, path: currentVersionPath, editUrl, editCurrentVersion }, }) {
@@ -138,10 +128,10 @@ function getVersionEditUrls({ contentPath, contentPathLocalized, context: { site
             pluginId: id,
         })
         : contentPathLocalized;
-    const versionPathSegment = utils_1.posixPath(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPath)));
-    const versionPathSegmentLocalized = utils_1.posixPath(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPathLocalized)));
-    const versionEditUrl = utils_1.normalizeUrl([editUrl, versionPathSegment]);
-    const versionEditUrlLocalized = utils_1.normalizeUrl([
+    const versionPathSegment = (0, utils_1.posixPath)(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPath)));
+    const versionPathSegmentLocalized = (0, utils_1.posixPath)(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPathLocalized)));
+    const versionEditUrl = (0, utils_1.normalizeUrl)([editUrl, versionPathSegment]);
+    const versionEditUrlLocalized = (0, utils_1.normalizeUrl)([
         editUrl,
         versionPathSegmentLocalized,
     ]);
@@ -153,33 +143,44 @@ function getVersionEditUrls({ contentPath, contentPathLocalized, context: { site
 function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }) {
     // Current version: good, no banner
     if (versionName === lastVersionName) {
-        return 'none';
+        return null;
     }
     // Upcoming versions: unreleased banner
-    else if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
+    if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
         return 'unreleased';
     }
     // Older versions: display unmaintained banner
-    else {
-        return 'unmaintained';
-    }
+    return 'unmaintained';
 }
+exports.getDefaultVersionBanner = getDefaultVersionBanner;
 function getVersionBanner({ versionName, versionNames, lastVersionName, options, }) {
-    var _a;
-    const versionOptionBanner = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.banner;
-    return (versionOptionBanner !== null && versionOptionBanner !== void 0 ? versionOptionBanner : getDefaultVersionBanner({
+    const versionBannerOption = options.versions[versionName]?.banner;
+    if (versionBannerOption) {
+        return versionBannerOption === 'none' ? null : versionBannerOption;
+    }
+    return getDefaultVersionBanner({
         versionName,
         versionNames,
         lastVersionName,
-    }));
+    });
+}
+exports.getVersionBanner = getVersionBanner;
+function getVersionBadge({ versionName, versionNames, options, }) {
+    const versionBadgeOption = options.versions[versionName]?.badge;
+    // If site is not versioned or only one version is included
+    // we don't show the version badge by default
+    // See https://github.com/facebook/docusaurus/issues/3362
+    const versionBadgeDefault = versionNames.length !== 1;
+    return versionBadgeOption ?? versionBadgeDefault;
+}
+exports.getVersionBadge = getVersionBadge;
+function getVersionClassName({ versionName, options, }) {
+    const versionClassNameOption = options.versions[versionName]?.className;
+    const versionClassNameDefault = `docs-version-${versionName}`;
+    return versionClassNameOption ?? versionClassNameDefault;
 }
 function createVersionMetadata({ versionName, versionNames, lastVersionName, context, options, }) {
-    var _a, _b, _c;
-    const { sidebarFilePath, contentPath, contentPathLocalized, } = getVersionMetadataPaths({
-        versionName,
-        context,
-        options,
-    });
+    const { sidebarFilePath, contentPath, contentPathLocalized } = getVersionMetadataPaths({ versionName, context, options });
     const isLast = versionName === lastVersionName;
     // retro-compatible values
     const defaultVersionLabel = versionName === constants_1.CURRENT_VERSION_NAME ? 'Next' : versionName;
@@ -190,10 +191,10 @@ function createVersionMetadata({ versionName, versionNames, lastVersionName, con
         return versionName === constants_1.CURRENT_VERSION_NAME ? 'next' : versionName;
     }
     const defaultVersionPathPart = getDefaultVersionPathPart();
-    const versionOptions = (_a = options.versions[versionName]) !== null && _a !== void 0 ? _a : {};
-    const versionLabel = (_b = versionOptions.label) !== null && _b !== void 0 ? _b : defaultVersionLabel;
-    const versionPathPart = (_c = versionOptions.path) !== null && _c !== void 0 ? _c : defaultVersionPathPart;
-    const versionPath = utils_1.normalizeUrl([
+    const versionOptions = options.versions[versionName] ?? {};
+    const versionLabel = versionOptions.label ?? defaultVersionLabel;
+    const versionPathPart = versionOptions.path ?? defaultVersionPathPart;
+    const versionPath = (0, utils_1.normalizeUrl)([
         context.baseUrl,
         options.routeBasePath,
         versionPathPart,
@@ -206,18 +207,24 @@ function createVersionMetadata({ versionName, versionNames, lastVersionName, con
     });
     // Because /docs/:route` should always be after `/docs/versionName/:route`.
     const routePriority = versionPathPart === '' ? -1 : undefined;
+    // the path that will be used to refer the docs tags
+    // example below will be using /docs/tags
+    const tagsPath = (0, utils_1.normalizeUrl)([versionPath, options.tagsBasePath]);
     return {
         versionName,
         versionLabel,
         versionPath,
-        versionEditUrl: versionEditUrls === null || versionEditUrls === void 0 ? void 0 : versionEditUrls.versionEditUrl,
-        versionEditUrlLocalized: versionEditUrls === null || versionEditUrls === void 0 ? void 0 : versionEditUrls.versionEditUrlLocalized,
+        tagsPath,
+        versionEditUrl: versionEditUrls?.versionEditUrl,
+        versionEditUrlLocalized: versionEditUrls?.versionEditUrlLocalized,
         versionBanner: getVersionBanner({
             versionName,
             versionNames,
             lastVersionName,
             options,
         }),
+        versionBadge: getVersionBadge({ versionName, versionNames, options }),
+        versionClassName: getVersionClassName({ versionName, options }),
         isLast,
         routePriority,
         sidebarFilePath,
@@ -225,25 +232,26 @@ function createVersionMetadata({ versionName, versionNames, lastVersionName, con
         contentPathLocalized,
     };
 }
-function checkVersionMetadataPaths({ versionMetadata, context, }) {
+async function checkVersionMetadataPaths({ versionMetadata, context, }) {
     const { versionName, contentPath, sidebarFilePath } = versionMetadata;
     const { siteDir } = context;
     const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    if (!fs_extra_1.default.existsSync(contentPath)) {
+    if (!(await fs_extra_1.default.pathExists(contentPath))) {
         throw new Error(`The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path_1.default.relative(siteDir, contentPath)}.`);
     }
-    // If the current version defines a path to a sidebar file  that does not exist, we throw!
-    // Note: for versioned sidebars, the file may not exist (as we prefer to not create it rather than to create an empty file)
+    // If the current version defines a path to a sidebar file that does not
+    // exist, we throw! Note: for versioned sidebars, the file may not exist (as
+    // we prefer to not create it rather than to create an empty file)
     // See https://github.com/facebook/docusaurus/issues/3366
     // See https://github.com/facebook/docusaurus/pull/4775
     if (isCurrentVersion &&
         typeof sidebarFilePath === 'string' &&
-        !fs_extra_1.default.existsSync(sidebarFilePath)) {
+        !(await fs_extra_1.default.pathExists(sidebarFilePath))) {
         throw new Error(`The path to the sidebar file does not exist at "${path_1.default.relative(siteDir, sidebarFilePath)}".
 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`);
     }
 }
 // TODO for retrocompatibility with existing behavior
@@ -253,17 +261,15 @@ function getDefaultLastVersionName(versionNames) {
     if (versionNames.length === 1) {
         return versionNames[0];
     }
-    else {
-        return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
-    }
+    return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
 }
 function checkVersionsOptions(availableVersionNames, options) {
     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}`);
+        throw new Error(`Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
     }
-    const unknownVersionConfigNames = lodash_1.difference(Object.keys(options.versions), availableVersionNames);
+    const unknownVersionConfigNames = lodash_1.default.difference(Object.keys(options.versions), availableVersionNames);
     if (unknownVersionConfigNames.length > 0) {
         throw new Error(`Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(',')}) found. ${availableVersionNamesMsg}`);
     }
@@ -271,7 +277,7 @@ function checkVersionsOptions(availableVersionNames, options) {
         if (options.onlyIncludeVersions.length === 0) {
             throw new Error(`Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`);
         }
-        const unknownOnlyIncludeVersionNames = lodash_1.difference(options.onlyIncludeVersions, availableVersionNames);
+        const unknownOnlyIncludeVersionNames = lodash_1.default.difference(options.onlyIncludeVersions, availableVersionNames);
         if (unknownOnlyIncludeVersionNames.length > 0) {
             throw new Error(`Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(',')}) found. ${availableVersionNamesMsg}`);
         }
@@ -281,24 +287,23 @@ function checkVersionsOptions(availableVersionNames, options) {
         }
     }
 }
-// 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
+/**
+ * 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, options) {
     if (options.onlyIncludeVersions) {
         return versionNamesUnfiltered.filter((name) => (options.onlyIncludeVersions || []).includes(name));
     }
-    else {
-        return versionNamesUnfiltered;
-    }
+    return versionNamesUnfiltered;
 }
-// TODO make this async (requires plugin init to be async)
-function readVersionsMetadata({ context, options, }) {
-    var _a;
-    const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
+exports.filterVersions = filterVersions;
+async function readVersionsMetadata({ context, options, }) {
+    const versionNamesUnfiltered = await readVersionNames(context.siteDir, options);
     checkVersionsOptions(versionNamesUnfiltered, options);
     const versionNames = filterVersions(versionNamesUnfiltered, options);
-    const lastVersionName = (_a = options.lastVersion) !== null && _a !== void 0 ? _a : getDefaultLastVersionName(versionNames);
+    const lastVersionName = options.lastVersion ?? getDefaultLastVersionName(versionNames);
     const versionsMetadata = versionNames.map((versionName) => createVersionMetadata({
         versionName,
         versionNames,
@@ -306,7 +311,7 @@ function readVersionsMetadata({ context, options, }) {
         context,
         options,
     }));
-    versionsMetadata.forEach((versionMetadata) => checkVersionMetadataPaths({ versionMetadata, context }));
+    await Promise.all(versionsMetadata.map((versionMetadata) => checkVersionMetadataPaths({ versionMetadata, context })));
     return versionsMetadata;
 }
 exports.readVersionsMetadata = readVersionsMetadata;

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "2.0.0-beta.15a2b59f9",
+  "version": "2.0.0-beta.17",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
+  "exports": {
+    "./client": "./lib/client/index.js",
+    "./server": "./lib/server-export.js",
+    ".": "./lib/index.js"
+  },
   "types": "src/plugin-content-docs.d.ts",
   "scripts": {
     "build": "tsc",
@@ -17,41 +22,39 @@
     "directory": "packages/docusaurus-plugin-content-docs"
   },
   "license": "MIT",
-  "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.15a2b59f9",
-    "@types/js-yaml": "^4.0.0",
-    "@types/picomatch": "^2.2.1",
-    "commander": "^5.1.0",
-    "picomatch": "^2.1.1"
-  },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/mdx-loader": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/types": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/utils": "2.0.0-beta.15a2b59f9",
-    "@docusaurus/utils-validation": "2.0.0-beta.15a2b59f9",
-    "chalk": "^4.1.1",
+    "@docusaurus/core": "2.0.0-beta.17",
+    "@docusaurus/logger": "2.0.0-beta.17",
+    "@docusaurus/mdx-loader": "2.0.0-beta.17",
+    "@docusaurus/utils": "2.0.0-beta.17",
+    "@docusaurus/utils-validation": "2.0.0-beta.17",
     "combine-promises": "^1.1.0",
-    "escape-string-regexp": "^4.0.0",
-    "execa": "^5.0.0",
-    "fs-extra": "^10.0.0",
-    "globby": "^11.0.2",
-    "import-fresh": "^3.2.2",
-    "js-yaml": "^4.0.0",
-    "loader-utils": "^1.2.3",
-    "lodash": "^4.17.20",
+    "fs-extra": "^10.0.1",
+    "import-fresh": "^3.3.0",
+    "js-yaml": "^4.1.0",
+    "lodash": "^4.17.21",
     "remark-admonitions": "^1.2.1",
-    "shelljs": "^0.8.4",
-    "tslib": "^2.2.0",
+    "tslib": "^2.3.1",
     "utility-types": "^3.10.0",
-    "webpack": "^5.40.0"
+    "webpack": "^5.69.1"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.17",
+    "@docusaurus/types": "2.0.0-beta.17",
+    "@types/js-yaml": "^4.0.5",
+    "@types/picomatch": "^2.3.0",
+    "commander": "^5.1.0",
+    "escape-string-regexp": "^4.0.0",
+    "picomatch": "^2.3.1",
+    "shelljs": "^0.8.5",
+    "utility-types": "^3.10.0"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "34881586224092fb9b5b2f455a46e19b3eee7f08"
+  "gitHead": "0032c0b0480083227af2e1b4da2d3ee6ce992403"
 }

package/src/categoryGeneratedIndex.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {CategoryGeneratedIndexMetadata, DocMetadataBase} from './types';
+import type {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
+import {type SidebarsUtils, toNavigationLink} from './sidebars/utils';
+import {createDocsByIdIndex} from './docs';
+
+function getCategoryGeneratedIndexMetadata({
+  category,
+  sidebarsUtils,
+  docsById,
+}: {
+  category: SidebarItemCategoryWithGeneratedIndex;
+  sidebarsUtils: SidebarsUtils;
+  docsById: Record<string, DocMetadataBase>;
+}): CategoryGeneratedIndexMetadata {
+  const {sidebarName, previous, next} =
+    sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+  if (!sidebarName) {
+    throw new Error('unexpected');
+  }
+
+  return {
+    title: category.link.title ?? category.label,
+    description: category.link.description,
+    image: category.link.image,
+    keywords: category.link.keywords,
+    slug: category.link.slug,
+    permalink: category.link.permalink,
+    sidebar: sidebarName,
+    previous: toNavigationLink(previous, docsById),
+    next: toNavigationLink(next, docsById),
+  };
+}
+
+export function getCategoryGeneratedIndexMetadataList({
+  docs,
+  sidebarsUtils,
+}: {
+  sidebarsUtils: SidebarsUtils;
+  docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[] {
+  const docsById = createDocsByIdIndex(docs);
+
+  const categoryGeneratedIndexItems =
+    sidebarsUtils.getCategoryGeneratedIndexList();
+  return categoryGeneratedIndexItems.map((category) =>
+    getCategoryGeneratedIndexMetadata({
+      category,
+      sidebarsUtils,
+      docsById,
+    }),
+  );
+}

package/src/cli.ts

@@ -12,15 +12,15 @@ import {
 } from './versions';
 import fs from 'fs-extra';
 import path from 'path';
-import {
+import type {
   PathOptions,
-  UnprocessedSidebarItem,
-  UnprocessedSidebars,
-} from './types';
-import {loadSidebars, resolveSidebarPathOption} from './sidebars';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+  SidebarOptions,
+} from '@docusaurus/plugin-content-docs';
+import {loadSidebarsFileUnsafe, resolveSidebarPathOption} from './sidebars';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
 
-function createVersionedSidebarFile({
+async function createVersionedSidebarFile({
   siteDir,
   pluginId,
   sidebarPath,
@@ -32,63 +32,37 @@ function createVersionedSidebarFile({
   version: string;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadSidebars(sidebarPath);
+  // 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);
 
-  // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
-  const shouldCreateVersionedSidebarFile =
-    Object.keys(loadedSidebars).length > 0;
+  // 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;
 
   if (shouldCreateVersionedSidebarFile) {
-    // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
-    // TODO try to get rid of it
-    // Transform id in original sidebar to versioned id.
-    const normalizeItem = (
-      item: UnprocessedSidebarItem,
-    ): UnprocessedSidebarItem => {
-      switch (item.type) {
-        case 'category':
-          return {...item, items: item.items.map(normalizeItem)};
-        case 'ref':
-        case 'doc':
-          return {
-            type: item.type,
-            id: `version-${version}/${item.id}`,
-          };
-        default:
-          return item;
-      }
-    };
-
-    const versionedSidebar: UnprocessedSidebars = Object.entries(
-      loadedSidebars,
-    ).reduce((acc: UnprocessedSidebars, [sidebarId, sidebarItems]) => {
-      const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-      acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-      return acc;
-    }, {});
-
     const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
     const newSidebarFile = path.join(
       versionedSidebarsDir,
       `version-${version}-sidebars.json`,
     );
-    fs.ensureDirSync(path.dirname(newSidebarFile));
-    fs.writeFileSync(
+    await fs.ensureDir(path.dirname(newSidebarFile));
+    await fs.writeFile(
       newSidebarFile,
-      `${JSON.stringify(versionedSidebar, null, 2)}\n`,
+      `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
     );
   }
 }
 
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
-export function cliDocsVersionCommand(
+export async function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,
   pluginId: string,
-  options: PathOptions,
-): void {
+  options: PathOptions & SidebarOptions,
+): Promise<void> {
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
   const pluginIdLogPrefix =
@@ -130,8 +104,8 @@ export function cliDocsVersionCommand(
   // Load existing versions.
   let versions = [];
   const versionsJSONFile = getVersionsFilePath(siteDir, pluginId);
-  if (fs.existsSync(versionsJSONFile)) {
-    versions = JSON.parse(fs.readFileSync(versionsJSONFile, 'utf8'));
+  if (await fs.pathExists(versionsJSONFile)) {
+    versions = JSON.parse(await fs.readFile(versionsJSONFile, 'utf8'));
   }
 
   // Check if version already exists.
@@ -146,15 +120,18 @@ export function cliDocsVersionCommand(
   // Copy docs files.
   const docsDir = path.join(siteDir, docsPath);
 
-  if (fs.existsSync(docsDir) && fs.readdirSync(docsDir).length > 0) {
+  if (
+    (await fs.pathExists(docsDir)) &&
+    (await fs.readdir(docsDir)).length > 0
+  ) {
     const versionedDir = getVersionedDocsDirPath(siteDir, pluginId);
     const newVersionDir = path.join(versionedDir, `version-${version}`);
-    fs.copySync(docsDir, newVersionDir);
+    await fs.copy(docsDir, newVersionDir);
   } else {
     throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
   }
 
-  createVersionedSidebarFile({
+  await createVersionedSidebarFile({
     siteDir,
     pluginId,
     version,
@@ -163,8 +140,11 @@ export function cliDocsVersionCommand(
 
   // Update versions.json file.
   versions.unshift(version);
-  fs.ensureDirSync(path.dirname(versionsJSONFile));
-  fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+  await fs.ensureDir(path.dirname(versionsJSONFile));
+  await fs.writeFile(
+    versionsJSONFile,
+    `${JSON.stringify(versions, null, 2)}\n`,
+  );
 
-  console.log(`${pluginIdLogPrefix}: version ${version} created!`);
+  logger.success`name=${pluginIdLogPrefix}: version name=${version} created!`;
 }