feat: add sidebar title option

src/bach/breadcrumbs.ts

@@ -12,6 +12,7 @@ export async function searchPagesForBreadcrumbs<TCollection extends string>(
   pages: PageItem<TCollection>[],
   prefix: { label: string; href: string }[],
   titleMap: Map<string, string>,
+  sidebarTitleMap: Map<string, string>,
   iconMap: Map<string, string>
 ): Promise<{ label: string; href: string }[] | null> {
   const normalizedTarget = normalizePagePath(pagePath)
@@ -41,11 +42,20 @@ export async function searchPagesForBreadcrumbs<TCollection extends string>(
           return groupPrefix
         }
       } else {
-        const firstChildHref = findFirstHref(buildPages(item.pages, 0, '', titleMap, new Map(), iconMap))
+        const firstChildHref = findFirstHref(
+          buildPages(item.pages, 0, '', titleMap, new Map(), sidebarTitleMap, iconMap)
+        )
         groupPrefix.push({ label: item.group, href: firstChildHref ?? '/' })
       }
 
-      const result = await searchPagesForBreadcrumbs(pagePath, item.pages, groupPrefix, titleMap, iconMap)
+      const result = await searchPagesForBreadcrumbs(
+        pagePath,
+        item.pages,
+        groupPrefix,
+        titleMap,
+        sidebarTitleMap,
+        iconMap
+      )
       if (result) return result
     }
   }
@@ -65,12 +75,13 @@ export async function buildBreadcrumbs<TCollection extends string>(
   entryId: string,
   pageTitle: string,
   titleMap: Map<string, string>,
+  sidebarTitleMap: Map<string, string>,
   iconMap: Map<string, string>
 ): Promise<{ label: string; href: string }[]> {
   const pagePath = normalizeEntryId(entryId)
 
   for (const tab of config.navigation.tabs) {
-    const crumbs = await searchPagesForBreadcrumbs(pagePath, tab.pages, [], titleMap, iconMap)
+    const crumbs = await searchPagesForBreadcrumbs(pagePath, tab.pages, [], titleMap, sidebarTitleMap, iconMap)
     if (crumbs) {
       // Remove the active page itself — breadcrumbs show only the parent path
       return crumbs.slice(0, -1)

src/bach/content.ts

@@ -55,6 +55,10 @@ export function buildSidebarEntryMap(
       entries.map((entry) => ({
         id: entry.id,
         title: entry.data.title,
+        sidebarTitle:
+          'sidebarTitle' in entry.data && typeof entry.data.sidebarTitle === 'string'
+            ? entry.data.sidebarTitle
+            : undefined,
         method: 'method' in entry.data && typeof entry.data.method === 'string' ? entry.data.method : undefined,
         icon: 'icon' in entry.data && typeof entry.data.icon === 'string' ? entry.data.icon : undefined,
         sortOrder:
@@ -75,6 +79,7 @@ export function buildSidebarEntryMap(
 export function buildCollectionsSidebarData(allEntries: Map<string, DynamicCollectionEntry[]>) {
   const titleMap = new Map<string, string>()
   const methodMap = new Map<string, string>()
+  const sidebarTitleMap = new Map<string, string>()
   const iconMap = new Map<string, string>()
   const articles: ArticleEntry[] = []
 
@@ -88,6 +93,14 @@ export function buildCollectionsSidebarData(allEntries: Map<string, DynamicColle
         methodMap.set(entry.id, method)
         methodMap.set(slug, method)
       }
+      const sidebarTitle =
+        'sidebarTitle' in entry.data && typeof entry.data.sidebarTitle === 'string'
+          ? entry.data.sidebarTitle
+          : undefined
+      if (sidebarTitle) {
+        sidebarTitleMap.set(entry.id, sidebarTitle)
+        sidebarTitleMap.set(slug, sidebarTitle)
+      }
       const icon = 'icon' in entry.data && typeof entry.data.icon === 'string' ? entry.data.icon : undefined
       if (icon) {
         iconMap.set(entry.id, icon)
@@ -101,7 +114,7 @@ export function buildCollectionsSidebarData(allEntries: Map<string, DynamicColle
     }
   }
 
-  return { titleMap, methodMap, iconMap, articles }
+  return { titleMap, methodMap, sidebarTitleMap, iconMap, articles }
 }
 
 /**

src/bach/schemas/api.ts

@@ -95,6 +95,7 @@ export const DEFAULT_API_DESCRIPTION =
 
 export const apiCollectionSchema = z.object({
   title: z.string(),
+  sidebarTitle: z.string().optional(),
   description: z.string().default(DEFAULT_API_DESCRIPTION),
   method: z.string(),
   apiSlug: z.string(),

src/bach/schemas/docs.ts

@@ -2,6 +2,7 @@ import { z } from 'astro/zod'
 
 export const docsSchema = z.object({
   title: z.string(),
+  sidebarTitle: z.string().optional(),
   description: z.string().optional(),
   icon: z.string().optional(),
   prose: z.boolean().default(true),

src/bach/site.ts

@@ -18,6 +18,7 @@ export interface SiteContext {
   sidebar: SidebarTreeResult
   titleMap: Map<string, string>
   methodMap: Map<string, string>
+  sidebarTitleMap: Map<string, string>
   iconMap: Map<string, string>
   articles: ArticleEntry[]
   defaultEntriesBySlug: Map<string, DynamicCollectionEntry>
@@ -50,9 +51,9 @@ export class BachSite<TCollection extends string = string> {
 
     const defaultCollection = getDefaultCollection(this._config)
     const allEntries = await loadCollections(this._config)
-    const { titleMap, methodMap, iconMap, articles } = buildCollectionsSidebarData(allEntries)
+    const { titleMap, methodMap, sidebarTitleMap, iconMap, articles } = buildCollectionsSidebarData(allEntries)
     const collectionsMap = buildSidebarEntryMap(allEntries)
-    const sidebar = await buildSidebarTree(this._config, titleMap, methodMap, iconMap, collectionsMap)
+    const sidebar = await buildSidebarTree(this._config, titleMap, methodMap, sidebarTitleMap, iconMap, collectionsMap)
 
     const defaultEntriesBySlug = new Map<string, DynamicCollectionEntry>()
     for (const entry of allEntries.get(defaultCollection) ?? []) {
@@ -65,6 +66,7 @@ export class BachSite<TCollection extends string = string> {
       sidebar,
       titleMap,
       methodMap,
+      sidebarTitleMap,
       iconMap,
       articles,
       defaultEntriesBySlug,
@@ -96,6 +98,7 @@ export class BachSite<TCollection extends string = string> {
         entry.id,
         title,
         siteContext.titleMap,
+        siteContext.sidebarTitleMap,
         siteContext.iconMap
       )
     }

src/bach/tree.ts

@@ -49,6 +49,7 @@ function _collectFromPages<TCollection extends string>(pages: PageItem<TCollecti
 export interface CollectionEntryData {
   id: string
   title: string
+  sidebarTitle?: string
   method?: string
   icon?: string
   sortOrder?: number
@@ -68,6 +69,7 @@ export function buildPages<TCollection extends string>(
   parentPath: string,
   titleMap: Map<string, string>,
   methodMap: Map<string, string>,
+  sidebarTitleMap: Map<string, string>,
   iconMap: Map<string, string>,
   collectionsMap?: Map<TCollection, CollectionEntryData[]>
 ): SidebarNode[] {
@@ -83,6 +85,7 @@ export function buildPages<TCollection extends string>(
       const articleNode: SidebarArticleNode = {
         type: 'article',
         title,
+        sidebarTitle: sidebarTitleMap.get(normalizedPath),
         href,
         path: normalizedPath,
         method: methodMap.get(normalizedPath),
@@ -117,6 +120,7 @@ export function buildPages<TCollection extends string>(
           children: sortedEntries.map((entry) => ({
             type: 'article',
             title: entry.title,
+            sidebarTitle: entry.sidebarTitle,
             href: `/${entry.id}`,
             path: entry.id,
             method: entry.method,
@@ -141,7 +145,16 @@ export function buildPages<TCollection extends string>(
         childrenPages = item.pages
       }
 
-      const children = buildPages(childrenPages, depth + 1, groupPath, titleMap, methodMap, iconMap, collectionsMap)
+      const children = buildPages(
+        childrenPages,
+        depth + 1,
+        groupPath,
+        titleMap,
+        methodMap,
+        sidebarTitleMap,
+        iconMap,
+        collectionsMap
+      )
 
       const categoryNode: SidebarCategoryNode = {
         type: 'category',
@@ -201,10 +214,12 @@ export async function buildSidebarTree<TCollection extends string>(
   config: DocsConfig<TCollection>,
   titleMap: Map<string, string>,
   methodMap?: Map<string, string>,
+  sidebarTitleMap?: Map<string, string>,
   iconMap?: Map<string, string>,
   collectionsMap?: Map<TCollection, CollectionEntryData[]>
 ): Promise<SidebarTreeResult> {
   const _methodMap = methodMap ?? new Map()
+  const _sidebarTitleMap = sidebarTitleMap ?? new Map()
   const _iconMap = iconMap ?? new Map()
 
   const tabs: TabInfo[] = []
@@ -213,7 +228,7 @@ export async function buildSidebarTree<TCollection extends string>(
 
   for (const tabItem of config.navigation.tabs) {
     const tabSlug = slugify(tabItem.tab)
-    const tabTree = buildPages(tabItem.pages, 0, '', titleMap, _methodMap, _iconMap, collectionsMap)
+    const tabTree = buildPages(tabItem.pages, 0, '', titleMap, _methodMap, _sidebarTitleMap, _iconMap, collectionsMap)
 
     const firstHref = findFirstHref(tabTree) ?? '/'
 

src/bach/types.ts

@@ -24,6 +24,7 @@ export interface SidebarCategoryNode {
 export interface SidebarArticleNode {
   type: 'article'
   title: string
+  sidebarTitle?: string
   href: string
   path: string
   method?: string

src/components/sidebar-tree-view.tsx

@@ -150,7 +150,7 @@ function ChildNode({
         }`}
       >
         {node.icon && <TreeIcon name={node.icon} />}
-        <span className="min-w-0 truncate">{node.title}</span>
+        <span className="min-w-0 truncate">{node.sidebarTitle ?? node.title}</span>
         {node.method && <SidebarMethodBadge method={node.method} />}
       </a>
     </li>