astro-better-docs-sidebar 0.1.0 → 1.0.0

package/README.md

@@ -122,6 +122,38 @@ hidden: true
 ---
 ```
 
+## Non-routable folder index pages
+
+Set `route: false` in a folder's `index.mdx` to prevent the sidebar from linking to it while still using it to set the folder's title and `order`. The folder heading appears as a plain label with no link.
+
+```yaml
+# docs/core-concepts/index.mdx
+---
+title: Core Concepts
+order: 2
+route: false
+---
+```
+
+This is equivalent to `sidebar.folderBehavior: unclickable` but scoped to the index page itself rather than the `folderBehavior` prop. Use it when a folder should never have a clickable header, regardless of the global `folderBehavior` setting.
+
+Make sure your content collection schema includes `route`:
+
+```ts
+const docs = defineCollection({
+  schema: z.object({
+    title: z.string(),
+    order: z.number().optional(),
+    hidden: z.boolean().optional(),
+    route: z.boolean().optional(),
+    sidebar: z.object({
+      label: z.string().optional(),
+      folderBehavior: z.enum(['page', 'unclickable', 'overview']).optional(),
+    }).optional(),
+  }),
+});
+```
+
 ## Controlling sort order
 
 Set `order` in front matter to control sort position within a folder. Lower numbers sort first. Pages without `order` sort last, then alphabetically by title.

package/Sidebar.astro

@@ -52,27 +52,30 @@ function buildTree(pages: any[]) {
 
       if (part === 'index') {
         const effective: FolderBehavior = pageFolderBehavior || folderBehavior;
-        const href = `${basePath}/${slug.replace(/\/index$/, "")}`.replace(/\/+/g, '/').replace(/\/$/, "");
 
         current.title = label || dataTitle || current.title;
         if (order !== undefined) current.order = order;
 
-        if (effective === 'page') {
-          current.href = href;
-        } else if (effective === 'overview') {
-          // inject a synthetic first child that links to the index page
-          current.children['__sidebar_overview__'] = {
-            name: '__sidebar_overview__',
-            title: overviewLabel,
-            href,
-            children: {},
-            sortedChildren: [],
-            isOpen: false,
-            isActive: false,
-            order: -Infinity,
-          };
+        // route: false pages still contribute title/order but produce no link
+        if (page.data?.route !== false) {
+          const href = `${basePath}/${slug.replace(/\/index$/, "")}`.replace(/\/+/g, '/').replace(/\/$/, "");
+          if (effective === 'page') {
+            current.href = href;
+          } else if (effective === 'overview') {
+            // inject a synthetic first child that links to the index page
+            current.children['__sidebar_overview__'] = {
+              name: '__sidebar_overview__',
+              title: overviewLabel,
+              href,
+              children: {},
+              sortedChildren: [],
+              isOpen: false,
+              isActive: false,
+              order: -Infinity,
+            };
+          }
+          // 'unclickable': no href set, no overview child
         }
-        // 'unclickable': no href set, no overview child
         break;
       }
 
@@ -131,7 +134,7 @@ const treeArray = getSortedArray(treeRoot.children);
 ---
 
 
-<nav class="nav">
+<nav>
   {treeArray.map(node => <SidebarItem node={node} />)}
 </nav>
 
@@ -139,61 +142,58 @@ const treeArray = getSortedArray(treeRoot.children);
   @reference "tailwindcss";
 
   aside.aside { @apply w-64 shrink-0 border-r border-gray-200 bg-white pt-2 pr-2; }
-  .nav { @apply flex flex-col gap-1; }
+  #side-nav nav { @apply flex flex-col gap-1; }
 
-  /* DEPTH LINE */
-  .nav details > div { @apply flex flex-col gap-0.5 pl-3 ml-3 border-l border-slate-200; }
+  /* depth line */
+  #side-nav nav details > div { @apply flex flex-col gap-0.5 pl-3 ml-3 border-l border-slate-200; }
 
-  /* `s` = summary wrapper container */
-  .s { @apply flex items-center justify-between cursor-pointer select-none rounded gap-1 transition-colors text-slate-700; list-style: none; }
-  .s::-webkit-details-marker { display: none; }
+  /* folder header row */
+  #side-nav nav summary { @apply flex items-center justify-between cursor-pointer select-none rounded gap-1 transition-colors text-slate-700; list-style: none; }
+  #side-nav nav summary::-webkit-details-marker { display: none; }
 
-  /* `l` = standalone leaf link OR the text link inside the summary */
-  .l { @apply flex-1 text-sm py-1 px-2 rounded transition-colors no-underline block text-slate-700; }
-  a.l { @apply cursor-pointer; }
-  span.l { @apply cursor-default; }
+  /* leaf links and folder labels */
+  #side-nav nav :is(a, span) { @apply flex-1 text-sm py-1 px-2 rounded transition-colors no-underline block text-slate-700; }
+  #side-nav nav a { @apply cursor-pointer; }
+  #side-nav nav span { @apply cursor-default; }
 
-  /* `c` = chevron element */
-  .c { @apply flex items-center justify-center w-7 h-7 rounded text-gray-400 shrink-0 transition-transform; }
-  .c::after { content: ''; @apply w-[0.4rem] h-[0.4rem] border-r-2 border-b-2 border-current block -rotate-45 transition-transform box-border; }
-  details[open] > .s .c::after { @apply rotate-45; }
+  /* chevron */
+  #side-nav nav i { @apply flex items-center justify-center w-7 h-7 rounded text-gray-400 shrink-0 transition-transform; }
+  #side-nav nav i::after { content: ''; @apply w-[0.4rem] h-[0.4rem] border-r-2 border-b-2 border-current block -rotate-45 transition-transform box-border; }
+  #side-nav nav details[open] > summary i::after { @apply rotate-45; }
 
-  /* JS-FREE FOLDER EXPANSION */
-  details:not([open]) > .s a.l { pointer-events: none; }
+  /* clicking a closed folder opens it; disables the link's own navigation */
+  #side-nav nav details:not([open]) > summary a { pointer-events: none; }
 
-  /* HOVERS: Group Hover (Leaves, Closed Folders, No-Link Folders) */
-  :is(a.l, details:not([open]) > .s, details:not(:has(a.l)) > .s):hover { @apply bg-slate-100; }
-  a.l:hover { @apply text-indigo-600; }
-  :is(details:not([open]) > .s, details:not(:has(a.l)) > .s):hover .l { @apply text-indigo-600; }
-
-  /* HOVERS: Separate Hovers (Open Folders WITH Links) */
-  details[open] > .s:has(a.l) a.l:hover { @apply bg-slate-100 text-indigo-600; }
-  details[open] > .s:has(a.l) .c:hover { @apply bg-slate-100 text-slate-700; }
+  /* HOVERS */
+  #side-nav nav a:not(summary a):hover { @apply bg-slate-100 text-indigo-600; }
+  #side-nav nav details:not([open]) > summary:hover,
+  #side-nav nav summary:not(:has(a)):hover { @apply bg-slate-100; }
+  #side-nav nav details:not([open]) > summary:hover :is(a, span),
+  #side-nav nav summary:not(:has(a)):hover span { @apply text-indigo-600; }
+  #side-nav nav details[open] > summary:has(a) a:hover { @apply bg-slate-100 text-indigo-600; }
+  #side-nav nav details[open] > summary:has(a) i:hover { @apply bg-slate-100 text-slate-700; }
 
   /* ACTIVE & ANCESTOR STATES */
-  .l[aria-current="page"], .s:has(> .l[aria-current="page"]) .l { @apply font-semibold text-indigo-600 bg-indigo-50; }
-  .l[data-a], .s[data-a] .l { @apply font-semibold text-slate-900; }
-  .s:has(> [aria-current="page"]) .c, details:has([aria-current="page"]) > .s .c { @apply text-indigo-500; }
-
-  /* --- DARK MODE --- */
+  #side-nav nav a[aria-current="page"],
+  #side-nav nav summary:has(> a[aria-current="page"]) :is(a, span) { @apply font-semibold text-indigo-600 bg-indigo-50; }
+  #side-nav nav a[data-a],
+  #side-nav nav summary[data-a] :is(a, span) { @apply font-semibold text-slate-900; }
+  #side-nav nav summary:has(> [aria-current="page"]) i,
+  #side-nav nav details:has([aria-current="page"]) > summary i { @apply text-indigo-500; }
+
+  /* DARK MODE */
   .dark aside.aside { @apply border-gray-800 bg-gray-900; }
-
-  /* Dimmed inactive text to increase contrast with bold active items */
-  .dark :is(.l, .s) { @apply text-slate-400; }
-
-  /* Dark mode border color for the depth line */
-  .dark .nav details > div { @apply border-slate-700; }
-
-  .dark :is(a.l, details:not([open]) > .s, details:not(:has(a.l)) > .s):hover { @apply bg-slate-800; }
-  .dark a.l:hover { @apply text-indigo-400; }
-  .dark :is(details:not([open]) > .s, details:not(:has(a.l)) > .s):hover .l { @apply text-indigo-400; }
-
-  .dark details[open] > .s:has(a.l) a.l:hover { @apply bg-slate-800 text-indigo-400; }
-  .dark details[open] > .s:has(a.l) .c:hover { @apply bg-slate-800 text-slate-200; }
-
-  .dark .l[aria-current="page"],
-  .dark .s:has(> .l[aria-current="page"]) .l { @apply text-indigo-400 bg-indigo-950/40; }
-
-  .dark .l[data-a],
-  .dark .s[data-a] .l { @apply text-white; }
+  .dark #side-nav nav :is(a, span) { @apply text-slate-400; }
+  .dark #side-nav nav details > div { @apply border-slate-700; }
+  .dark #side-nav nav a:not(summary a):hover { @apply bg-slate-800 text-indigo-400; }
+  .dark #side-nav nav details:not([open]) > summary:hover,
+  .dark #side-nav nav summary:not(:has(a)):hover { @apply bg-slate-800; }
+  .dark #side-nav nav details:not([open]) > summary:hover :is(a, span),
+  .dark #side-nav nav summary:not(:has(a)):hover span { @apply text-indigo-400; }
+  .dark #side-nav nav details[open] > summary:has(a) a:hover { @apply bg-slate-800 text-indigo-400; }
+  .dark #side-nav nav details[open] > summary:has(a) i:hover { @apply bg-slate-800 text-slate-200; }
+  .dark #side-nav nav a[aria-current="page"],
+  .dark #side-nav nav summary:has(> a[aria-current="page"]) :is(a, span) { @apply text-indigo-400 bg-indigo-950/40; }
+  .dark #side-nav nav a[data-a],
+  .dark #side-nav nav summary[data-a] :is(a, span) { @apply text-white; }
 </style>

package/SidebarItem.astro

@@ -11,18 +11,17 @@ const isAnc = node.isActive && !node.isCurrentPage;
 
 {childNodes.length > 0 ? (
   <details open={node.isOpen || undefined}>
-    <summary class="s" data-a={isAnc || undefined}>
+    <summary data-a={isAnc || undefined}>
       {node.href ? (
         <a
           href={`${node.href}/`}
-          class="l"
           aria-current={node.isCurrentPage ? "page" : undefined}
           set:html={htmlTitle}
         ></a>
       ) : (
-        <span class="l" set:html={htmlTitle}></span>
+        <span set:html={htmlTitle}></span>
       )}
-      <i class="c"></i>
+      <i></i>
     </summary>
     <div>
       {childNodes.map((child: any) => <Astro.self node={child} />)}
@@ -31,7 +30,6 @@ const isAnc = node.isActive && !node.isCurrentPage;
 ) : (
   <a
     href={node.href}
-    class="l"
     aria-current={node.isCurrentPage ? "page" : undefined}
     data-a={isAnc || undefined}
     set:html={htmlTitle}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-better-docs-sidebar",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "type": "module",
   "exports": {
     "./Sidebar.astro": "./Sidebar.astro",