fix(content-docs): improve sidebar shorthand normalization error message (#6745)

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

@@ -58,7 +58,7 @@ describe('loadSidebars', () => {
     await expect(() =>
       loadSidebars(sidebarPath, params),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"Invalid category {\\"type\\":\\"category\\",\\"label\\":\\"Category Label\\",\\"items\\":\\"doc1\\"}: items must be an array of sidebar items or a category shorthand"`,
+      `"Invalid sidebar items collection \`\\"doc1\\"\` in \`items\` of the category Category Label: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`,
     );
   });
 

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

@@ -37,4 +37,53 @@ describe('normalization', () => {
       }),
     ).toMatchSnapshot();
   });
+  test('rejects some invalid cases', () => {
+    expect(() =>
+      normalizeSidebars({
+        sidebar: {
+          Category: {type: 'autogenerated', dirName: 'foo'},
+          Category2: {type: 'autogenerated', dirName: 'bar'},
+        },
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Invalid sidebar items collection \`{\\"type\\":\\"autogenerated\\",\\"dirName\\":\\"foo\\"}\` in \`items\` of the category Category: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`,
+    );
+
+    expect(() =>
+      normalizeSidebars({
+        sidebar: [
+          'foo',
+          {
+            Category: {
+              type: 'category',
+              items: ['bar', 'baz'],
+            },
+          },
+        ],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Invalid sidebar items collection \`{\\"type\\":\\"category\\",\\"items\\":[\\"bar\\",\\"baz\\"]}\` in \`items\` of the category Category: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`,
+    );
+
+    expect(() =>
+      normalizeSidebars({
+        sidebar: [
+          'foo',
+          {
+            Category: 'bar',
+          },
+        ],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Invalid sidebar items collection \`\\"bar\\"\` in \`items\` of the category Category: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`,
+    );
+
+    expect(() =>
+      normalizeSidebars({
+        sidebar: 'item',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Invalid sidebar items collection \`\\"item\\"\` in sidebar sidebar: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`,
+    );
+  });
 });

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

@@ -18,6 +18,7 @@ import type {
 } from './types';
 import {isCategoriesShorthand} from './utils';
 import _ from 'lodash';
+import logger from '@docusaurus/logger';
 
 function normalizeCategoriesShorthand(
   sidebar: SidebarCategoriesShorthand,
@@ -37,40 +38,37 @@ export function normalizeItem(
   item: SidebarItemConfig,
 ): NormalizedSidebarItem[] {
   if (typeof item === 'string') {
-    return [
-      {
-        type: 'doc',
-        id: item,
-      },
-    ];
+    return [{type: 'doc', id: item}];
   }
   if (isCategoriesShorthand(item)) {
-    return normalizeCategoriesShorthand(item).flatMap((subItem) =>
-      normalizeItem(subItem),
-    );
+    // This will never throw anyways
+    return normalizeSidebar(item, 'sidebar items slice');
   }
   if (item.type === 'category') {
-    if (typeof item.items !== 'undefined' && typeof item.items !== 'object') {
-      throw new Error(
-        `Invalid category ${JSON.stringify(
-          item,
-        )}: items must be an array of sidebar items or a category shorthand`,
-      );
-    }
     const normalizedCategory: NormalizedSidebarItemCategory = {
       ...item,
-      items: Array.isArray(item.items)
-        ? item.items.flatMap((subItem) => normalizeItem(subItem))
-        : normalizeCategoriesShorthand(item.items).flatMap((subItem) =>
-            normalizeItem(subItem),
-          ),
+      items: normalizeSidebar(
+        item.items,
+        logger.interpolate`code=${'items'} of the category name=${item.label}`,
+      ),
     };
     return [normalizedCategory];
   }
   return [item];
 }
 
-function normalizeSidebar(sidebar: SidebarConfig): NormalizedSidebar {
+function normalizeSidebar(
+  sidebar: SidebarConfig,
+  place: string,
+): NormalizedSidebar {
+  if (!Array.isArray(sidebar) && !isCategoriesShorthand(sidebar)) {
+    throw new Error(
+      logger.interpolate`Invalid sidebar items collection code=${JSON.stringify(
+        sidebar,
+      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
+    );
+  }
+
   const normalizedSidebar = Array.isArray(sidebar)
     ? sidebar
     : normalizeCategoriesShorthand(sidebar);
@@ -81,5 +79,7 @@ function normalizeSidebar(sidebar: SidebarConfig): NormalizedSidebar {
 export function normalizeSidebars(
   sidebars: SidebarsConfig,
 ): NormalizedSidebars {
-  return _.mapValues(sidebars, normalizeSidebar);
+  return _.mapValues(sidebars, (sidebar, id) =>
+    normalizeSidebar(sidebar, logger.interpolate`sidebar name=${id}`),
+  );
 }

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

@@ -26,7 +26,7 @@ import type {DocMetadataBase, DocNavLink} from '../types';
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
 ): item is SidebarCategoriesShorthand {
-  return typeof item !== 'string' && !item.type;
+  return typeof item === 'object' && !item.type;
 }
 
 export function transformSidebarItems(