From 48c1041019f8419cda9656611e7db3f6bd9f098e Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sun, 21 Sep 2025 22:56:22 -0700
Subject: [PATCH] Add subgroups to docs utils nav

---
 site/data/sidebar.yml                 | 16 +++++----
 site/src/components/DocsSidebar.astro | 50 ++++++++++++++++++++++++---
 site/src/libs/data.ts                 | 10 ++++--
 site/src/scss/_sidebar.scss           |  5 +++
 4 files changed, 67 insertions(+), 14 deletions(-)

diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index f4dd6c9ab3..49a55ab158 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -117,25 +117,27 @@
   icon_color: red
   pages:
     - title: API
-    - title: Align content
-    - title: Align items
-    - title: Align self
     - title: Aspect ratio
     - title: Background
     - title: Border
     - title: Border radius
     - title: Colors
     - title: Display
-    - title: Flex
+    - group: Flex & Grid
+      pages:
+        - title: Align content
+        - title: Align items
+        - title: Align self
+        - title: Flex
+        - title: Justify content
+        - title: Justify items
+        - title: Place items
     - title: Float
     - title: Interactions
-    - title: Justify content
-    - title: Justify items
     - title: Link
     - title: Object fit
     - title: Opacity
     - title: Overflow
-    - title: Place items
     - title: Position
     - title: Shadows
     - title: Sizing
diff --git a/site/src/components/DocsSidebar.astro b/site/src/components/DocsSidebar.astro
index fb207fb2e9..ca28fb16f5 100644
--- a/site/src/components/DocsSidebar.astro
+++ b/site/src/components/DocsSidebar.astro
@@ -29,8 +29,50 @@ const sidebar = getData('sidebar')
                 {group.title}
               </strong>
               <ul class="list-unstyled fw-normal pb-2 small">
-                {group.pages?.map((page) => {
-                  const docSlug = getSlug(page.title)
+                {group.pages?.map((item: any) => {
+                  // Handle sub-groups
+                  if (item.group && item.pages) {
+                    return (
+                      <li class="mb-2">
+                        <div class="bd-links-subgroup fw-semibold mt-3">
+                          {item.group}
+                        </div>
+                        <ul class="list-unstyled">
+                          {item.pages.map((page: any) => {
+                            const docSlug = getSlug(page.title)
+                            const unversionedPageSlug = `${groupSlug}/${docSlug}`
+
+                            const url = `/docs/${getConfig().docs_version}/${unversionedPageSlug}`
+                            const active = Astro.params.slug === unversionedPageSlug
+
+                            const generatedPage = docsPages.find((page) => page.slug === unversionedPageSlug)
+
+                            // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
+                            if (!generatedPage) {
+                              throw new Error(
+                                `The page '${page.title}' referenced in 'site/data/sidebar.yml' does not exist at '${url}'.`
+                              )
+                            }
+
+                            return (
+                              <li>
+                                <a
+                                  href={url}
+                                  class:list={['bd-links-link d-inline-block rounded', { active }]}
+                                  aria-current={active ? 'page' : undefined}
+                                >
+                                  {page.title}
+                                </a>
+                              </li>
+                            )
+                          })}
+                        </ul>
+                      </li>
+                    )
+                  }
+
+                  // Handle regular pages
+                  const docSlug = getSlug(item.title)
                   const unversionedPageSlug = `${groupSlug}/${docSlug}`
 
                   const url = `/docs/${getConfig().docs_version}/${unversionedPageSlug}`
@@ -41,7 +83,7 @@ const sidebar = getData('sidebar')
                   // This test should not be necessary, see comments for `getSlug()` in `src/libs/utils.ts`.
                   if (!generatedPage) {
                     throw new Error(
-                      `The page '${page.title}' referenced in 'site/data/sidebar.yml' does not exist at '${url}'.`
+                      `The page '${item.title}' referenced in 'site/data/sidebar.yml' does not exist at '${url}'.`
                     )
                   }
 
@@ -52,7 +94,7 @@ const sidebar = getData('sidebar')
                         class:list={['bd-links-link d-inline-block rounded', { active }]}
                         aria-current={active ? 'page' : undefined}
                       >
-                        {page.title}
+                        {item.title}
                       </a>
                     </li>
                   )
diff --git a/site/src/libs/data.ts b/site/src/libs/data.ts
index b4279b965d..9cc89a3ed8 100644
--- a/site/src/libs/data.ts
+++ b/site/src/libs/data.ts
@@ -82,7 +82,11 @@ const dataDefinitions = {
       icon_color: z.string().optional(),
       pages: z
         .object({
-          title: z.string()
+          title: z.string().optional(),
+          group: z.string().optional(),
+          pages: z.object({
+            title: z.string()
+          }).array().optional()
         })
         .array()
         .optional()
@@ -117,7 +121,7 @@ let data = new Map<DataType, z.infer<DataSchema>>()
 export function getData<TType extends DataType>(type: TType): z.infer<(typeof dataDefinitions)[TType]> {
   if (data.has(type)) {
     // Returns the data if it has already been loaded.
-    return data.get(type)
+    return data.get(type) as z.infer<(typeof dataDefinitions)[TType]>
   }
 
   const dataPath = `./site/data/${type}.yml`
@@ -127,7 +131,7 @@ export function getData<TType extends DataType>(type: TType): z.infer<(typeof da
     const rawData = yaml.load(fs.readFileSync(dataPath, 'utf8'))
 
     // Parse the data using the data schema to validate its content and get back a fully typed data object.
-    const parsedData = dataDefinitions[type].parse(rawData)
+    const parsedData = dataDefinitions[type].parse(rawData) as z.infer<(typeof dataDefinitions)[TType]>
 
     // Cache the data.
     data.set(type, parsedData)
diff --git a/site/src/scss/_sidebar.scss b/site/src/scss/_sidebar.scss
index 10e750f32b..edf7db77e8 100644
--- a/site/src/scss/_sidebar.scss
+++ b/site/src/scss/_sidebar.scss
@@ -28,6 +28,11 @@
   color: var(--bs-emphasis-color);
 }
 
+.bd-links-subgroup {
+  margin-left: 1.625rem;
+  color: var(--bs-emphasis-color);
+}
+
 .bd-links-nav {
   // @include media-breakpoint-down(lg) {
   //   font-size: .875rem;