astro-better-docs-sidebar 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# astro-better-docs-sidebar
+
+A documentation sidebar component for Astro that builds navigation trees from your content collection's folder structure. Supports customizable titles for pages and sidebar entries, ignorable shared content, and configurable folder behavior.
+
+## Installation
+
+```sh
+npm install astro-better-docs-sidebar
+```
+
+## Basic usage
+
+```astro
+---
+import { getCollection } from 'astro:content';
+import Sidebar from 'astro-better-docs-sidebar/Sidebar.astro';
+
+const collection = await getCollection('docs');
+---
+
+<Sidebar
+  frontmatter={frontmatter}
+  collection={collection}
+  basePath="/docs"
+/>
+```
+
+The sidebar renders into whatever element you place it in. The `aside.aside` CSS class is styled automatically if you wrap it in `<aside class="aside">`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `frontmatter` | `Record<string, any>` | required | The current page's front matter. |
+| `collection` | `any[]` | required | The Astro content collection to build the tree from. |
+| `basePath` | `string` | required | URL prefix for all links, e.g. `"/docs"`. |
+| `folderBehavior` | `'page' \| 'unclickable' \| 'overview'` | `'page'` | Default behavior for folders that have an index page. See below. |
+| `overviewLabel` | `string` | `'Overview'` | Label for the synthetic overview child in `overview` mode. |
+
+## Folder behavior
+
+When a folder contains an `index.mdx` (or `index.md`), the sidebar needs to decide what to do with it. The `folderBehavior` prop sets the global default, and individual folders can override it via front matter.
+
+### Modes
+
+**`page`** (default) - The folder heading is a clickable link to the index page.
+
+```
+> Core Concepts          <- clickable, links to /docs/core-concepts/
+    What is FusionAuth
+    Architecture
+```
+
+**`unclickable`** - The folder heading is a plain label. The index page is not linked anywhere in the sidebar. Use this when the index page is shared boilerplate or auto-generated content that users should not navigate to directly.
+
+```
+  Core Concepts          <- not clickable, just a label
+    What is FusionAuth
+    Architecture
+```
+
+**`overview`** - The folder heading is a plain label, but a synthetic child entry is inserted at the top of the folder linking to the index page. Use this when the index page has real content but you want the folder itself to stay unclickable.
+
+```
+  Core Concepts          <- not clickable
+    Overview             <- synthetic child, links to /docs/core-concepts/
+    What is FusionAuth
+    Architecture
+```
+
+The `overviewLabel` prop controls the text of this synthetic child globally. It defaults to `'Overview'`.
+
+### Per-folder override
+
+Set `sidebar.folderBehavior` in the front matter of a folder's index page to override the global default for that folder:
+
+```yaml
+---
+title: Core Concepts
+sidebar:
+  folderBehavior: overview
+---
+```
+
+Valid values are the same three strings: `page`, `unclickable`, `overview`.
+
+## Customizing titles
+
+### Page title vs sidebar label
+
+By default the sidebar uses the page's `title` front matter field as the link text. To show a different label in the sidebar without changing the page's `<title>`, set `sidebar.label`:
+
+```yaml
+---
+title: Introduction to Authentication Concepts
+sidebar:
+  label: Introduction
+---
+```
+
+### Folder titles
+
+A folder's display name comes from its `index.mdx` front matter. Set `title` (or `sidebar.label`) there to control how the folder heading reads:
+
+```yaml
+# docs/core-concepts/index.mdx
+---
+title: Core Concepts
+---
+```
+
+If no index page exists, the folder name is derived from the directory slug by splitting on hyphens and capitalizing each word (`core-concepts` becomes `Core Concepts`).
+
+## Hiding pages
+
+Set `hidden: true` in a page's front matter to exclude it from the sidebar entirely:
+
+```yaml
+---
+title: Internal Draft
+hidden: true
+---
+```
+
+## 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.
+
+```yaml
+---
+title: Getting Started
+order: 1
+---
+```
+
+## Styling
+
+The component uses Tailwind CSS `@apply` directives and expects Tailwind to be configured in the consuming project. All styles are injected with `<style is:global>` so they apply regardless of where the component is placed.
+
+The sidebar renders a `<nav class="nav">` element. Wrap it in `<aside class="aside">` to get the default width, border, and background:
+
+```astro
+<aside class="aside">
+  <Sidebar ... />
+</aside>
+```
+
+Dark mode is supported via the `.dark` class on a parent element.
+
+## SidebarItem
+
+The `SidebarItem` component renders individual tree nodes recursively. It is exported separately if you need to build a custom tree and render nodes manually:
+
+```astro
+import SidebarItem from 'astro-better-docs-sidebar/SidebarItem.astro';
+```
+
+A node object passed to `SidebarItem` should have:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Display text (may contain inline markdown). |
+| `href` | `string \| null` | Link URL, or `null` for an unclickable label. |
+| `sortedChildren` | `any[]` | Pre-sorted child nodes. |
+| `isOpen` | `boolean` | Whether the `<details>` element starts open. |
+| `isCurrentPage` | `boolean` | Whether to set `aria-current="page"`. |
+| `isActive` | `boolean` | Whether this node is an ancestor of the current page. |

package/Sidebar.astro

@@ -0,0 +1,199 @@
+---
+import SidebarItem from './SidebarItem.astro';
+
+type FolderBehavior = 'page' | 'unclickable' | 'overview';
+
+interface Props {
+  frontmatter: Record<string, any>;
+  collection: any[];
+  basePath: string;
+  folderBehavior?: FolderBehavior;
+  overviewLabel?: string;
+}
+
+const {
+  frontmatter,
+  collection,
+  basePath,
+  folderBehavior = 'page',
+  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;
+        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,
+          };
+        }
+        // '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);
+---
+
+
+<nav class="nav">
+  {treeArray.map(node => <SidebarItem node={node} />)}
+</nav>
+
+<style is:global>
+  @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; }
+
+  /* `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; }
+
+  /* `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; }
+
+  /* `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; }
+
+  /* JS-FREE FOLDER EXPANSION */
+  details:not([open]) > .s a.l { 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; }
+
+  /* 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 --- */
+  .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; }
+</style>

package/SidebarItem.astro

@@ -0,0 +1,39 @@
+---
+import { Marked } from "marked";
+
+const { node } = Astro.props;
+const childNodes = node.sortedChildren || [];
+
+const remark = new Marked();
+const htmlTitle = remark.parseInline(node.title);
+const isAnc = node.isActive && !node.isCurrentPage;
+---
+
+{childNodes.length > 0 ? (
+  <details open={node.isOpen || undefined}>
+    <summary class="s" 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>
+      )}
+      <i class="c"></i>
+    </summary>
+    <div>
+      {childNodes.map((child: any) => <Astro.self node={child} />)}
+    </div>
+  </details>
+) : (
+  <a
+    href={node.href}
+    class="l"
+    aria-current={node.isCurrentPage ? "page" : undefined}
+    data-a={isAnc || undefined}
+    set:html={htmlTitle}
+  ></a>
+)}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "astro-better-docs-sidebar",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    "./Sidebar.astro": "./Sidebar.astro",
+    "./SidebarItem.astro": "./SidebarItem.astro"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "dependencies": {
+    "marked": "^17.0.0"
+  },
+  "keywords": ["astro", "sidebar", "docs", "navigation"],
+  "license": "MIT"
+}