feat(sidebar): add collapsible root sidebar groups

docs/configuration.md

@@ -306,6 +306,21 @@ window.$docsify = {
 };
 ```
 
+## collapseSidebarGroups
+
+- Type: `Boolean`
+- Default: `false`
+
+Initially collapses all root sidebar groups. Visitors can still expand and
+collapse each group by selecting its title. Their choices are preserved while
+navigating between pages.
+
+```js
+window.$docsify = {
+  collapseSidebarGroups: true,
+};
+```
+
 ## sidebarPosition
 
 - Type: `String`

src/core/config.js

@@ -11,6 +11,7 @@ const defaultDocsifyConfig = () => ({
   autoHeader: false,
   basePath: '',
   catchPluginErrors: true,
+  collapseSidebarGroups: false,
   cornerExternalLinkTarget:
     /** @type {'_blank' | '_self' | '_parent' | '_top'  | '_unfencedTop'} */ (
       '_blank'

src/core/event/index.js

@@ -252,6 +252,17 @@ export function Events(Base) {
 
       // Collapse toggle
       dom.on(sidebarElm, 'click', (/** @type {MouseEvent} */ { target }) => {
+        const groupTitle = /** @type {HTMLElement | null} */ (
+          /** @type {HTMLElement} */ (target).closest(
+            '.group-title[role="button"]',
+          )
+        );
+
+        if (groupTitle) {
+          this.#toggleSidebarGroup(groupTitle);
+          return;
+        }
+
         const linkElm = /** @type {HTMLElement} */ (target).closest('a');
         const linkParent = /** @type {HTMLLIElement} */ (
           linkElm?.closest('li')
@@ -262,6 +273,38 @@ export function Events(Base) {
           linkParent.classList.toggle('collapse');
         }
       });
+
+      dom.on(sidebarElm, 'keydown', (/** @type {KeyboardEvent} */ event) => {
+        const groupTitle = /** @type {HTMLElement | null} */ (
+          /** @type {HTMLElement} */ (event.target).closest(
+            '.group-title[role="button"]',
+          )
+        );
+
+        if (groupTitle && (event.key === 'Enter' || event.key === ' ')) {
+          event.preventDefault();
+          this.#toggleSidebarGroup(groupTitle);
+        }
+      });
+    }
+
+    /**
+     * Toggle a root sidebar group and keep its accessible state in sync.
+     *
+     * @param {HTMLElement} groupTitle
+     * @void
+     */
+    #toggleSidebarGroup(groupTitle) {
+      const group = /** @type {HTMLLIElement | null} */ (
+        groupTitle.closest('li')
+      );
+
+      if (!group) {
+        return;
+      }
+
+      const isCollapsed = group.classList.toggle('collapse');
+      groupTitle.setAttribute('aria-expanded', String(!isCollapsed));
     }
 
     /**

src/core/render/index.js

@@ -294,7 +294,13 @@ export function Render(Base) {
     }
 
     _renderSidebar(text) {
-      const { maxLevel, subMaxLevel, loadSidebar, hideSidebar } = this.config;
+      const {
+        collapseSidebarGroups,
+        maxLevel,
+        subMaxLevel,
+        loadSidebar,
+        hideSidebar,
+      } = this.config;
       const sidebarEl = dom.getNode('aside.sidebar');
       const sidebarNavEl = dom.getNode('.sidebar-nav');
       const sidebarToggleEl = dom.getNode('button.sidebar-toggle');
@@ -310,6 +316,18 @@ export function Render(Base) {
         throw new Error('Compiler is not initialized');
       }
 
+      const sidebarGroupStates = new Map(
+        dom
+          .findAll(
+            sidebarNavEl,
+            'li.group > .group-title[role="button"][data-group-id]',
+          )
+          .map(elm => [
+            elm.getAttribute('data-group-id'),
+            elm.closest('li')?.classList.contains('collapse'),
+          ]),
+      );
+
       dom.setHTML('.sidebar-nav', this.compiler.sidebar(text, maxLevel));
 
       sidebarToggleEl.setAttribute('aria-expanded', String(!isMobile()));
@@ -360,9 +378,48 @@ export function Render(Base) {
 
       pageLinkGroups.forEach(elm => {
         elm.classList.add('group');
-        elm
-          .querySelector(':scope > p:not(:has(> *))')
-          ?.classList.add('group-title');
+
+        let groupTitle = [...elm.children].find(
+          child => child.tagName === 'P' && !child.querySelector('a'),
+        );
+
+        if (!groupTitle) {
+          const sublist = [...elm.children].find(
+            child => child.tagName === 'UL',
+          );
+          const titleNodes = [];
+
+          for (const child of elm.childNodes) {
+            if (child === sublist) {
+              break;
+            }
+
+            titleNodes.push(child);
+          }
+
+          if (sublist && titleNodes.some(node => node.textContent?.trim())) {
+            const newGroupTitle = document.createElement('p');
+            titleNodes.forEach(node => newGroupTitle.append(node));
+            groupTitle = newGroupTitle;
+            elm.insertBefore(newGroupTitle, sublist);
+          }
+        }
+
+        groupTitle?.classList.add('group-title');
+
+        const rootList = elm.parentElement;
+
+        if (groupTitle && rootList?.parentElement === sidebarNavEl) {
+          const groupId = `${[...sidebarNavEl.children].indexOf(rootList)}:${[...rootList.children].indexOf(elm)}`;
+          const isCollapsed =
+            sidebarGroupStates.get(groupId) ?? collapseSidebarGroups;
+
+          elm.classList.toggle('collapse', isCollapsed);
+          groupTitle.setAttribute('data-group-id', groupId);
+          groupTitle.setAttribute('role', 'button');
+          groupTitle.setAttribute('tabindex', '0');
+          groupTitle.setAttribute('aria-expanded', String(!isCollapsed));
+        }
       });
     }
 

src/themes/shared/_classes.css

@@ -53,6 +53,22 @@
         var(--sidebar-chevron-expanded-color) 2.75px 4.25px,
         transparent 4.25px
       );
+  /* Chevron down (Mono) */
+  --sidebar-group-title-bg-expanded: no-repeat
+      calc(var(--_sidebar_pagelink-bg-left) - 2px) center / 5px 6px
+      linear-gradient(
+        225deg,
+        transparent 2.75px,
+        var(--sidebar-chevron-collapsed-color) 2.75px 4.25px,
+        transparent 4.25px
+      ),
+    no-repeat calc(var(--_sidebar_pagelink-bg-left) + 3px) center / 5px 6px
+      linear-gradient(
+        135deg,
+        transparent 2.75px,
+        var(--sidebar-chevron-collapsed-color) 2.75px 4.25px,
+        transparent 4.25px
+      );
   /* Dot (active without children) */
   --sidebar-pagelink-bg-empty: no-repeat var(--_sidebar_pagelink-bg-left) center /
     7px 7px
@@ -65,9 +81,17 @@
 }
 
 body[class*='sidebar-chevron'] {
-  .sidebar-nav a.page-link.no-chevron {
+  .sidebar-nav :is(a.page-link, p.group-title[role='button']).no-chevron {
     background: none;
   }
+
+  .sidebar-nav p.group-title[role='button'] {
+    background: var(--sidebar-pagelink-bg);
+
+    &[aria-expanded='true'] {
+      background: var(--sidebar-group-title-bg-expanded);
+    }
+  }
 }
 
 /* Left */
@@ -81,7 +105,7 @@ body.sidebar-chevron-left {
     --_inset: 18px;
 
     li {
-      a.page-link {
+      :is(a.page-link, p.group-title[role='button']) {
         padding-left: var(--_inset);
       }
 
@@ -104,8 +128,12 @@ body.sidebar-chevron-left {
 
 body.sidebar-chevron-right {
   .sidebar-nav {
+    p.group-title[role='button'] {
+      margin-right: 0;
+    }
+
     li {
-      a {
+      :is(a, p.group-title[role='button']) {
         padding-right: calc(var(--_sidebar-inset) + 15px);
       }
     }
@@ -120,6 +148,14 @@ body.sidebar-chevron-right {
   --sidebar-group-spacing: 1em;
 }
 
+body.sidebar-group-box {
+  :is(.app-nav-merged, .sidebar-nav)
+    > ul
+    > li.group:is(:has(+ :not(.group)), :last-child).collapse {
+    padding-bottom: var(--sidebar-group-spacing);
+  }
+}
+
 /* prettier-ignore */
 :root:has(body.sidebar-group-underline) {
   --sidebar-group-spacing      : 0.5em;

src/themes/shared/_sidebar.css

@@ -67,6 +67,16 @@
         color: var(--sidebar-group-title-color);
         font-size: var(--sidebar-group-title-font-size);
         font-weight: var(--sidebar-group-title-font-weight);
+
+        &[role='button'] {
+          cursor: pointer;
+          user-select: none;
+
+          &:focus-visible {
+            outline: 2px solid currentColor;
+            outline-offset: 2px;
+          }
+        }
       }
     }
 
@@ -89,7 +99,7 @@
     }
 
     &.collapse {
-      > :not(a, p:has(> a.page-link)) {
+      > :not(a, p:has(> a.page-link)):not(.group-title) {
         display: none;
       }
     }
@@ -175,6 +185,7 @@
   body.sticky & {
     position: fixed;
     overflow-y: auto;
+    scrollbar-gutter: stable;
   }
 }
 
@@ -249,7 +260,7 @@
   }
 
   /* Increase tap target size on touch-only devices */
-  @media screen and not (any-hover) {
+  @media screen and (any-hover: none) {
     width: calc(var(--content-margin-inline) - 10px);
   }
 }

test/consume-types/example.js

@@ -33,6 +33,7 @@ const d = new Docsify({
   name: 'Vanilla ESM TypeScript Example',
   themeColor: 'deeppink',
   hideSidebar: false,
+  collapseSidebarGroups: true,
 
   // @ts-expect-error invalid property to test that type checking works
   blahblah: 123,