fix(v2): improve dx sidebar config, ability to have no sidebars file (#4775)

* Improve sidebar config

* Edit message

* fix some little issues in the way undefined/false sidebars are handled

* remove old error message as it has been moved to a better place

Co-authored-by: Nam Hoang Le <nam.hoang.le@mgm-tp.com>
Co-authored-by: slorber <lorber.sebastien@gmail.com>

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

@@ -24,7 +24,6 @@ import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 import {LoadContext} from '@docusaurus/types';
 import {getPluginI18nPath, normalizeUrl, posixPath} from '@docusaurus/utils';
 import {difference} from 'lodash';
-import chalk from 'chalk';
 
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir: string, pluginId: string): string {
@@ -183,14 +182,24 @@ function getVersionMetadataPaths({
     versionName,
   });
 
-  const sidebarFilePath = isCurrentVersion
-    ? path.resolve(context.siteDir, options.sidebarPath)
-    : path.join(
+  function getSidebarFilePath() {
+    if (isCurrentVersion) {
+      return options.sidebarPath
+        ? path.resolve(context.siteDir, options.sidebarPath)
+        : options.sidebarPath;
+    } else {
+      return path.join(
         getVersionedSidebarsDirPath(context.siteDir, options.id),
         `version-${versionName}-sidebars.json`,
       );
+    }
+  }
 
-  return {contentPath, contentPathLocalized, sidebarFilePath};
+  return {
+    contentPath,
+    contentPathLocalized,
+    sidebarFilePath: getSidebarFilePath(),
+  };
 }
 
 function getVersionEditUrls({
@@ -330,6 +339,7 @@ function checkVersionMetadataPaths({
 }) {
   const {versionName, contentPath, sidebarFilePath} = versionMetadata;
   const {siteDir} = context;
+  const isCurrentVersion = versionName === CURRENT_VERSION_NAME;
 
   if (!fs.existsSync(contentPath)) {
     throw new Error(
@@ -340,13 +350,23 @@ function checkVersionMetadataPaths({
     );
   }
 
+  // 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
-  if (!fs.existsSync(sidebarFilePath)) {
-    console.log(
-      chalk.yellow(
-        `The sidebar file of docs version [${versionName}] does not exist. It is optional, but should rather be provided at ${sidebarFilePath}`,
-      ),
-    );
+  // See https://github.com/facebook/docusaurus/pull/4775
+  if (
+    isCurrentVersion &&
+    typeof sidebarFilePath === 'string' &&
+    !fs.existsSync(sidebarFilePath)
+  ) {
+    throw new Error(`The path to the sidebar file does not exist at [${path.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`);
   }
 }