astro-better-docs-sidebar 0.2.0 → 1.1.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Better Static Sites
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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

@@ -1,5 +1,6 @@
 ---
 import SidebarItem from './SidebarItem.astro';
+import { sidebarFor } from './tree.js';
 
 type FolderBehavior = 'page' | 'unclickable' | 'overview';
 
@@ -19,122 +20,11 @@ const {
   overviewLabel = 'Overview',
 } = Astro.props;
 
-const normalizeForMatch = (p: string | null) => {
-  if (!p) return "";
-  let clean = decodeURI(p);
-  if (clean.startsWith(basePath)) clean = clean.substring(basePath.length);
-  return clean.replace(/\.(md|mdx|html)$/i, '').replace(/\/index$/i, '').replace(/^\/+|\/+$/g, '');
-};
-
-const safeCurrentPath = normalizeForMatch(Astro.url.pathname);
-const formatTitle = (str: string) => str.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
-
-function buildTree(pages: any[]) {
-  const root: any = { children: {}, title: 'Documentation', href: basePath, order: -1 };
-  for (const page of pages) {
-    const { order, hidden, title: dataTitle } = page.data;
-    const label = page.data?.sidebar?.label;
-    const pageFolderBehavior: FolderBehavior | undefined = page.data?.sidebar?.folderBehavior;
-    if (hidden === true) continue;
-
-    const slug = page.slug || page.id || "";
-    const parts = slug.split('/');
-    let current = root;
-
-    if (slug === "index" || slug === "") {
-      root.title = label || dataTitle || root.title;
-      if (order !== undefined) root.order = order;
-      continue;
-    }
-
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-
-      if (part === 'index') {
-        const effective: FolderBehavior = pageFolderBehavior || folderBehavior;
-
-        current.title = label || dataTitle || current.title;
-        if (order !== undefined) current.order = order;
-
-        // 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
-        }
-        break;
-      }
-
-      if (!current.children[part]) {
-        current.children[part] = {
-          name: part,
-          title: formatTitle(part),
-          href: null,
-          children: {},
-          isOpen: false,
-          isActive: false,
-          order: Infinity,
-        };
-      }
-
-      if (i === parts.length - 1) {
-        current.children[part].title = label || dataTitle || formatTitle(part);
-        current.children[part].href = `${basePath}/${slug.replace(/\.(md|mdx)$/i, '')}`.replace(/\/+/g, '/').replace(/\/$/, "");
-        if (order !== undefined) current.children[part].order = order;
-      }
-      current = current.children[part];
-    }
-  }
-  return root;
-}
-
-const treeRoot = buildTree(collection);
-
-function markActiveAndOpen(node: any): boolean {
-  node.isCurrentPage = node.href != null && normalizeForMatch(node.href) === safeCurrentPath;
-  let hasActiveChild = false;
-  for (const key in node.children) {
-    if (markActiveAndOpen(node.children[key])) hasActiveChild = true;
-  }
-  node.isActive = node.isCurrentPage || hasActiveChild;
-  node.isOpen = node.isActive;
-  return node.isActive;
-}
-
-markActiveAndOpen(treeRoot);
-
-function getSortedArray(nodeChildren: Record<string, any>) {
-  const arr = Object.values(nodeChildren);
-  arr.sort((a, b) => {
-    const vA = a.order === undefined ? Infinity : a.order;
-    const vB = b.order === undefined ? Infinity : b.order;
-    return vA !== vB ? vA - vB : a.title.localeCompare(b.title);
-  });
-  arr.forEach(child => {
-    child.sortedChildren = child.children && Object.keys(child.children).length > 0 ? getSortedArray(child.children) : [];
-  });
-  return arr;
-}
-
-const treeArray = getSortedArray(treeRoot.children);
+const treeArray = sidebarFor(collection, { basePath, folderBehavior, overviewLabel }, Astro.url.pathname);
 ---
 
 
-<nav class="nav">
+<nav>
   {treeArray.map(node => <SidebarItem node={node} />)}
 </nav>
 
@@ -142,61 +32,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; }
-
-  /* DEPTH LINE */
-  .nav details > div { @apply flex flex-col gap-0.5 pl-3 ml-3 border-l border-slate-200; }
+  #side-nav nav { @apply flex flex-col gap-1; }
 
-  /* `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; }
+  /* depth line */
+  #side-nav nav details > div { @apply flex flex-col gap-0.5 pl-3 ml-3 border-l border-slate-200; }
 
-  /* `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; }
+  /* 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; }
 
-  /* `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; }
+  /* 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; }
 
-  /* JS-FREE FOLDER EXPANSION */
-  details:not([open]) > .s a.l { pointer-events: none; }
+  /* 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; }
 
-  /* 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; }
+  /* clicking a closed folder opens it; disables the link's own navigation */
+  #side-nav nav details:not([open]) > summary a { pointer-events: none; }
 
-  /* 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

@@ -1,28 +1,26 @@
 ---
-import { Marked } from "marked";
+import { titleHtml } from "./tree.js";
 
 const { node } = Astro.props;
 const childNodes = node.sortedChildren || [];
 
-const remark = new Marked();
-const htmlTitle = remark.parseInline(node.title);
+const htmlTitle = node.htmlTitle ?? titleHtml(node.title);
 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 +29,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,17 +1,38 @@
 {
   "name": "astro-better-docs-sidebar",
-  "version": "0.2.0",
+  "version": "1.1.0",
+  "keywords": [
+    "astro",
+    "sidebar",
+    "docs",
+    "navigation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/better-static-sites/better-static-sites.github.io.git",
+    "directory": "astro-better-docs-sidebar"
+  },
+  "homepage": "https://better-static-sites.github.io",
+  "bugs": {
+    "url": "https://github.com/better-static-sites/better-static-sites.github.io/issues"
+  },
   "type": "module",
   "exports": {
     "./Sidebar.astro": "./Sidebar.astro",
     "./SidebarItem.astro": "./SidebarItem.astro"
   },
-  "peerDependencies": {
-    "astro": ">=4.0.0"
-  },
+  "files": [
+    "*.astro",
+    "tree.js"
+  ],
   "dependencies": {
     "marked": "^17.0.0"
   },
-  "keywords": ["astro", "sidebar", "docs", "navigation"],
-  "license": "MIT"
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  }
 }

package/tree.js

@@ -0,0 +1,186 @@
+/**
+ * Sidebar tree building, shared across every page of a build.
+ *
+ * The tree only depends on the collection and the sidebar options, so it is
+ * built and sorted once per distinct input. Each page then gets a view that
+ * copies just the nodes on its active path, with the open/active flags set.
+ */
+
+import { Marked } from 'marked';
+
+const marked = new Marked();
+const titleHtmlCache = new Map();
+
+/** Inline-markdown title HTML, parsed once per distinct title. */
+export function titleHtml(title) {
+  let html = titleHtmlCache.get(title);
+  if (html === undefined) {
+    html = marked.parseInline(title);
+    titleHtmlCache.set(title, html);
+  }
+  return html;
+}
+
+export function normalizeForMatch(p, basePath) {
+  if (!p) return "";
+  let clean = decodeURI(p);
+  if (clean.startsWith(basePath)) clean = clean.substring(basePath.length);
+  return clean.replace(/\.(md|mdx|html)$/i, '').replace(/\/index$/i, '').replace(/^\/+|\/+$/g, '');
+}
+
+const formatTitle = (str) => str.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+
+function buildTree(pages, { basePath, folderBehavior, overviewLabel }) {
+  const root = { children: {}, title: 'Documentation', href: basePath, order: -1 };
+  for (const page of pages) {
+    const { order, hidden, title: dataTitle } = page.data;
+    const label = page.data?.sidebar?.label;
+    const pageFolderBehavior = page.data?.sidebar?.folderBehavior;
+    if (hidden === true) continue;
+
+    const slug = page.slug || page.id || "";
+    const parts = slug.split('/');
+    let current = root;
+
+    if (slug === "index" || slug === "") {
+      root.title = label || dataTitle || root.title;
+      if (order !== undefined) root.order = order;
+      continue;
+    }
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+
+      if (part === 'index') {
+        const effective = pageFolderBehavior || folderBehavior;
+
+        current.title = label || dataTitle || current.title;
+        if (order !== undefined) current.order = order;
+
+        // 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
+        }
+        break;
+      }
+
+      if (!current.children[part]) {
+        current.children[part] = {
+          name: part,
+          title: formatTitle(part),
+          href: null,
+          children: {},
+          isOpen: false,
+          isActive: false,
+          order: Infinity,
+        };
+      }
+
+      if (i === parts.length - 1) {
+        current.children[part].title = label || dataTitle || formatTitle(part);
+        current.children[part].href = `${basePath}/${slug.replace(/\.(md|mdx)$/i, '')}`.replace(/\/+/g, '/').replace(/\/$/, "");
+        if (order !== undefined) current.children[part].order = order;
+      }
+      current = current.children[part];
+    }
+  }
+  return root;
+}
+
+function getSortedArray(nodeChildren) {
+  const arr = Object.values(nodeChildren);
+  arr.sort((a, b) => {
+    const vA = a.order === undefined ? Infinity : a.order;
+    const vB = b.order === undefined ? Infinity : b.order;
+    return vA !== vB ? vA - vB : a.title.localeCompare(b.title);
+  });
+  arr.forEach(child => {
+    child.sortedChildren = child.children && Object.keys(child.children).length > 0 ? getSortedArray(child.children) : [];
+  });
+  return arr;
+}
+
+// Everything buildTree reads, so equal keys always build equal trees.
+function cacheKey(pages, opts) {
+  const parts = [JSON.stringify([opts.basePath, opts.folderBehavior, opts.overviewLabel])];
+  for (const page of pages) {
+    const d = page.data ?? {};
+    parts.push(JSON.stringify([page.slug, page.id, d.order, d.hidden, d.title, d.sidebar?.label, d.sidebar?.folderBehavior, d.route]));
+  }
+  return parts.join('\n');
+}
+
+// dev servers rebuild on every content change; keep only recent trees
+const MAX_CACHED_TREES = 8;
+const cache = new Map();
+
+function cachedTree(pages, opts) {
+  const key = cacheKey(pages, opts);
+  let entry = cache.get(key);
+  if (entry) return entry;
+
+  const root = buildTree(pages, opts);
+  const nodes = getSortedArray(root.children);
+
+  // flags start false; each page's view flips them along its active path
+  const parents = new Map();
+  const byHref = new Map();
+  const index = (list, parent) => {
+    for (const node of list) {
+      node.isCurrentPage = false;
+      node.isActive = false;
+      node.isOpen = false;
+      node.htmlTitle = titleHtml(node.title);
+      if (parent) parents.set(node, parent);
+      if (node.href != null) {
+        const match = normalizeForMatch(node.href, opts.basePath);
+        if (!byHref.has(match)) byHref.set(match, []);
+        byHref.get(match).push(node);
+      }
+      index(node.sortedChildren, node);
+    }
+  };
+  index(nodes, null);
+
+  entry = { nodes, parents, byHref };
+  cache.set(key, entry);
+  if (cache.size > MAX_CACHED_TREES) cache.delete(cache.keys().next().value);
+  return entry;
+}
+
+/**
+ * Sorted top-level sidebar nodes for one page, with isCurrentPage, isActive,
+ * and isOpen set as they would be on a freshly built tree. Shared nodes are
+ * never mutated; nodes on the active path are copies.
+ */
+export function sidebarFor(pages, opts, pathname) {
+  const { nodes, parents, byHref } = cachedTree(pages, opts);
+  const current = new Set(byHref.get(normalizeForMatch(pathname, opts.basePath)) ?? []);
+  if (current.size === 0) return nodes;
+
+  const active = new Set();
+  for (const node of current) {
+    for (let n = node; n && !active.has(n); n = parents.get(n)) active.add(n);
+  }
+
+  const view = (list) => list.map(node => active.has(node)
+    ? { ...node, isCurrentPage: current.has(node), isActive: true, isOpen: true, sortedChildren: view(node.sortedChildren) }
+    : node);
+  return view(nodes);
+}