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/__tests__/__snapshots__/index.test.ts.snap

@@ -1,5 +1,27 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`sidebar site with wrong sidebar content 1`] = `
+"Bad sidebars file.
+These sidebar document ids do not exist:
+- goku,
+
+Available document ids=
+- foo/bar
+- foo/baz
+- headingAsTitle
+- hello
+- ipsum
+- lorem
+- rootAbsoluteSlug
+- rootRelativeSlug
+- rootResolvedSlug
+- rootTryToEscapeSlug
+- slugs/absoluteSlug
+- slugs/relativeSlug
+- slugs/resolvedSlug
+- slugs/tryToEscapeSlug"
+`;
+
 exports[`simple website content 1`] = `
 Object {
   "docs": Array [
@@ -790,28 +812,6 @@ Object {
 }
 `;
 
-exports[`site with wrong sidebar file 1`] = `
-"Bad sidebars file.
-These sidebar document ids do not exist:
-- goku,
-
-Available document ids=
-- foo/bar
-- foo/baz
-- headingAsTitle
-- hello
-- ipsum
-- lorem
-- rootAbsoluteSlug
-- rootRelativeSlug
-- rootResolvedSlug
-- rootTryToEscapeSlug
-- slugs/absoluteSlug
-- slugs/relativeSlug
-- slugs/resolvedSlug
-- slugs/tryToEscapeSlug"
-`;
-
 exports[`versioned website (community) content: 100 version sidebars 1`] = `
 Object {
   "version-1.0.0/community": Array [

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

@@ -35,6 +35,7 @@ import {toSidebarsProp} from '../props';
 
 import {validate} from 'webpack';
 import {DefaultSidebarItemsGenerator} from '../sidebarItemsGenerator';
+import {DisabledSidebars} from '../sidebars';
 
 function findDocById(version: LoadedVersion, unversionedId: string) {
   return version.docs.find((item) => item.unversionedId === unversionedId);
@@ -124,17 +125,84 @@ Entries created:
   };
 };
 
-test('site with wrong sidebar file', async () => {
-  const siteDir = path.join(__dirname, '__fixtures__', 'simple-site');
-  const context = await loadContext(siteDir);
-  const sidebarPath = path.join(siteDir, 'wrong-sidebars.json');
-  const plugin = pluginContentDocs(
-    context,
-    normalizePluginOptions(OptionsSchema, {
-      sidebarPath,
-    }),
-  );
-  await expect(plugin.loadContent!()).rejects.toThrowErrorMatchingSnapshot();
+describe('sidebar', () => {
+  test('site with wrong sidebar content', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'simple-site');
+    const context = await loadContext(siteDir);
+    const sidebarPath = path.join(siteDir, 'wrong-sidebars.json');
+    const plugin = pluginContentDocs(
+      context,
+      normalizePluginOptions(OptionsSchema, {
+        sidebarPath,
+      }),
+    );
+    await expect(plugin.loadContent!()).rejects.toThrowErrorMatchingSnapshot();
+  });
+
+  test('site with wrong sidebar file path', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'site-with-doc-label');
+    const context = await loadContext(siteDir);
+
+    await expect(async () => {
+      const plugin = pluginContentDocs(
+        context,
+        normalizePluginOptions(OptionsSchema, {
+          sidebarPath: 'wrong-path-sidebar.json',
+        }),
+      );
+      await plugin.loadContent!();
+    }).rejects.toThrowErrorMatchingInlineSnapshot(`
+            "The path to the sidebar file does not exist at [wrong-path-sidebar.json].
+            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"
+          `);
+  });
+
+  test('site with undefined sidebar', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'site-with-doc-label');
+    const context = await loadContext(siteDir);
+    const plugin = pluginContentDocs(
+      context,
+      normalizePluginOptions(OptionsSchema, {
+        sidebarPath: undefined,
+      }),
+    );
+    const result = await plugin.loadContent!();
+
+    expect(result.loadedVersions).toHaveLength(1);
+    expect(result.loadedVersions[0].sidebars).toMatchInlineSnapshot(`
+          Object {
+            "defaultSidebar": Array [
+              Object {
+                "id": "hello-1",
+                "type": "doc",
+              },
+              Object {
+                "id": "hello-2",
+                "label": "Hello 2 From Doc",
+                "type": "doc",
+              },
+            ],
+          }
+      `);
+  });
+
+  test('site with disabled sidebar', async () => {
+    const siteDir = path.join(__dirname, '__fixtures__', 'site-with-doc-label');
+    const context = await loadContext(siteDir);
+    const plugin = pluginContentDocs(
+      context,
+      normalizePluginOptions(OptionsSchema, {
+        sidebarPath: false,
+      }),
+    );
+    const result = await plugin.loadContent!();
+
+    expect(result.loadedVersions).toHaveLength(1);
+    expect(result.loadedVersions[0].sidebars).toEqual(DisabledSidebars);
+  });
 });
 
 describe('empty/no docs website', () => {

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

@@ -14,8 +14,9 @@ import {
   collectSidebarCategories,
   collectSidebarLinks,
   transformSidebarItems,
-  DefaultSidebars,
   processSidebars,
+  DefaultSidebars,
+  DisabledSidebars,
 } from '../sidebars';
 import {
   Sidebar,
@@ -127,35 +128,15 @@ describe('loadSidebars', () => {
   });
 
   test('unexisting path', () => {
-    /*
-    expect(() => loadSidebars('badpath')).toThrowErrorMatchingInlineSnapshot(
-      `"No sidebar file exist at path: badpath"`,
-    );
-     */
-    // See https://github.com/facebook/docusaurus/issues/3366
-    expect(loadSidebars('badpath')).toEqual(DefaultSidebars);
+    expect(loadSidebars('badpath')).toEqual(DisabledSidebars);
   });
 
   test('undefined path', () => {
-    expect(() =>
-      loadSidebars(
-        // @ts-expect-error: bad arg
-        undefined,
-      ),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"sidebarFilePath not provided: undefined"`,
-    );
+    expect(loadSidebars(undefined)).toEqual(DefaultSidebars);
   });
 
-  test('null path', () => {
-    expect(() =>
-      loadSidebars(
-        // @ts-expect-error: bad arg
-        null,
-      ),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"sidebarFilePath not provided: null"`,
-    );
+  test('literal false path', () => {
+    expect(loadSidebars(false)).toEqual(DisabledSidebars);
   });
 
   test('sidebars with category.collapsed property', async () => {

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

@@ -75,7 +75,7 @@ describe('simple site', () => {
       ),
       isLast: true,
       routePriority: -1,
-      sidebarFilePath: path.join(simpleSiteDir, 'sidebars.json'),
+      sidebarFilePath: undefined,
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/docs',
@@ -138,6 +138,9 @@ describe('simple site', () => {
         versionPath: '/myBaseUrl/docs/current-path',
         versionLabel: 'current-label',
         routePriority: undefined,
+        sidebarFilePath: undefined,
+        versionEditUrl: undefined,
+        versionEditUrlLocalized: undefined,
       },
     ]);
   });
@@ -210,6 +213,7 @@ describe('versioned site, pluginId=default', () => {
     const defaultOptions: PluginOptions = {
       id: DEFAULT_PLUGIN_ID,
       ...DEFAULT_OPTIONS,
+      sidebarPath: 'sidebars.json',
     };
     const defaultContext = {
       siteDir: versionedSiteDir,
@@ -607,6 +611,7 @@ describe('versioned site, pluginId=community', () => {
       id: 'community',
       path: 'community',
       routeBasePath: 'communityBasePath',
+      sidebarPath: 'sidebars.json',
     };
     const defaultContext = {
       siteDir: versionedSiteDir,