feat(content-docs): allow omitting enclosing array consistently for c…

…ategory shorthand (#6602) * feat(content-docs): allow omitting enclosing array consistently for category shorthand * update snapshot * fix doc
facebook · Feb 4, 2022 · 0c4dc00 · 0c4dc00
1 parent e3fd3e7
commit 0c4dc00
Show file tree

Hide file tree

Showing 6 changed files with 301 additions and 79 deletions.
diff --git a/...aurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/normalization.test.ts.snap b/...aurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/normalization.test.ts.snap
@@ -0,0 +1,96 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`normalization normalizes shorthands 1`] = `
+Object {
+  "sidebar": Array [
+    Object {
+      "items": Array [
+        Object {
+          "id": "doc1",
+          "type": "doc",
+        },
+        Object {
+          "id": "doc2",
+          "type": "doc",
+        },
+      ],
+      "label": "Category",
+      "type": "category",
+    },
+    Object {
+      "items": Array [
+        Object {
+          "items": Array [
+            Object {
+              "id": "doc3",
+              "type": "doc",
+            },
+            Object {
+              "id": "doc4",
+              "type": "doc",
+            },
+          ],
+          "label": "Subcategory 1",
+          "type": "category",
+        },
+        Object {
+          "items": Array [
+            Object {
+              "id": "doc5",
+              "type": "doc",
+            },
+            Object {
+              "id": "doc6",
+              "type": "doc",
+            },
+          ],
+          "label": "Subcategory 2",
+          "type": "category",
+        },
+      ],
+      "label": "Category 2",
+      "type": "category",
+    },
+  ],
+}
+`;
+
+exports[`normalization normalizes shorthands 2`] = `
+Object {
+  "sidebar": Array [
+    Object {
+      "href": "https://google.com",
+      "label": "Google",
+      "type": "link",
+    },
+    Object {
+      "items": Array [
+        Object {
+          "id": "doc1",
+          "type": "doc",
+        },
+        Object {
+          "id": "doc2",
+          "type": "doc",
+        },
+      ],
+      "label": "Category 1",
+      "type": "category",
+    },
+    Object {
+      "items": Array [
+        Object {
+          "id": "doc3",
+          "type": "doc",
+        },
+        Object {
+          "id": "doc4",
+          "type": "doc",
+        },
+      ],
+      "label": "Category 2",
+      "type": "category",
+    },
+  ],
+}
+`;
diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/index.test.ts b/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"`,
+      `"Invalid category {\\"type\\":\\"category\\",\\"label\\":\\"Category Label\\",\\"items\\":\\"doc1\\"}: items must be an array of sidebar items or a category shorthand"`,
     );
   });
 

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts
@@ -0,0 +1,40 @@
+/**
+ * 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 {normalizeSidebars} from '../normalization';
+
+describe('normalization', () => {
+  test('normalizes shorthands', () => {
+    expect(
+      normalizeSidebars({
+        sidebar: {
+          Category: ['doc1', 'doc2'],
+          'Category 2': {
+            'Subcategory 1': ['doc3', 'doc4'],
+            'Subcategory 2': ['doc5', 'doc6'],
+          },
+        },
+      }),
+    ).toMatchSnapshot();
+
+    expect(
+      normalizeSidebars({
+        sidebar: [
+          {
+            type: 'link',
+            label: 'Google',
+            href: 'https://google.com',
+          },
+          {
+            'Category 1': ['doc1', 'doc2'],
+            'Category 2': ['doc3', 'doc4'],
+          },
+        ],
+      }),
+    ).toMatchSnapshot();
+  });
+});
diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts
@@ -50,14 +50,20 @@ export function normalizeItem(
     );
   }
   if (item.type === 'category') {
-    if (typeof item.items !== 'undefined' && !Array.isArray(item.items)) {
+    if (typeof item.items !== 'undefined' && typeof item.items !== 'object') {
       throw new Error(
-        `Invalid category ${JSON.stringify(item)}: items must be an array`,
+        `Invalid category ${JSON.stringify(
+          item,
+        )}: items must be an array of sidebar items or a category shorthand`,
       );
     }
     const normalizedCategory: NormalizedSidebarItemCategory = {
       ...item,
-      items: item.items.flatMap((subItem) => normalizeItem(subItem)),
+      items: Array.isArray(item.items)
+        ? item.items.flatMap((subItem) => normalizeItem(subItem))
+        : normalizeCategoriesShorthand(item.items).flatMap((subItem) =>
+            normalizeItem(subItem),
+          ),
     };
     return [normalizedCategory];
   }

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
@@ -83,13 +83,13 @@ export type SidebarItemCategoryLink =
 // The user-given configuration in sidebars.js, before normalization
 export type SidebarItemCategoryConfig = Expand<
   Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
-    items: SidebarItemConfig[];
+    items: SidebarCategoriesShorthand | SidebarItemConfig[];
     link?: SidebarItemCategoryLinkConfig;
   }
 >;
 
 export type SidebarCategoriesShorthand = {
-  [sidebarCategory: string]: SidebarItemConfig[];
+  [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
 };
 
 export type SidebarItemConfig =