feat(v2): allow non sidebar category to be first item of sidebar (#2032)

* feat(v2): allow non sidebar category to be first item of sidebar

* better error messages

* edit the react component

* Update website/docs/sidebar.md

* nits

* add @babel/plugin-transform-runtime

package.json

@@ -23,10 +23,10 @@
     "tsc": "lerna run tsc --no-private"
   },
   "devDependencies": {
-    "@babel/core": "^7.7.2",
+    "@babel/core": "^7.7.4",
-    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.4.4",
+    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.7.4",
-    "@babel/plugin-proposal-optional-chaining": "^7.6.0",
+    "@babel/plugin-proposal-optional-chaining": "^7.7.4",
-    "@babel/preset-typescript": "^7.7.2",
+    "@babel/preset-typescript": "^7.7.4",
     "@types/express": "^4.17.1",
     "@types/fs-extra": "^8.0.1",
     "@types/inquirer": "^6.5.0",

packages/docusaurus-1.x/package.json

@@ -26,15 +26,15 @@
     "docusaurus-rename-version": "./lib/rename-version.js"
   },
   "dependencies": {
-    "@babel/core": "^7.7.2",
+    "@babel/core": "^7.7.4",
-    "@babel/plugin-proposal-class-properties": "^7.7.0",
+    "@babel/plugin-proposal-class-properties": "^7.7.4",
-    "@babel/plugin-proposal-object-rest-spread": "^7.6.2",
+    "@babel/plugin-proposal-object-rest-spread": "^7.7.4",
     "@babel/polyfill": "^7.7.0",
-    "@babel/preset-env": "^7.7.1",
+    "@babel/preset-env": "^7.7.4",
-    "@babel/preset-react": "^7.7.0",
+    "@babel/preset-react": "^7.7.4",
-    "@babel/register": "^7.7.0",
+    "@babel/register": "^7.7.4",
-    "@babel/traverse": "^7.7.2",
+    "@babel/traverse": "^7.7.4",
-    "@babel/types": "^7.7.2",
+    "@babel/types": "^7.7.4",
     "autoprefixer": "^9.7.2",
     "babylon": "^6.18.0",
     "chalk": "^3.0.0",

packages/docusaurus-mdx-loader/package.json

@@ -8,8 +8,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@babel/parser": "^7.7.3",
+    "@babel/parser": "^7.7.4",
-    "@babel/traverse": "^7.7.2",
+    "@babel/traverse": "^7.7.4",
     "@mdx-js/mdx": "^1.5.1",
     "@mdx-js/react": "^1.5.1",
     "github-slugger": "^1.2.1",

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-label.json

@@ -0,0 +1,11 @@
+{
+  "docs": {
+    "Test": [
+      {
+        "type": "category",
+        "label": true,
+        "items": ["doc1"]
+      }
+    ]
+  }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-doc-id-not-string.json

@@ -0,0 +1,10 @@
+{
+  "docs": {
+    "Test": [
+      {
+        "type": "doc",
+        "id": ["doc1"]
+      }
+    ]
+  }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-invalid-item.json

@@ -0,0 +1,8 @@
+{
+  "docs": [
+    {
+      "a": "b",
+      "c": "d"
+    }
+  ]
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-href.json

@@ -0,0 +1,11 @@
+{
+  "docs": {
+    "Test": [
+      {
+        "type": "link",
+        "label": "GitHub",
+        "href": ["example.com"]
+      }
+    ]
+  }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-label.json

@@ -0,0 +1,11 @@
+{
+  "docs": {
+    "Test": [
+      {
+        "type": "link",
+        "label": false,
+        "href": "https://github.com"
+      }
+    ]
+  }
+}

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-link.json

@@ -0,0 +1,11 @@
+{
+  "docs": {
+    "Test": [
+      {
+        "type": "link",
+        "label": "category",
+        "href": "https://github.com"
+      }
+    ]
+  }
+}

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

@@ -1,5 +1,23 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`loadSidebars sidebars link 1`] = `
+Object {
+  "docs": Array [
+    Object {
+      "items": Array [
+        Object {
+          "href": "https://github.com",
+          "label": "category",
+          "type": "link",
+        },
+      ],
+      "label": "Test",
+      "type": "category",
+    },
+  ],
+}
+`;
+
 exports[`loadSidebars sidebars with deep level of category 1`] = `
 Object {
   "docs": Array [
@@ -57,6 +75,27 @@ Object {
 }
 `;
 
+exports[`loadSidebars sidebars with first level not a category 1`] = `
+Object {
+  "docs": Array [
+    Object {
+      "items": Array [
+        Object {
+          "id": "greeting",
+          "type": "doc",
+        },
+      ],
+      "label": "Getting Started",
+      "type": "category",
+    },
+    Object {
+      "id": "api",
+      "type": "doc",
+    },
+  ],
+}
+`;
+
 exports[`loadSidebars sidebars with known sidebar item type 1`] = `
 Object {
   "docs": Array [

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

@@ -32,7 +32,31 @@ describe('loadSidebars', () => {
     expect(() =>
       loadSidebars([sidebarPath]),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Error loading \\"Category Label\\" category. Category items must be array."`,
+      `"Error loading {\\"type\\":\\"category\\",\\"label\\":\\"Category Label\\",\\"items\\":\\"doc1\\"}. \\"items\\" must be an array."`,
+    );
+  });
+
+  test('sidebars with category but category label is not a string', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-category-wrong-label.json',
+    );
+    expect(() =>
+      loadSidebars([sidebarPath]),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Error loading {\\"type\\":\\"category\\",\\"label\\":true,\\"items\\":[\\"doc1\\"]}. \\"label\\" must be a string."`,
+    );
+  });
+
+  test('sidebars item doc but id is not a string', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-doc-id-not-string.json',
+    );
+    expect(() =>
+      loadSidebars([sidebarPath]),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Error loading {\\"type\\":\\"doc\\",\\"id\\":[\\"doc1\\"]}. \\"id\\" must be a string."`,
     );
   });
 
@@ -41,10 +65,40 @@ describe('loadSidebars', () => {
       fixtureDir,
       'sidebars-first-level-not-category.js',
     );
+    const result = loadSidebars([sidebarPath]);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars link', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link.json');
+    const result = loadSidebars([sidebarPath]);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars link wrong label', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-label.json');
     expect(() =>
       loadSidebars([sidebarPath]),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Error loading {\\"type\\":\\"doc\\",\\"id\\":\\"api\\"}. First level item of a sidebar must be a category"`,
+      `"Error loading {\\"type\\":\\"link\\",\\"label\\":false,\\"href\\":\\"https://github.com\\"}. \\"label\\" must be a string."`,
+    );
+  });
+
+  test('sidebars link wrong href', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-href.json');
+    expect(() =>
+      loadSidebars([sidebarPath]),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Error loading {\\"type\\":\\"link\\",\\"label\\":\\"GitHub\\",\\"href\\":[\\"example.com\\"]}. \\"href\\" must be a string."`,
+    );
+  });
+
+  test('sidebars with invalid sidebar item', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-invalid-item.json');
+    expect(() =>
+      loadSidebars([sidebarPath]),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Unknown sidebar item \\"{\\"a\\":\\"b\\",\\"c\\":\\"d\\"}\\"."`,
     );
   });
 

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

@@ -25,16 +25,16 @@ import {
   LoadedContent,
   SourceToPermalink,
   PermalinkToSidebar,
-  DocsSidebarItemCategory,
   SidebarItemLink,
   SidebarItemDoc,
-  SidebarItemCategory,
   DocsSidebar,
   DocsBaseMetadata,
   MetadataRaw,
   DocsMetadataRaw,
   Metadata,
   VersionToSidebars,
+  SidebarItem,
+  DocsSidebarItem,
 } from './types';
 import {Configuration} from 'webpack';
 import {docsVersion} from './version';
@@ -237,32 +237,24 @@ export default function pluginContentDocs(
         };
       };
 
-      const normalizeCategory = (
+      const normalizeItem = (item: SidebarItem): DocsSidebarItem => {
-        category: SidebarItemCategory,
-      ): DocsSidebarItemCategory => {
-        const items = category.items.map(item => {
         switch (item.type) {
           case 'category':
-              return normalizeCategory(item as SidebarItemCategory);
+            return {...item, items: item.items.map(normalizeItem)};
           case 'ref':
           case 'doc':
-              return convertDocLink(item as SidebarItemDoc);
+            return convertDocLink(item);
           case 'link':
           default:
-              break;
+            return item;
         }
-          return item as SidebarItemLink;
-        });
-        return {...category, items};
       };
 
       // Transform the sidebar so that all sidebar item will be in the form of 'link' or 'category' only
       // This is what will be passed as props to the UI component
       const docsSidebars: DocsSidebar = Object.entries(loadedSidebars).reduce(
-        (acc: DocsSidebar, [sidebarId, sidebarItemCategories]) => {
+        (acc: DocsSidebar, [sidebarId, sidebarItems]) => {
-          acc[sidebarId] = sidebarItemCategories.map(sidebarItemCategory =>
+          acc[sidebarId] = sidebarItems.map(normalizeItem);
-            normalizeCategory(sidebarItemCategory),
-          );
           return acc;
         },
         {},

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

@@ -8,11 +8,13 @@
 import fs from 'fs-extra';
 import importFresh from 'import-fresh';
 import {
-  SidebarItemCategory,
   Sidebar,
   SidebarRaw,
   SidebarItem,
   SidebarItemCategoryRaw,
+  SidebarItemRaw,
+  SidebarItemLink,
+  SidebarItemDoc,
 } from './types';
 
 /**
@@ -32,54 +34,71 @@ function assertItem(item: Object, keys: string[]): void {
   }
 }
 
+function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw {
+  assertItem(item, ['items', 'label']);
+  if (typeof item.label !== 'string') {
+    throw new Error(
+      `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
+    );
+  }
+  if (!Array.isArray(item.items)) {
+    throw new Error(
+      `Error loading ${JSON.stringify(item)}. "items" must be an array.`,
+    );
+  }
+}
+
+function assertIsDoc(item: any): asserts item is SidebarItemDoc {
+  assertItem(item, ['id']);
+  if (typeof item.id !== 'string') {
+    throw new Error(
+      `Error loading ${JSON.stringify(item)}. "id" must be a string.`,
+    );
+  }
+}
+
+function assertIsLink(item: any): asserts item is SidebarItemLink {
+  assertItem(item, ['href', 'label']);
+  if (typeof item.href !== 'string') {
+    throw new Error(
+      `Error loading ${JSON.stringify(item)}. "href" must be a string.`,
+    );
+  }
+  if (typeof item.label !== 'string') {
+    throw new Error(
+      `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
+    );
+  }
+}
+
 /**
- * Normalizes recursively category and all its children. Ensures, that at the end
+ * Normalizes recursively item and all its children. Ensures, that at the end
  * each item will be an object with the corresponding type
  */
-function normalizeCategory(
+function normalizeItem(item: SidebarItemRaw): SidebarItem {
-  category: SidebarItemCategoryRaw,
-  level = 0,
-): SidebarItemCategory {
-  if (level === 0 && category.type !== 'category') {
-    throw new Error(
-      `Error loading ${JSON.stringify(
-        category,
-      )}. First level item of a sidebar must be a category`,
-    );
-  }
-  assertItem(category, ['items', 'label']);
-
-  if (!Array.isArray(category.items)) {
-    throw new Error(
-      `Error loading "${category.label}" category. Category items must be array.`,
-    );
-  }
-
-  const items: SidebarItem[] = category.items.map(item => {
   if (typeof item === 'string') {
     return {
       type: 'doc',
       id: item,
     };
   }
+  if (!item.type) {
+    throw new Error(`Unknown sidebar item "${JSON.stringify(item)}".`);
+  }
   switch (item.type) {
     case 'category':
-        return normalizeCategory(item as SidebarItemCategoryRaw, level + 1);
+      assertIsCategory(item);
+      return {...item, items: item.items.map(normalizeItem)};
     case 'link':
-        assertItem(item, ['href', 'label']);
+      assertIsLink(item);
-        break;
+      return item;
     case 'ref':
     case 'doc':
-        assertItem(item, ['id']);
+      assertIsDoc(item);
-        break;
+      return item;
     default:
       throw new Error(`Unknown sidebar item type: ${item.type}`);
   }
-
-    return item as SidebarItem;
-  });
-
-  return {...category, items};
 }
 
 /**
@@ -88,7 +107,7 @@ function normalizeCategory(
 function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
   return Object.entries(sidebars).reduce(
     (acc: Sidebar, [sidebarId, sidebar]) => {
-      let normalizedSidebar: SidebarItemCategoryRaw[];
+      let normalizedSidebar: SidebarItemRaw[];
 
       if (!Array.isArray(sidebar)) {
         // convert sidebar to a more generic structure
@@ -101,7 +120,7 @@ function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
         normalizedSidebar = sidebar;
       }
 
-      acc[sidebarId] = normalizedSidebar.map(item => normalizeCategory(item));
+      acc[sidebarId] = normalizedSidebar.map(normalizeItem);
 
       return acc;
     },

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

@@ -65,23 +65,27 @@ export type SidebarItemRaw =
 
 // Sidebar given by user that is not normalized yet. e.g: sidebars.json
 export interface SidebarRaw {
-  [sidebarId: string]: {
+  [sidebarId: string]:
+    | {
         [sidebarCategory: string]: SidebarItemRaw[];
-  };
+      }
+    | SidebarItemRaw[];
 }
 
 export interface Sidebar {
-  [sidebarId: string]: SidebarItemCategory[];
+  [sidebarId: string]: SidebarItem[];
 }
 
 export interface DocsSidebarItemCategory {
   type: 'category';
   label: string;
-  items: (SidebarItemLink | DocsSidebarItemCategory)[];
+  items: DocsSidebarItem[];
 }
 
+export type DocsSidebarItem = SidebarItemLink | DocsSidebarItemCategory;
+
 export interface DocsSidebar {
-  [sidebarId: string]: DocsSidebarItemCategory[];
+  [sidebarId: string]: DocsSidebarItem[];
 }
 
 export interface OrderMetadata {

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

@@ -12,7 +12,7 @@ import {
 } from './env';
 import fs from 'fs-extra';
 import path from 'path';
-import {Sidebar, SidebarItemCategory, PathOptions} from './types';
+import {Sidebar, PathOptions, SidebarItem} from './types';
 import loadSidebars from './sidebars';
 
 export function docsVersion(
@@ -80,33 +80,25 @@ export function docsVersion(
     const loadedSidebars: Sidebar = loadSidebars([sidebarPath]);
 
     // Transform id in original sidebar to versioned id
-    const normalizeCategory = (
+    const normalizeItem = (item: SidebarItem): SidebarItem => {
-      category: SidebarItemCategory,
-    ): SidebarItemCategory => {
-      const items = category.items.map(item => {
       switch (item.type) {
         case 'category':
-            return normalizeCategory(item);
+          return {...item, items: item.items.map(normalizeItem)};
         case 'ref':
         case 'doc':
           return {
             type: item.type,
             id: `version-${version}/${item.id}`,
           };
-        }
+        default:
           return item;
-      });
+      }
-      return {...category, items};
     };
 
     const versionedSidebar: Sidebar = Object.entries(loadedSidebars).reduce(
-      (acc: Sidebar, [sidebarId, sidebarItemCategories]) => {
+      (acc: Sidebar, [sidebarId, sidebarItems]) => {
         const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-        acc[
+        acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-          newVersionedSidebarId
-        ] = sidebarItemCategories.map(sidebarItemCategory =>
-          normalizeCategory(sidebarItemCategory),
-        );
         return acc;
       },
       {},

packages/docusaurus-plugin-sitemap/src/__tests__/createSitemap.test.ts

@@ -7,7 +7,6 @@
 
 import createSitemap from '../createSitemap';
 import {DocusaurusConfig} from '@docusaurus/types';
-import DEFAULT_OPTIONS from '../index';
 
 describe('createSitemap', () => {
   test('simple site', () => {

packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js

@@ -171,9 +171,7 @@ function DocSidebar(props) {
           )}
         </button>
         <ul className="menu__list">
-          {sidebarData.map(
+          {sidebarData.map(item => (
-            item =>
-              item.items.length > 0 && (
             <DocSidebarItem
               key={item.label}
               item={item}
@@ -182,8 +180,7 @@ function DocSidebar(props) {
               }}
               collapsible={sidebarCollapsible}
             />
-              ),
+          ))}
-          )}
         </ul>
       </div>
     </div>

packages/docusaurus/package.json

@@ -32,11 +32,11 @@
     "@docusaurus/types": "^2.0.0-alpha.36"
   },
   "dependencies": {
-    "@babel/core": "^7.7.2",
+    "@babel/core": "^7.7.4",
-    "@babel/plugin-syntax-dynamic-import": "^7.2.0",
+    "@babel/plugin-syntax-dynamic-import": "^7.7.4",
     "@babel/plugin-transform-runtime": "^7.7.4",
-    "@babel/preset-env": "^7.7.1",
+    "@babel/preset-env": "^7.7.4",
-    "@babel/preset-react": "^7.7.0",
+    "@babel/preset-react": "^7.7.4",
     "@babel/runtime": "^7.7.4",
     "@docusaurus/utils": "^2.0.0-alpha.36",
     "@endiliey/static-site-generator-webpack-plugin": "^4.0.0",

website/docs/sidebar.md

@@ -26,7 +26,18 @@ module.exports = {
 
 ## Sidebar object
 
-A sidebar object looks like the following. The key `docs` is the name of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` is just a [Sidebar Item](#sidebar-item).
+A sidebar object is defined like this.
+
+```typescript
+type Sidebar = {
+  [sidebarId: string]: {
+    [sidebarCategory: string]: SidebarItem[];
+  } | SidebarItem[];
+}
+```
+
+Below is an example of a sidebar object. The key `docs` is the id of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` are both [sidebar item](#sidebar-item).
+
 
 ```js
 // sidebars.js
@@ -109,6 +120,13 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a
 
 ### Doc
 
+```typescript
+type SidebarItemDoc = string | {
+  type: 'doc';
+  id: string;
+};
+```
+
 Sidebar item type that links to a doc page. Example:
 
 ```js
@@ -141,6 +159,14 @@ module.exports = {
 
 ### Link
 
+```typescript
+type SidebarItemLink = {
+  type: 'link';
+  label: string;
+  href: string;
+};
+```
+
 Sidebar item type that links to a non-document page. Example:
 
 ```js
@@ -153,6 +179,13 @@ Sidebar item type that links to a non-document page. Example:
 
 ### Ref
 
+```typescript
+type SidebarItemRef = {
+  type: 'ref';
+  id: string;
+};
+```
+
 Sidebar item type that links to doc without bounding it to the sidebar. Example:
 
 ```js
@@ -166,11 +199,11 @@ Sidebar item type that links to doc without bounding it to the sidebar. Example:
 
 This is used to add hierarchies to the sidebar:
 
-```js
+```typescript
-{
+type SidebarItemCategory = {
-  type: 'category',
+  type: 'category';
-  label: string, // Sidebar label text.
+  label: string; // Sidebar label text.
-  items: SidebarItem[], // Array of sidebar items.
+  items: SidebarItem[]; // Array of sidebar items.
 }
 ```