@levino/shipyard-docs 0.5.2 → 0.6.0-rc-20260106213612

package/src/sidebarEntries.test.ts

@@ -37,7 +37,7 @@ describe('toSidebarEntries', () => {
     })
   })
 
-  it('should respect sidebar_label', () => {
+  it('should respect sidebar.label', () => {
     const docs: DocsData[] = [
       {
         id: 'guide/intro.md',
@@ -51,7 +51,7 @@ describe('toSidebarEntries', () => {
     expect(entries.guide.subEntry?.intro.label).toBe('Intro')
   })
 
-  it('should respect sidebar_position', () => {
+  it('should respect sidebar.position', () => {
     const docs: DocsData[] = [
       {
         id: 'guide/b.md',
@@ -80,7 +80,7 @@ describe('toSidebarEntries', () => {
     expect(keys).toEqual(['a', 'b', 'c'])
   })
 
-  it('should apply sidebar_class_name', () => {
+  it('should apply sidebar.className', () => {
     const docs: DocsData[] = [
       {
         id: 'page.md',
@@ -117,9 +117,9 @@ describe('toSidebarEntries', () => {
     expect(keys).toEqual(['a', 'z'])
   })
 
-  it('should apply index.md sidebar_position to parent category for top-level sorting', () => {
+  it('should apply index.md sidebar.position to parent category for top-level sorting', () => {
     const docs: DocsData[] = [
-      // "zebra" folder with index.md that has sidebar_position: 1
+      // "zebra" folder with index.md that has sidebar.position: 1
       {
         id: 'zebra/index.md',
         title: 'Zebra Section',
@@ -144,9 +144,9 @@ describe('toSidebarEntries', () => {
     expect(keys).toEqual(['zebra', 'apple'])
   })
 
-  it('should position category first when index.md has explicit sidebar_position', () => {
+  it('should position category first when index.md has explicit sidebar.position', () => {
     const docs: DocsData[] = [
-      // A category with index.md having sidebar_position: 0
+      // A category with index.md having sidebar.position: 0
       {
         id: 'sidebar-demo/index.md',
         title: 'Sidebar Demo',
@@ -170,4 +170,142 @@ describe('toSidebarEntries', () => {
     // So sidebar-demo comes first, then others alphabetically
     expect(keys).toEqual(['sidebar-demo', 'garden-beds', 'harvesting'])
   })
+
+  it('should include collapsible/collapsed in category entries', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'guide/index.md',
+        title: 'Guide',
+        path: '/docs/guide',
+        collapsible: true,
+        collapsed: false,
+      },
+      {
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+
+    expect(entries.guide.collapsible).toBe(true)
+    expect(entries.guide.collapsed).toBe(false)
+  })
+
+  it('should apply default collapsible/collapsed values when not specified', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'guide/index.md',
+        title: 'Guide',
+        path: '/docs/guide',
+      },
+      {
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+
+    // Default values: collapsible: true, collapsed: true
+    expect(entries.guide.collapsible).toBe(true)
+    expect(entries.guide.collapsed).toBe(true)
+  })
+
+  it('should filter unlisted pages from sidebar', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
+      },
+      {
+        id: 'guide/hidden.md',
+        title: 'Hidden Page',
+        path: '/docs/guide/hidden',
+        unlisted: true,
+      },
+      {
+        id: 'guide/visible.md',
+        title: 'Visible Page',
+        path: '/docs/guide/visible',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+    const guideSubKeys = Object.keys(entries.guide.subEntry || {})
+
+    // hidden should not be in the sidebar
+    expect(guideSubKeys).toContain('intro')
+    expect(guideSubKeys).toContain('visible')
+    expect(guideSubKeys).not.toContain('hidden')
+  })
+
+  it('should create non-clickable entries for render: false (no href)', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'guide/index.md',
+        title: 'Guide',
+        path: '/docs/guide',
+        link: false, // render: false translates to link: false
+      },
+      {
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+
+    // Category should exist but not have an href
+    expect(entries.guide.label).toBe('Guide')
+    expect(entries.guide.href).toBeUndefined()
+    expect(entries.guide.subEntry?.intro.href).toBe('/docs/guide/intro')
+  })
+
+  it('should apply index.md metadata including collapsible state to parent category', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'advanced/index.md',
+        title: 'Advanced Topics',
+        path: '/docs/advanced',
+        sidebarLabel: 'Advanced',
+        sidebarPosition: 5,
+        sidebarClassName: 'advanced-section',
+        collapsible: false,
+        collapsed: false,
+      },
+      {
+        id: 'advanced/topic1.md',
+        title: 'Topic 1',
+        path: '/docs/advanced/topic1',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+
+    expect(entries.advanced.label).toBe('Advanced')
+    expect(entries.advanced.className).toBe('advanced-section')
+    expect(entries.advanced.collapsible).toBe(false)
+    expect(entries.advanced.collapsed).toBe(false)
+  })
+
+  it('should not include collapsible/collapsed for leaf nodes', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'page.md',
+        title: 'Page',
+        path: '/docs/page',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+
+    // Leaf nodes should not have collapsible/collapsed properties
+    expect(entries.page.collapsible).toBeUndefined()
+    expect(entries.page.collapsed).toBeUndefined()
+  })
 })

package/src/sidebarEntries.ts

@@ -2,14 +2,21 @@ import type { Entry } from '@levino/shipyard-base'
 
 export interface DocsData {
   id: string
+  /** Custom document ID from frontmatter (for referencing in pagination) */
+  customId?: string
   title: string
   path: string
   link?: boolean
   sidebarPosition?: number
   sidebarLabel?: string
   sidebarClassName?: string
-  pagination_next?: string | null
-  pagination_prev?: string | null
+  sidebarCustomProps?: Record<string, unknown>
+  collapsible?: boolean
+  collapsed?: boolean
+  unlisted?: boolean
+  paginationLabel?: string
+  paginationNext?: string | null
+  paginationPrev?: string | null
 }
 
 interface TreeNode {
@@ -18,6 +25,9 @@ interface TreeNode {
   readonly href?: string
   readonly position: number
   readonly className?: string
+  readonly customProps?: Record<string, unknown>
+  readonly collapsible: boolean
+  readonly collapsed: boolean
   readonly children: Readonly<Record<string, TreeNode>>
 }
 
@@ -29,6 +39,9 @@ const createLeafNode = (key: string, doc: DocsData): TreeNode => ({
   href: doc.link !== false ? doc.path : undefined,
   position: doc.sidebarPosition ?? DEFAULT_POSITION,
   className: doc.sidebarClassName,
+  customProps: doc.sidebarCustomProps,
+  collapsible: doc.collapsible ?? true,
+  collapsed: doc.collapsed ?? true,
   children: {},
 })
 
@@ -36,6 +49,8 @@ const createBranchNode = (key: string): TreeNode => ({
   key,
   label: key,
   position: DEFAULT_POSITION,
+  collapsible: true,
+  collapsed: true,
   children: {},
 })
 
@@ -45,6 +60,9 @@ const mergeNodeWithDoc = (node: TreeNode, doc: DocsData): TreeNode => ({
   href: doc.link !== false ? doc.path : node.href,
   position: doc.sidebarPosition ?? node.position,
   className: doc.sidebarClassName ?? node.className,
+  customProps: doc.sidebarCustomProps ?? node.customProps,
+  collapsible: doc.collapsible ?? node.collapsible,
+  collapsed: doc.collapsed ?? node.collapsed,
 })
 
 const insertAtPath = (
@@ -93,11 +111,17 @@ const treeNodeToEntry = (node: TreeNode): Entry[string] => {
         )
       : undefined
 
+  // Only include collapsible/collapsed for nodes with children (category nodes)
+  const hasChildren = sortedChildren.length > 0
+
   return {
     label: node.label,
     ...(node.href && { href: node.href }),
     ...(node.className && { className: node.className }),
+    ...(node.customProps && { customProps: node.customProps }),
     ...(subEntry && { subEntry }),
+    ...(hasChildren && { collapsible: node.collapsible }),
+    ...(hasChildren && { collapsed: node.collapsed }),
   }
 }
 
@@ -109,7 +133,10 @@ const parseDocPath = (id: string): readonly string[] => {
 }
 
 export const toSidebarEntries = (docs: readonly DocsData[]): Entry => {
-  const rootTree = docs.reduce<Readonly<Record<string, TreeNode>>>(
+  // Filter out unlisted pages from the sidebar
+  const visibleDocs = docs.filter((doc) => !doc.unlisted)
+
+  const rootTree = visibleDocs.reduce<Readonly<Record<string, TreeNode>>>(
     (acc, doc) => insertAtPath(acc, parseDocPath(doc.id), doc),
     {},
   )