boltdocs 1.6.0 → 1.7.0

package/src/client/theme/ui/Sidebar/sidebar.css

@@ -8,72 +8,44 @@
   backdrop-filter: blur(var(--ld-sidebar-blur));
   -webkit-backdrop-filter: blur(var(--ld-sidebar-blur));
   border-right: 1px solid var(--ld-border-subtle);
-  padding: 1rem 0.6rem;
+  padding: 1.5rem 0.6rem;
   overflow-y: auto;
-  position: sticky;
-  top: var(--ld-navbar-height);
-  height: calc(100vh - var(--ld-navbar-height));
-  scrollbar-width: thin;
-  scrollbar-color: var(--ld-bg-mute) transparent;
+  height: 100%;
+  scrollbar-width: none;
   display: flex;
   flex-direction: column;
-  transition:
-    width 0.3s cubic-bezier(0.16, 1, 0.3, 1),
-    padding 0.3s cubic-bezier(0.16, 1, 0.3, 1),
-    opacity 0.2s ease;
+  /* Hardware acceleration */
+  transform: translate3d(0, 0, 0);
+  backface-visibility: hidden;
 }
 
-.boltdocs-sidebar > nav {
-  flex: 1;
-}
-
-/* ─── Collapsible Sidebar ────────────────────────────────── */
-.boltdocs-main-container.sidebar-collapsed .boltdocs-sidebar {
-  width: 54px;
-  padding: 1rem 0;
-  border-right: 1px solid var(--ld-border-subtle);
-  opacity: 1;
-  pointer-events: auto;
-  overflow: hidden;
-}
-
-.sidebar-collapse {
-  width: 100%;
+.sidebar-icon {
+  flex-shrink: 0;
   display: flex;
   align-items: center;
-  justify-content: flex-end;
-  padding: 0 0.75rem 1rem;
-  transition: justify-content 0.3s ease;
-}
-
-.boltdocs-main-container.sidebar-collapsed .sidebar-collapse {
   justify-content: center;
-  padding: 0 0 1rem;
 }
 
-.sidebar-collapse-btn {
+.sidebar-icon.lucide-icon,
+.sidebar-icon.svg-icon svg {
   color: var(--ld-text-muted);
-  border: none;
-  box-shadow: none;
-  background-color: transparent;
-  cursor: pointer;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 32px;
-  height: 32px;
-  border-radius: var(--ld-radius-md);
-  transition: all 0.2s cubic-bezier(0.16, 1, 0.3, 1);
+  width: 18px;
+  height: 18px;
+  stroke-width: 2px;
+  transition: color 0.2s ease;
 }
 
-.sidebar-collapse-btn:hover {
-  background-color: var(--ld-bg-mute);
-  color: var(--ld-text-main);
-  transform: scale(1.05);
+.sidebar-link:hover .sidebar-icon.lucide-icon,
+.sidebar-link.active .sidebar-icon.lucide-icon {
+  color: var(--ld-color-primary);
+}
+
+.boltdocs-sidebar > nav {
+  flex: 1;
 }
 
 .boltdocs-sidebar::-webkit-scrollbar {
-  width: 4px;
+  display: none;
 }
 
 .boltdocs-sidebar::-webkit-scrollbar-track {
@@ -92,23 +64,29 @@
 }
 
 .sidebar-list li {
-  margin-bottom: 1px;
+  margin-bottom: 2px;
 }
 
 .sidebar-link {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  padding: 0.45rem 0.75rem;
+  padding: 0.5rem 0.75rem;
   color: var(--ld-text-muted);
   text-decoration: none;
-  border-radius: var(--ld-radius-md);
+  border-radius: 0.75rem; /* Large rounded corners */
   font-size: 0.875rem;
   font-weight: 500;
   transition: all 0.2s ease;
   margin: 0.15rem 0;
 }
 
+.sidebar-link-title-container {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
 .sidebar-link-content {
   display: flex;
   align-items: center;
@@ -117,7 +95,7 @@
   gap: 0.5rem;
 }
 
-.sidebar-link-content > span:first-child {
+.sidebar-link-content > span:last-child {
   flex: 1;
   word-wrap: break-word;
 }
@@ -162,11 +140,13 @@
 
 .sidebar-link:hover {
   color: var(--ld-color-primary-hover);
+  background-color: var(--ld-bg-soft);
 }
 
 .sidebar-link.active {
   color: var(--ld-color-primary);
   font-weight: 600;
+  background-color: var(--ld-bg-soft);
 }
 
 /* ─── Sidebar Groups ─────────────────────────────────────── */
@@ -183,29 +163,32 @@
   align-items: center;
   justify-content: space-between;
   width: 100%;
-  padding: 0.35rem 0.75rem;
+  padding: 0.5rem 0.75rem;
   background: none;
   border: none;
   border-radius: var(--ld-radius-md);
-  color: var(--ld-text-dim);
+  color: var(--ld-text-muted);
   font-family: var(--ld-font-sans);
-  font-size: 0.6875rem;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
+  font-size: 0.8125rem;
+  font-weight: 600;
   cursor: pointer;
   transition:
     color 0.2s,
     background-color 0.2s;
 }
 
+.sidebar-group-header-content {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
 .sidebar-group-header:hover {
-  color: var(--ld-text-muted);
-  background-color: rgba(255, 255, 255, 0.03);
+  color: var(--ld-text-main);
 }
 
 .sidebar-group-header.active {
-  color: var(--ld-color-primary);
+  color: var(--ld-text-main);
 }
 
 .sidebar-group-chevron {
@@ -223,14 +206,25 @@
 .sidebar-group-list {
   list-style: none;
   padding: 0;
-  margin: 0.35rem 0 0;
-  overflow: hidden;
+  margin: 0.35rem 0 0.5rem 0;
+  position: relative;
 }
 
 .sidebar-group-list li {
-  margin-bottom: 1px;
+  margin-bottom: 2px;
 }
 
 .sidebar-link-nested {
-  padding-left: 1.25rem;
+  padding-left: 0.75rem;
+}
+
+.sidebar-group-list {
+  list-style: none;
+  padding: 0;
+  margin: 0.35rem 0 0.5rem 0;
+  position: relative;
+}
+
+.sidebar-group-list li {
+  margin-bottom: 2px;
 }

package/src/client/types.ts

@@ -29,6 +29,14 @@ export interface ComponentRoute {
   locale?: string;
   /** The version this route belongs to, if versioning is configured */
   version?: string;
+  /** Optional icon to display (Lucide icon name or raw SVG) */
+  icon?: string;
+  /** The tab this route belongs to, if tabs are configured */
+  tab?: string;
+  /** Optional badge to display next to the sidebar item */
+  badge?: string | { text: string; expires?: string };
+  /** Optional icon for the route's group */
+  groupIcon?: string;
 }
 
 /**
@@ -39,6 +47,8 @@ export interface CreateBoltdocsAppOptions {
   target: string;
   /** Initial routes generated by the Vite plugin (`virtual:boltdocs-routes`) */
   routes: ComponentRoute[];
+  /** The name of the documentation directory (e.g. 'docs') */
+  docsDirName: string;
   /** Site configuration (`virtual:boltdocs-config`) */
   config: any;
   /** Dynamic import mapping from `import.meta.glob` for the documentation pages */

package/src/node/config.ts

@@ -32,7 +32,20 @@ export interface BoltdocsThemeConfig {
   /** URL path to the site logo */
   logo?: string;
   /** Items to display in the top navigation bar */
-  navbar?: Array<{ text: string; link: string }>;
+  navbar?: Array<{
+    /** Text to display (alias for text) */
+    label?: string;
+    /** Text to display */
+    text?: string;
+    /** URL path or external link (alias for link) */
+    to?: string;
+    /** URL path or external link (alias for link) */
+    href?: string;
+    /** URL path or external link */
+    link?: string;
+    /** Alignment of the item in the navbar */
+    position?: "left" | "right";
+  }>;
   /** Items to display in the sidebar, organized optionally by group URLs */
   sidebar?: Record<string, Array<{ text: string; link: string }>>;
   /** Social links to display in the navigation bar */
@@ -66,6 +79,11 @@ export interface BoltdocsThemeConfig {
     className?: string;
     style?: any;
   };
+  /**
+   * Top-level tabs for organizing documentation groups.
+   * Tab discovery uses the (tab-id) directory syntax.
+   */
+  tabs?: Array<{ id: string; text: string; icon?: string }>;
   /**
    * The syntax highlighting theme for code blocks.
    * Supports any Shiki theme name (e.g., 'github-dark', 'one-dark-pro', 'aurora-x').

package/src/node/plugin/entry.ts

@@ -1,6 +1,7 @@
 import { normalizePath } from "../utils";
 import type { BoltdocsConfig } from "../config";
 import type { BoltdocsPluginOptions } from "./types";
+import path from "path";
 
 /**
  * Generates the raw source code for the virtual entry file (`\0virtual:boltdocs-entry`).
@@ -36,6 +37,8 @@ const ${name} = _comp_${name}.default || _comp_${name}['${name}'] || _comp_${nam
     .join("\n");
   const componentMap = pluginComponents.map(([name]) => name).join(", ");
 
+  const docsDirName = path.basename(options.docsDir || "docs");
+
   return `
 import { createBoltdocsApp as _createApp } from 'boltdocs/client';
 import 'boltdocs/style.css';
@@ -48,8 +51,9 @@ ${componentImports}
 _createApp({
   target: '#root',
   routes: _routes,
+  docsDirName: '${docsDirName}',
   config: _config,
-  modules: import.meta.glob('/docs/**/*.{md,mdx}'),
+  modules: import.meta.glob('/${docsDirName}/**/*.{md,mdx}'),
   hot: import.meta.hot,
   ${homeOption}
   components: { ${componentMap} },

package/src/node/plugin/index.ts

@@ -165,7 +165,8 @@ export function boltdocsPlugin(
           ? path.resolve(viteConfig.root, viteConfig.build.outDir)
           : path.resolve(process.cwd(), "dist");
 
-        await generateStaticPages({ docsDir, outDir, config });
+        const docsDirName = path.basename(docsDir || "docs");
+        await generateStaticPages({ docsDir, docsDirName, outDir, config });
 
         const { flushCache } = await import("../cache");
         await flushCache();

package/src/node/routes/index.ts

@@ -69,13 +69,17 @@ export async function generateRoutes(
   docCache.save();
 
   // Collect group metadata from directory names and index files
-  const groupMeta = new Map<string, { title: string; position?: number }>();
+  const groupMeta = new Map<
+    string,
+    { title: string; position?: number; icon?: string }
+  >();
   for (const p of parsed) {
     if (p.relativeDir) {
       if (!groupMeta.has(p.relativeDir)) {
         groupMeta.set(p.relativeDir, {
           title: capitalize(p.relativeDir),
           position: p.inferredGroupPosition,
+          icon: p.route.icon,
         });
       } else {
         const entry = groupMeta.get(p.relativeDir)!;
@@ -85,6 +89,9 @@ export async function generateRoutes(
         ) {
           entry.position = p.inferredGroupPosition;
         }
+        if (!entry.icon && p.route.icon) {
+          entry.icon = p.route.icon;
+        }
       }
     }
 
@@ -94,6 +101,9 @@ export async function generateRoutes(
       if (p.groupMeta.position !== undefined) {
         entry.position = p.groupMeta.position;
       }
+      if (p.groupMeta.icon) {
+        entry.icon = p.groupMeta.icon;
+      }
     }
   }
 
@@ -107,6 +117,7 @@ export async function generateRoutes(
       group: dir,
       groupTitle: meta?.title || (dir ? capitalize(dir) : undefined),
       groupPosition: meta?.position,
+      groupIcon: meta?.icon,
     };
   });
 

package/src/node/routes/parser.ts

@@ -69,6 +69,16 @@ export function parseDocFile(
     }
   }
 
+  // Level 3: Check for Tab hierarchy (name)
+  let inferredTab: string | undefined;
+  if (parts.length > 0) {
+    const tabMatch = parts[0].match(/^\((.+)\)$/);
+    if (tabMatch) {
+      inferredTab = tabMatch[1].toLowerCase();
+      parts = parts.slice(1);
+    }
+  }
+
   const cleanRelativePath = parts.join("/");
 
   let cleanRoutePath: string;
@@ -118,12 +128,12 @@ export function parseDocFile(
       .trim();
     const id = slugger.slug(text);
     // Security: Sanitize heading text for XSS
-    headings.push({ level, text: escapeHtml(text), id });
+    headings.push({ level, text, id });
   }
 
-  const sanitizedTitle = data.title ? escapeHtml(data.title) : inferredTitle;
+  const sanitizedTitle = data.title ? data.title : inferredTitle;
   let sanitizedDescription = data.description
-    ? escapeHtml(data.description)
+    ? data.description
     : "";
 
   // If no description is provided, extract a summary from the content
@@ -135,10 +145,11 @@ export function parseDocFile(
       .replace(/\n+/g, " ") // Normalize whitespace
       .trim()
       .slice(0, 160);
-    sanitizedDescription = escapeHtml(summary);
+    sanitizedDescription = summary;
   }
 
-  const sanitizedBadge = data.badge ? escapeHtml(data.badge) : undefined;
+  const sanitizedBadge = data.badge ? data.badge : undefined;
+  const icon = data.icon ? String(data.icon) : undefined;
 
   return {
     route: {
@@ -152,20 +163,23 @@ export function parseDocFile(
       locale,
       version,
       badge: sanitizedBadge,
+      icon,
+      tab: inferredTab,
     },
     relativeDir: cleanDirName,
     isGroupIndex,
+    inferredTab,
     groupMeta: isGroupIndex
       ? {
-          title: escapeHtml(
+          title: 
             data.groupTitle ||
               data.title ||
               (cleanDirName ? capitalize(cleanDirName) : ""),
-          ),
           position:
             data.groupPosition ??
             data.sidebarPosition ??
             (rawDirName ? extractNumberPrefix(rawDirName) : undefined),
+          icon,
         }
       : undefined,
     inferredGroupPosition: rawDirName

package/src/node/routes/types.ts

@@ -21,6 +21,8 @@ export interface RouteMeta {
   groupTitle?: string;
   /** Optional explicit position for ordering the group itself */
   groupPosition?: number;
+  /** Optional icon for the route's group */
+  groupIcon?: string;
   /** Extracted markdown headings for search indexing */
   headings?: { level: number; text: string; id: string }[];
   /** The locale this route belongs to, if i18n is configured */
@@ -29,6 +31,10 @@ export interface RouteMeta {
   version?: string;
   /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
   badge?: string | { text: string; expires?: string };
+  /** Optional icon to display (Lucide icon name or raw SVG) */
+  icon?: string;
+  /** The tab this route belongs to, if tabs are configured */
+  tab?: string;
 }
 
 /**
@@ -43,7 +49,9 @@ export interface ParsedDocFile {
   /** Whether this file is the index file for its directory group */
   isGroupIndex: boolean;
   /** If this is a group index, any specific frontmatter metadata dictating the group's title and position */
-  groupMeta?: { title: string; position?: number };
+  groupMeta?: { title: string; position?: number; icon?: string };
   /** Extracted group position from the directory name if it has a numeric prefix */
   inferredGroupPosition?: number;
+  /** Extracted tab name from the directory name if it follows the (tab-name) syntax */
+  inferredTab?: string;
 }

package/src/node/ssg/index.ts

@@ -24,7 +24,7 @@ const _require = createRequire(import.meta.url);
  * @param options - Configuration for paths and site metadata
  */
 export async function generateStaticPages(options: SSGOptions): Promise<void> {
-  const { docsDir, outDir, config } = options;
+  const { docsDir, docsDirName, outDir, config } = options;
   const routes = await generateRoutes(docsDir, config);
   const siteTitle = config?.themeConfig?.title || "Boltdocs";
   const siteDescription = config?.themeConfig?.description || "";
@@ -64,6 +64,7 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
           path: route.path,
           routes: routes,
           config: config || {},
+          docsDirName: docsDirName,
           modules: fakeModules,
           homePage: undefined, // No custom home page for now
         });

package/src/node/ssg/options.ts

@@ -6,6 +6,8 @@ import { BoltdocsConfig } from "../config";
 export interface SSGOptions {
   /** The root directory containing markdown documentation files */
   docsDir: string;
+  /** The name of the documentation directory (e.g. 'docs') */
+  docsDirName: string;
   /** The output directory where Vite placed the compiled `index.html` and assets */
   outDir: string;
   /** Pre-resolved config (avoids re-resolving during the SSG phase) */