docs: add page level sidebar (#1749)

* POC: docs: add page level sidebar

Closes #1341

* docs: hide level 1 test page from navbar

docs/docs/index.mdx

@@ -1,4 +1,5 @@
 ---
+id: homepage
 sidebar_position: 0
 hide_title: true
 sidebar_class_name: display-none

docs/docs/level-1/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Level 1",
+  "className": "display-none"
+}

docs/docs/level-1/level-2/level-2.mdx

@@ -0,0 +1,9 @@
+---
+title: "Level 2"
+displayed_sidebar: level2PageSidebar
+sidebar_custom_props:
+  icon: TbBolt
+  isSidebarRoot: true
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus posuere sollicitudin nisl a euismod. Aenean congue tellus sed sollicitudin posuere. Proin convallis, elit ac mollis scelerisque, purus erat consequat magna, sed pellentesque libero mi vel massa. Phasellus vulputate dolor leo, a vulputate turpis mollis vitae. Mauris purus ante, tempor id erat pellentesque, tempor gravida metus. Praesent gravida arcu orci, vel vestibulum arcu placerat eu. Nulla eu malesuada leo, ac blandit lectus. Nunc egestas nulla at aliquet sollicitudin. Ut mi ante, ullamcorper vel facilisis nec, suscipit at.

docs/docs/level-1/level-2/level-3/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Level 3"
+}

docs/docs/level-1/level-2/level-3/level-4.mdx

@@ -0,0 +1,7 @@
+---
+title: "Level 4"
+sidebar_custom_props:
+  icon: TbBolt
+---
+
+Nam consequat neque et velit molestie, non egestas est aliquam. Aenean sed nisl odio. Curabitur sed augue non justo convallis aliquet. Nam fringilla accumsan ex id ultricies. Interdum et malesuada fames ac ante ipsum primis in faucibus. Duis quis sem ac elit posuere dictum suscipit ut nunc. Nullam id auctor dui. Sed bibendum justo a nulla ultricies tempus. Sed at varius nulla, id pharetra quam. Vivamus a ex sollicitudin, ornare lectus nec, eleifend nisi. Donec sit amet ligula nisi. Integer urna ligula, pellentesque nec lectus et, finibus elementum purus. Etiam sit amet sapien massa.

docs/sidebars.js

@@ -11,10 +11,25 @@
 
 // @ts-check
 
+const backToHomeLink = {
+  /** @type {"ref"} */
+  type: "ref",
+  id: "homepage",
+  label: "Back to home",
+  className: "menu__list-item--home",
+  customProps: {
+    icon: "TbArrowBackUp",
+    iconSize: 20,
+  },
+};
+
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
-  // userGuideSidebar: [{type: 'autogenerated', dirName: 'user-guide'}]
+  docsSidebar: [{ type: "autogenerated", dirName: "." }],
+  level2PageSidebar: [
+    backToHomeLink,
+    { type: "autogenerated", dirName: "level-1/level-2" },
+  ],
 };
 
 module.exports = sidebars;

docs/src/css/custom.css

@@ -174,6 +174,25 @@ li.coming-soon a::after {
   margin-left: var(--ifm-menu-link-padding-horizontal);
 }
 
+.menu__list-item--home {
+  font-size: 13px;
+  margin: 1.5rem 0;
+}
+
+.theme-doc-sidebar-item-link-level-1.menu__list-item--root .sidebar-item-icon {
+  background-clip: content-box;
+  background-color: var(--category-icon-background-color);
+  border: 1px solid var(--category-icon-border-color);
+  border-radius: 8px;
+  padding: 3px;
+  margin-right: 16px;
+}
+.theme-doc-sidebar-item-link-level-1.menu__list-item--root .sidebar-item-icon svg {
+  height: 22px;
+  width: 22px;
+  padding: 1px;
+}
+
 .sidebar-item-icon {
   display: flex;
   vertical-align: center;

docs/src/theme/DocSidebarItem/Category/index.js

@@ -85,15 +85,17 @@ const DocSidebarItemCategory = ({
 
         {!!href && !isInternalLink && <IconExternalLink />}
       </Link>
-      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
-        <DocSidebarItems
-          items={items}
-          tabIndex={collapsed ? -1 : 0}
-          onItemClick={onItemClick}
-          activePath={activePath}
-          level={level + 1}
-        />
-      </Collapsible>
+      {!customProps.isSidebarRoot && (
+        <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
+          <DocSidebarItems
+            items={items}
+            tabIndex={collapsed ? -1 : 0}
+            onItemClick={onItemClick}
+            activePath={activePath}
+            level={level + 1}
+          />
+        </Collapsible>
+      )}
     </li>
   );
 };

docs/src/theme/DocSidebarItem/Link/index.js

@@ -29,6 +29,7 @@ const DocSidebarItemLink = ({
         ThemeClassNames.docs.docSidebarItemLinkLevel(level),
         "menu__list-item",
         `menu__list-item--level${level}`,
+        { "menu__list-item--root": customProps.isSidebarRoot },
         className
       )}
       key={label}