feat(theme-classic): auto-collapse sibling categories in doc sidebar

packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx

@@ -86,6 +86,9 @@ function DocPageContent({
               sidebarCollapsible={
                 siteConfig.themeConfig?.sidebarCollapsible ?? true
               }
+              autoCollapseSidebar={
+                siteConfig.themeConfig?.autoCollapseSidebar ?? false
+              }
               onCollapse={toggleSidebar}
               isHidden={hiddenSidebar}
             />

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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState, useCallback, useEffect, useRef} from 'react';
+import React, {useState, useEffect, useRef} from 'react';
 import clsx from 'clsx';
 import {useThemeConfig, isSamePath} from '@docusaurus/theme-common';
 import useUserPreferencesContext from '@theme/hooks/useUserPreferencesContext';
@@ -23,6 +23,10 @@ import styles from './styles.module.css';
 
 const MOBILE_TOGGLE_SIZE = 24;
 
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 function usePrevious(value) {
   const ref = useRef(value);
   useEffect(() => {
@@ -48,6 +52,8 @@ function DocSidebarItemCategory({
   onItemClick,
   collapsible,
   activePath,
+  autoCollapseCategory,
+  autoCollapse,
   ...props
 }) {
   const {items, label} = item;
@@ -65,6 +71,7 @@ function DocSidebarItemCategory({
   });
 
   const menuListRef = useRef<HTMLUListElement>(null);
+  const [currentCategory, setCurrentCategory] = useState(item);
   const [menuListHeight, setMenuListHeight] = useState<string | undefined>(
     undefined,
   );
@@ -82,18 +89,14 @@ function DocSidebarItemCategory({
     }
   }, [isActive, wasActive, collapsed]);
 
-  const handleItemClick = useCallback(
-    (e) => {
-      e.preventDefault();
-
-      if (!menuListHeight) {
-        handleMenuListHeight();
-      }
+  const handleItemClick = async (category) => {
+    if (!menuListHeight) {
+      handleMenuListHeight();
+    }
 
-      setTimeout(() => setCollapsed((state) => !state), 100);
-    },
-    [menuListHeight],
-  );
+    const updatedCategory = await autoCollapseCategory(category);
+    setCurrentCategory(updatedCategory);
+  };
 
   if (items.length === 0) {
     return null;
@@ -102,7 +105,7 @@ function DocSidebarItemCategory({
   return (
     <li
       className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
+        'menu__list-item--collapsed': currentCategory.collapsed,
       })}
       key={label}>
       <a
@@ -111,7 +114,9 @@ function DocSidebarItemCategory({
           'menu__link--active': collapsible && isActive,
           [styles.menuLinkText]: !collapsible,
         })}
-        onClick={collapsible ? handleItemClick : undefined}
+        onClick={
+          collapsible ? () => handleItemClick(currentCategory) : undefined
+        }
         href={collapsible ? '#!' : undefined}
         {...props}>
         {label}
@@ -132,6 +137,8 @@ function DocSidebarItemCategory({
             tabIndex={collapsed ? '-1' : '0'}
             key={childItem.label}
             item={childItem}
+            autoCollapse={autoCollapse}
+            parent={items}
             onItemClick={onItemClick}
             collapsible={collapsible}
             activePath={activePath}
@@ -176,9 +183,37 @@ function DocSidebarItemLink({
 }
 
 function DocSidebarItem(props) {
+  const {autoCollapse, parent} = props;
+
+  const autoCollapseCategory = async (item) => {
+    const isCollapsed = item.collapsed;
+
+    if (!isCollapsed) {
+      item.collapsed = !item.collapsed;
+    } else {
+      if (autoCollapse) {
+        for (const s in parent) {
+          if (parent[s].type !== 'link') {
+            parent[s].collapsed = true;
+          } else {
+            parent[s].collapsed = false;
+          }
+        }
+      }
+      item.collapsed = !item.collapsed;
+    }
+    await sleep(100);
+    return item;
+  };
+
   switch (props.item.type) {
     case 'category':
-      return <DocSidebarItemCategory {...props} />;
+      return (
+        <DocSidebarItemCategory
+          {...props}
+          autoCollapseCategory={autoCollapseCategory}
+        />
+      );
     case 'link':
     default:
       return <DocSidebarItemLink {...props} />;
@@ -189,6 +224,7 @@ function DocSidebar({
   path,
   sidebar,
   sidebarCollapsible = true,
+  autoCollapseSidebar,
   onCollapse,
   isHidden,
 }: Props): JSX.Element | null {
@@ -262,6 +298,8 @@ function DocSidebar({
                 setShowResponsiveSidebar(false);
               }}
               collapsible={sidebarCollapsible}
+              parent={sidebar}
+              autoCollapse={autoCollapseSidebar}
               activePath={path}
             />
           ))}

packages/docusaurus-theme-classic/src/types.d.ts

@@ -79,6 +79,7 @@ declare module '@theme/DocSidebar' {
     readonly path: string;
     readonly sidebar: readonly PropSidebarItem[];
     readonly sidebarCollapsible?: boolean;
+    readonly autoCollapseSidebar?: boolean;
     readonly onCollapse: () => void;
     readonly isHidden: boolean;
   };

packages/docusaurus/src/webpack/__tests__/utils.test.ts

@@ -135,7 +135,7 @@ describe('extending generated webpack config', () => {
 
 describe('getFileLoaderUtils()', () => {
   test('plugin svgo/removeViewBox should be disabled', () => {
-    const use = getFileLoaderUtils().rules.svg().use;
+    const {use} = getFileLoaderUtils().rules.svg();
     expect(use).toContainEqual(
       expect.objectContaining({
         loader: '@svgr/webpack',

website/docs/deployment.mdx

@@ -50,11 +50,9 @@ First, modify your `docusaurus.config.js` and add the required params:
 | `url` | URL for your GitHub Page's user/organization page. This is commonly https://_username_.github.io. |
 | `baseUrl` | Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. |
 
-:::info
-In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment.
+:::info In case you want to use your custom domain for GitHub Pages, create a `CNAME` file in the `static` directory. Anything within the `static` directory will be copied to the root of the `build` directory for deployment.
 
-You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details.
-:::
+You may refer to GitHub Pages' documentation [User, Organization, and Project Pages](https://help.github.com/en/articles/user-organization-and-project-pages) for more details. :::
 
 Example:
 

website/docs/sidebar.md

@@ -77,9 +77,7 @@ module.exports = {
 };
 ```
 
-:::note
-Shorthand notation relies on the iteration order of JavaScript object keys for the category name. When using this notation, keep in mind that EcmaScript does not guarantee `Object.keys({a,b}) === ['a','b']`, yet this is generally true.
-:::
+:::note Shorthand notation relies on the iteration order of JavaScript object keys for the category name. When using this notation, keep in mind that EcmaScript does not guarantee `Object.keys({a,b}) === ['a','b']`, yet this is generally true. :::
 
 ## Using multiple sidebars
 
@@ -270,6 +268,20 @@ module.exports = {
 };
 ```
 
+### Auto Collapsable Sidebar
+
+Using the enabled `themeConfig.autoCollapseSidebar` option, you can make the sidebar only have one parent category open at a time, helping users not get cluttered and only focus on the content they selected. If you want them to be enable this feature, set `themeConfig.autoCollapseSidebar` to `true`:
+
+```js {4} title="docusaurus.config.js"
+module.exports = {
+  // ...
+  themeConfig: {
+    autoCollapseSidebar: true,
+    // ...
+  },
+};
+```
+
 #### 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`:

website/docusaurus.config.js

@@ -246,6 +246,7 @@ module.exports = {
   ],
   themeConfig: {
     hideableSidebar: true,
+    autoCollapseSidebar: true,
     colorMode: {
       defaultMode: 'light',
       disableSwitch: false,