feat(v2): expanded sidebar categories by default (#2682)

* feat: update sidebar categ to  take collapsed prop

* feat: add extra sidebars collapsed test

* fix: only mutate item.collapsed if necessary

* feat: update docs for SidebarItemCategory

* fix: update snapshots

* fix: update json to match new sidebar schema

* fix: update last snapshot

* refactor: check if item should be expanded

* docs: update sidebar categories section

* refactor: use new collpased on docusaurus

* feat: only highlight category for active page

* fix: check for window

* refactor: use ExecutionEnviornment

* refactor: make isCategoryOfActivePage pure

* fix: rename docs to docs-introduction in sidebars

* Update docs.md

* misc: remove setting for every sidebar

Co-authored-by: Yangshun Tay <tay.yang.shun@gmail.com>

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js

@@ -9,25 +9,30 @@ module.exports = {
   docs: [
     {
       type: 'category',
+      collapsed: true,
       label: 'level 1',
       items: [
         'a',
         {
           type: 'category',
+          collapsed: true,
           label: 'level 2',
           items: [
             {
               type: 'category',
+              collapsed: true,
               label: 'level 3',
               items: [
                 'c',
                 {
                   type: 'category',
+                  collapsed: true,
                   label: 'level 4',
                   items: [
                     'd',
                     {
                       type: 'category',
+                      collapsed: true,
                       label: 'deeper more more',
                       items: ['e'],
                     },

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json

@@ -0,0 +1,20 @@
+{
+    "docs": [
+        {
+            "type": "category",
+            "label": "Introduction",
+            "items": [
+                "doc1"
+            ],
+            "collapsed": false
+        },
+        {
+            "type": "category",
+            "label": "Powering MDX",
+            "items": [
+                "doc2"
+            ],
+            "collapsed": false
+        }
+    ]
+}

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

@@ -0,0 +1,21 @@
+{
+    "docs": {
+      "Test": [
+        {
+          "type": "category",
+          "label": "Introduction",
+          "items": ["doc1"],
+          "collapsed": false
+        }
+      ],
+      "Reference": [
+        {
+          "type": "category",
+          "label": "Powering MDX",
+          "items": ["doc2"],
+          "collapsed": false
+        }
+      ]
+    }
+  }
+  

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

@@ -4,6 +4,7 @@ exports[`simple website content 1`] = `
 Object {
   "docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "items": Array [
@@ -36,6 +37,7 @@ Object {
       "type": "category",
     },
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "/docs/hello",
@@ -236,6 +238,7 @@ exports[`versioned website content: all sidebars 1`] = `
 Object {
   "docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "/docs/next/foo/bar",
@@ -247,6 +250,7 @@ Object {
       "type": "category",
     },
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "/docs/next/hello",
@@ -260,6 +264,7 @@ Object {
   ],
   "version-1.0.0/docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "/docs/1.0.0/foo/bar",
@@ -276,6 +281,7 @@ Object {
       "type": "category",
     },
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "/docs/1.0.0/hello",
@@ -289,6 +295,7 @@ Object {
   ],
   "version-1.0.1/docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "/docs/foo/bar",
@@ -300,6 +307,7 @@ Object {
       "type": "category",
     },
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "/docs/hello",
@@ -319,6 +327,7 @@ Object {
   "docsSidebars": Object {
     "version-1.0.0/docs": Array [
       Object {
+        "collapsed": true,
         "items": Array [
           Object {
             "href": "/docs/1.0.0/foo/bar",
@@ -335,6 +344,7 @@ Object {
         "type": "category",
       },
       Object {
+        "collapsed": true,
         "items": Array [
           Object {
             "href": "/docs/1.0.0/hello",
@@ -361,6 +371,7 @@ Object {
   "docsSidebars": Object {
     "version-1.0.1/docs": Array [
       Object {
+        "collapsed": true,
         "items": Array [
           Object {
             "href": "/docs/foo/bar",
@@ -372,6 +383,7 @@ Object {
         "type": "category",
       },
       Object {
+        "collapsed": true,
         "items": Array [
           Object {
             "href": "/docs/hello",
@@ -397,6 +409,7 @@ Object {
   "docsSidebars": Object {
     "docs": Array [
       Object {
+        "collapsed": true,
         "items": Array [
           Object {
             "href": "/docs/next/foo/bar",
@@ -408,6 +421,7 @@ Object {
         "type": "category",
       },
       Object {
+        "collapsed": true,
         "items": Array [
           Object {
             "href": "/docs/next/hello",

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

@@ -4,6 +4,7 @@ exports[`loadSidebars sidebars link 1`] = `
 Object {
   "docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "href": "https://github.com",
@@ -18,30 +19,107 @@ Object {
 }
 `;
 
+exports[`loadSidebars sidebars with category.collapsed property 1`] = `
+Object {
+  "docs": Array [
+    Object {
+      "collapsed": true,
+      "items": Array [
+        Object {
+          "collapsed": false,
+          "items": Array [
+            Object {
+              "id": "doc1",
+              "type": "doc",
+            },
+          ],
+          "label": "Introduction",
+          "type": "category",
+        },
+      ],
+      "label": "Test",
+      "type": "category",
+    },
+    Object {
+      "collapsed": true,
+      "items": Array [
+        Object {
+          "collapsed": false,
+          "items": Array [
+            Object {
+              "id": "doc2",
+              "type": "doc",
+            },
+          ],
+          "label": "Powering MDX",
+          "type": "category",
+        },
+      ],
+      "label": "Reference",
+      "type": "category",
+    },
+  ],
+}
+`;
+
+exports[`loadSidebars sidebars with category.collapsed property at first level 1`] = `
+Object {
+  "docs": Array [
+    Object {
+      "collapsed": false,
+      "items": Array [
+        Object {
+          "id": "doc1",
+          "type": "doc",
+        },
+      ],
+      "label": "Introduction",
+      "type": "category",
+    },
+    Object {
+      "collapsed": false,
+      "items": Array [
+        Object {
+          "id": "doc2",
+          "type": "doc",
+        },
+      ],
+      "label": "Powering MDX",
+      "type": "category",
+    },
+  ],
+}
+`;
+
 exports[`loadSidebars sidebars with deep level of category 1`] = `
 Object {
   "docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "id": "a",
           "type": "doc",
         },
         Object {
+          "collapsed": true,
           "items": Array [
             Object {
+              "collapsed": true,
               "items": Array [
                 Object {
                   "id": "c",
                   "type": "doc",
                 },
                 Object {
+                  "collapsed": true,
                   "items": Array [
                     Object {
                       "id": "d",
                       "type": "doc",
                     },
                     Object {
+                      "collapsed": true,
                       "items": Array [
                         Object {
                           "id": "e",
@@ -100,6 +178,7 @@ exports[`loadSidebars sidebars with known sidebar item type 1`] = `
 Object {
   "docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "id": "foo/bar",
@@ -123,6 +202,7 @@ Object {
       "type": "category",
     },
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "id": "hello",

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

@@ -4,6 +4,7 @@ exports[`docsVersion first time versioning 1`] = `
 Object {
   "version-1.0.0/docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "items": Array [
@@ -33,6 +34,7 @@ Object {
       "type": "category",
     },
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "id": "version-1.0.0/hello",
@@ -50,6 +52,7 @@ exports[`docsVersion not the first time versioning 1`] = `
 Object {
   "version-2.0.0/docs": Array [
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "id": "version-2.0.0/foo/bar",
@@ -60,6 +63,7 @@ Object {
       "type": "category",
     },
     Object {
+      "collapsed": true,
       "items": Array [
         Object {
           "id": "version-2.0.0/hello",

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

@@ -126,4 +126,19 @@ describe('loadSidebars', () => {
     const result = loadSidebars(null);
     expect(result).toEqual({});
   });
+
+  test('sidebars with category.collapsed property', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-collapsed.json');
+    const result = loadSidebars([sidebarPath]);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars with category.collapsed property at first level', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-collapsed-first-level.json',
+    );
+    const result = loadSidebars([sidebarPath]);
+    expect(result).toMatchSnapshot();
+  });
 });

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

@@ -33,6 +33,7 @@ function normalizeCategoryShorthand(
 ): SidebarItemCategoryRaw[] {
   return Object.entries(sidebar).map(([label, items]) => ({
     type: 'category',
+    collapsed: true,
     label,
     items,
   }));
@@ -56,7 +57,7 @@ function assertItem(item: Object, keys: string[]): void {
 }
 
 function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw {
-  assertItem(item, ['items', 'label']);
+  assertItem(item, ['items', 'label', 'collapsed']);
   if (typeof item.label !== 'string') {
     throw new Error(
       `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
@@ -67,6 +68,12 @@ function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw {
       `Error loading ${JSON.stringify(item)}. "items" must be an array.`,
     );
   }
+  // "collapsed" is an optional property
+  if (item.hasOwnProperty('collapsed') && typeof item.collapsed !== 'boolean') {
+    throw new Error(
+      `Error loading ${JSON.stringify(item)}. "collapsed" must be a boolean.`,
+    );
+  }
 }
 
 function assertIsDoc(item: any): asserts item is SidebarItemDoc {

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

@@ -42,12 +42,14 @@ export interface SidebarItemCategory {
   type: 'category';
   label: string;
   items: SidebarItem[];
+  collapsed?: boolean;
 }
 
 export interface SidebarItemCategoryRaw {
   type: 'category';
   label: string;
   items: SidebarItemRaw[];
+  collapsed?: boolean;
 }
 
 export type SidebarItem =
@@ -83,6 +85,7 @@ export interface DocsSidebarItemCategory {
   type: 'category';
   label: string;
   items: DocsSidebarItem[];
+  collapsed?: boolean;
 }
 
 export type DocsSidebarItem = SidebarItemLink | DocsSidebarItemCategory;

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

@@ -6,6 +6,7 @@
  */
 
 import React, {useState, useCallback} from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import classnames from 'classnames';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useAnnouncementBarContext from '@theme/hooks/useAnnouncementBarContext';
@@ -44,6 +45,28 @@ function DocSidebarItem({
     setCollapsed((state) => !state);
   });
 
+  // Make sure we have access to the window
+  const activePageRelativeUrl = ExecutionEnvironment.canUseDOM
+    ? window.location.pathname + window.location.search
+    : null;
+
+  // We need to know if the category item
+  // is the parent of the active page
+  // If it is, this returns true and make sure to highlight this category
+  const isCategoryOfActivePage = (_items, _activePageRelativeUrl) => {
+    // Make sure we have items
+    if (typeof _items !== 'undefined') {
+      return _items.some((categoryItem) => {
+        // Grab the category item's href
+        const childHref = categoryItem.href;
+        // Compare it to the current active page
+        return _activePageRelativeUrl === childHref;
+      });
+    }
+
+    return false;
+  };
+
   switch (type) {
     case 'category':
       return (
@@ -56,7 +79,10 @@ function DocSidebarItem({
             <a
               className={classnames('menu__link', {
                 'menu__link--sublist': collapsible,
-                'menu__link--active': collapsible && !item.collapsed,
+                'menu__link--active':
+                  collapsible &&
+                  !item.collapsed &&
+                  isCategoryOfActivePage(items, activePageRelativeUrl),
               })}
               href="#!"
               onClick={collapsible ? handleItemClick : undefined}
@@ -116,8 +142,18 @@ function mutateSidebarCollapsingState(item, path) {
         items
           .map((childItem) => mutateSidebarCollapsingState(childItem, path))
           .filter((val) => val).length > 0;
+
+      // Check if the user wants the category to be expanded by default
+      const shouldExpand = item.collapsed === false;
+
       // eslint-disable-next-line no-param-reassign
       item.collapsed = !anyChildItemsActive;
+
+      if (shouldExpand) {
+        // eslint-disable-next-line no-param-reassign
+        item.collapsed = false;
+      }
+
       return anyChildItemsActive;
     }
 

website/docs/docs.md

@@ -243,6 +243,7 @@ type SidebarItemCategory = {
   type: 'category';
   label: string; // Sidebar label text.
   items: SidebarItem[]; // Array of sidebar items.
+  collapsed: boolean; // Set the category to be collapsed or open by default
 };
 ```
 
@@ -292,6 +293,26 @@ module.exports = {
 };
 ```
 
+#### Expanded categories by default
+
+For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`:
+
+```js title="sidebars.js"
+module.exports = {
+  docs: {
+    Guides: [
+      'creating-pages',
+      {
+        type: 'category',
+        label: 'Docs',
+        collapsed: false,
+        items: ['markdown-features', 'sidebar', 'versioning'],
+      },
+    ],
+  },
+};
+```
+
 ## Docs-only mode
 
 If you just want the documentation feature, you can enable "docs-only mode".

website/sidebars.js

@@ -6,30 +6,51 @@
  */
 
 module.exports = {
-  docs: {
+  docs: [
-    Docusaurus: ['introduction', 'design-principles', 'contributing'],
+    {
-    'Getting Started': ['installation', 'configuration'],
+      type: 'category',
-    Guides: [
+      label: 'Docusaurus',
-      'creating-pages',
+      items: ['introduction', 'design-principles', 'contributing'],
-      'styling-layout',
+    },
-      'static-assets',
+    {
-      {
+      type: 'category',
-        Docs: ['docs-introduction', 'markdown-features', 'versioning'],
+      label: 'Getting Started',
-      },
+      collapsed: false,
-      'blog',
+      items: ['installation', 'configuration'],
-      'search',
+    },
-      'deployment',
+    {
-      'migrating-from-v1-to-v2',
+      type: 'category',
-    ],
+      label: 'Guides',
-    'Advanced Guides': ['using-plugins', 'using-themes', 'presets'],
+      items: [
-    'API Reference': [
+        'creating-pages',
-      'cli',
+        'styling-layout',
-      'docusaurus-core',
+        'static-assets',
-      'docusaurus.config.js',
+        {
-      'lifecycle-apis',
+          Docs: ['docs-introduction', 'markdown-features', 'versioning'],
-      'theme-classic',
+        },
-    ],
+        'blog',
-  },
+        'search',
+        'deployment',
+        'migrating-from-v1-to-v2',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Advanced Guides',
+      items: ['using-plugins', 'using-themes', 'presets'],
+    },
+    {
+      type: 'category',
+      label: 'API Reference',
+      items: [
+        'cli',
+        'docusaurus-core',
+        'docusaurus.config.js',
+        'lifecycle-apis',
+        'theme-classic',
+      ],
+    },
+  ],
   community: [
     'support',
     'team',