@levino/shipyard-docs 0.4.5 → 0.4.6

package/astro/DocsEntry.astro

@@ -29,9 +29,9 @@ export async function getStaticPaths() {
 
 // 2. For your template, you can get the entry directly from the prop
 const { entry } = Astro.props
-const { Content } = await render(entry)
+const { Content, headings } = await render(entry)
 ---
 
-<Layout>
+<Layout headings={headings}>
   <Content />
 </Layout>

package/astro/Layout.astro

@@ -2,11 +2,17 @@
 import { i18n } from 'astro:config/server'
 import { getCollection, render } from 'astro:content'
 import type { NavigationTree } from '@levino/shipyard-base'
+import { Breadcrumbs, TableOfContents } from '@levino/shipyard-base/components'
 import BaseLayout from '@levino/shipyard-base/layouts/Page.astro'
 import { Array as EffectArray, Option } from 'effect'
-import { path } from 'ramda'
 import { toSidebarEntries } from '../src/sidebarEntries'
 
+interface Props {
+  headings?: { depth: number; text: string; slug: string }[]
+}
+
+const { headings = [] } = Astro.props
+
 const getPath = (id: string) =>
   i18n ? `/${Astro.currentLocale}/docs/${id.slice(3)}` : `/docs/${id}`
 
@@ -18,9 +24,14 @@ const docs = await getCollection('docs')
         data: {
           title,
           sidebar: { render: shouldBeRendered, label },
+          sidebar_position,
+          sidebar_label,
+          sidebar_class_name,
+          sidebar_custom_props,
         },
       } = doc
       return {
+        id,
         path: getPath(id),
         title:
           label ??
@@ -33,20 +44,36 @@ const docs = await getCollection('docs')
           )?.text ??
           id,
         link: shouldBeRendered,
+        sidebarPosition: sidebar_position,
+        sidebarLabel: sidebar_label,
+        sidebarClassName: sidebar_class_name,
+        sidebarCustomProps: sidebar_custom_props,
       }
     }),
   )
   .then((promises) => Promise.all(promises))
 
-const entries = path(
-  i18n
-    ? [Astro.currentLocale, 'subEntry', 'docs', 'subEntry']
-    : ['docs', 'subEntry'],
-)(toSidebarEntries(docs)) as NavigationTree
+const fullTree = toSidebarEntries(docs)
+
+const entries: NavigationTree =
+  i18n && Astro.currentLocale
+    ? (fullTree[Astro.currentLocale]?.subEntry ?? {})
+    : fullTree
 ---
 
 <BaseLayout sidebarNavigation={entries}>
-  <div class="prose mx-auto">
-    <slot />
+  <div class="grid grid-cols-12 gap-6 max-w-7xl mx-auto">
+    <div class="col-span-12 xl:col-span-9">
+      <div class="prose max-w-none">
+        <Breadcrumbs navigation={entries} />
+        <TableOfContents links={headings} class="xl:hidden" />
+        <slot />
+      </div>
+    </div>
+    <div class="hidden xl:block col-span-3">
+      <div class="sticky top-20 max-h-[calc(100vh-6rem)] overflow-y-auto">
+        <TableOfContents links={headings} desktopOnly />
+      </div>
+    </div>
   </div>
 </BaseLayout>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-docs",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "",
   "type": "module",
   "main": "src/index.ts",
@@ -13,7 +13,7 @@
   "dependencies": {
     "effect": "^3.12.5",
     "ramda": "^0.31",
-    "@levino/shipyard-base": "^0.5.6"
+    "@levino/shipyard-base": "^0.5.8"
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.16",

package/src/index.ts

@@ -11,6 +11,9 @@ export const docsSchema = z.object({
     .default({ render: true }),
   title: z.string().optional(),
   description: z.string().optional(),
+  sidebar_position: z.number().optional(),
+  sidebar_label: z.string().optional(),
+  sidebar_class_name: z.string().optional(),
 })
 
 export default (): AstroIntegration => ({

package/src/sidebarEntries.test.ts

@@ -1,205 +1,173 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, it } from 'vitest'
+import type { DocsData } from './sidebarEntries'
 import { toSidebarEntries } from './sidebarEntries'
 
-describe('Sidebar subEntry helpers', () => {
-  test.each([
-    [
-      [
-        {
-          title: 'foo',
-          path: '/foo',
-        },
-      ],
+describe('toSidebarEntries', () => {
+  it('should create a basic sidebar structure from flat docs', () => {
+    const docs: DocsData[] = [
       {
-        foo: {
-          label: 'foo',
-          href: '/foo',
-        },
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
       },
-    ],
-    [
-      [
-        {
-          title: 'foo',
-          path: '/foo',
-        },
-        {
-          title: 'bar',
-          path: '/bar',
-        },
-      ],
       {
-        foo: {
-          label: 'foo',
-          href: '/foo',
-        },
-        bar: {
-          label: 'bar',
-          href: '/bar',
-        },
+        id: 'guide/advanced/topic.md',
+        title: 'Topic',
+        path: '/docs/guide/advanced/topic',
       },
-    ],
-    [
-      [
-        {
-          title: 'foo baz',
-          path: '/baz/foo',
-        },
-        {
-          title: 'bar baz',
-          path: '/baz/bar',
-        },
-      ],
-      {
-        baz: {
-          subEntry: {
-            foo: {
-              label: 'foo baz',
-              href: '/baz/foo',
-            },
-            bar: {
-              label: 'bar baz',
-              href: '/baz/bar',
+      { id: 'api.md', title: 'API', path: '/docs/api' },
+    ]
+
+    const entries = toSidebarEntries(docs)
+
+    expect(entries).toMatchObject({
+      guide: {
+        label: 'guide',
+        subEntry: {
+          intro: { label: 'Introduction', href: '/docs/guide/intro' },
+          advanced: {
+            label: 'advanced',
+            subEntry: {
+              topic: { label: 'Topic', href: '/docs/guide/advanced/topic' },
             },
           },
         },
       },
-    ],
-    [
-      [
-        {
-          title: 'foo',
-          path: '/foo',
-        },
-        {
-          title: 'bar',
-          path: '/bar',
-        },
-        {
-          title: 'foo baz',
-          path: '/baz/foo',
-        },
-        {
-          title: 'bar baz',
-          path: '/baz/bar',
-        },
-      ],
+      api: { label: 'API', href: '/docs/api' },
+    })
+  })
+
+  it('should respect sidebar_label', () => {
+    const docs: DocsData[] = [
       {
-        foo: {
-          label: 'foo',
-          href: '/foo',
-        },
-        bar: {
-          label: 'bar',
-          href: '/bar',
-        },
-        baz: {
-          subEntry: {
-            foo: {
-              label: 'foo baz',
-              href: '/baz/foo',
-            },
-            bar: {
-              label: 'bar baz',
-              href: '/baz/bar',
-            },
-          },
-        },
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
+        sidebarLabel: 'Intro',
       },
-    ],
-    [
-      [
-        {
-          title: 'foo',
-          path: '/foo',
-        },
-        {
-          title: 'bar',
-          path: '/bar',
-        },
-        { title: 'baz', path: '/baz' },
-        {
-          title: 'foo baz',
-          path: '/baz/foo',
-        },
-        {
-          title: 'bar baz',
-          path: '/baz/bar',
-        },
-      ],
+    ]
+
+    const entries = toSidebarEntries(docs)
+    expect(entries.guide.subEntry?.intro.label).toBe('Intro')
+  })
+
+  it('should respect sidebar_position', () => {
+    const docs: DocsData[] = [
       {
-        foo: {
-          label: 'foo',
-          href: '/foo',
-        },
-        bar: {
-          label: 'bar',
-          href: '/bar',
-        },
-        baz: {
-          label: 'baz',
-          href: '/baz',
-          subEntry: {
-            foo: {
-              label: 'foo baz',
-              href: '/baz/foo',
-            },
-            bar: {
-              label: 'bar baz',
-              href: '/baz/bar',
-            },
-          },
-        },
+        id: 'guide/b.md',
+        title: 'B',
+        path: '/docs/guide/b',
+        sidebarPosition: 2,
       },
-    ],
-    [
-      [
-        {
-          title: 'foo',
-          path: '/foo',
-        },
-        {
-          title: 'bar',
-          path: '/bar',
-        },
-        { title: 'baz', path: '/baz', link: false },
-        {
-          title: 'foo baz',
-          path: '/baz/foo',
-        },
-        {
-          title: 'bar baz',
-          path: '/baz/bar',
-        },
-      ],
       {
-        foo: {
-          label: 'foo',
-          href: '/foo',
-        },
-        bar: {
-          label: 'bar',
-          href: '/bar',
-        },
-        baz: {
-          label: 'baz',
-          subEntry: {
-            foo: {
-              label: 'foo baz',
-              href: '/baz/foo',
-            },
-            bar: {
-              label: 'bar baz',
-              href: '/baz/bar',
-            },
-          },
-        },
+        id: 'guide/a.md',
+        title: 'A',
+        path: '/docs/guide/a',
+        sidebarPosition: 1,
+      },
+      {
+        id: 'guide/c.md',
+        title: 'C',
+        path: '/docs/guide/c',
       },
-    ],
-  ])(
-    'transforms a list of doc sites into a list of sidebar subEntry',
-    (input, expected) => {
-      expect(toSidebarEntries(input)).toEqual(expected)
-    },
-  )
+    ]
+
+    const entries = toSidebarEntries(docs)
+    const guideSub = entries.guide.subEntry
+    const keys = Object.keys(guideSub || {})
+
+    // Items with explicit positions come first (1, 2), then items without position (Infinity) are sorted alphabetically
+    expect(keys).toEqual(['a', 'b', 'c'])
+  })
+
+  it('should apply sidebar_class_name', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'page.md',
+        title: 'Page',
+        path: '/docs/page',
+        sidebarClassName: 'special-page',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+    expect(entries.page.className).toBe('special-page')
+  })
+
+  it('should handle index files correctly', () => {
+    const docs: DocsData[] = [
+      { id: 'guide/index.md', title: 'Guide Index', path: '/docs/guide' },
+      { id: 'guide/other.md', title: 'Other', path: '/docs/guide/other' },
+    ]
+
+    const entries = toSidebarEntries(docs)
+    expect(entries.guide.href).toBe('/docs/guide')
+    expect(entries.guide.label).toBe('Guide Index')
+    expect(entries.guide.subEntry).toBeDefined()
+    expect(entries.guide.subEntry?.other).toBeDefined()
+  })
+
+  it('should sort alphabetically when positions match', () => {
+    const docs: DocsData[] = [
+      { id: 'z.md', title: 'Zebra', path: '/z' },
+      { id: 'a.md', title: 'Apple', path: '/a' },
+    ]
+    const entries = toSidebarEntries(docs)
+    const keys = Object.keys(entries)
+    expect(keys).toEqual(['a', 'z'])
+  })
+
+  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
+      {
+        id: 'zebra/index.md',
+        title: 'Zebra Section',
+        path: '/docs/zebra',
+        sidebarPosition: 1,
+      },
+      { id: 'zebra/page.md', title: 'Zebra Page', path: '/docs/zebra/page' },
+      // "apple" folder with no explicit position (defaults to Infinity)
+      {
+        id: 'apple/index.md',
+        title: 'Apple Section',
+        path: '/docs/apple',
+      },
+      { id: 'apple/page.md', title: 'Apple Page', path: '/docs/apple/page' },
+    ]
+
+    const entries = toSidebarEntries(docs)
+    const keys = Object.keys(entries)
+
+    // zebra has explicit position 1, apple defaults to Infinity
+    // So zebra (position 1) comes before apple (Infinity)
+    expect(keys).toEqual(['zebra', 'apple'])
+  })
+
+  it('should position category first when index.md has explicit sidebar_position', () => {
+    const docs: DocsData[] = [
+      // A category with index.md having sidebar_position: 0
+      {
+        id: 'sidebar-demo/index.md',
+        title: 'Sidebar Demo',
+        path: '/docs/sidebar-demo',
+        sidebarPosition: 0,
+      },
+      {
+        id: 'sidebar-demo/custom-class.md',
+        title: 'Custom Class',
+        path: '/docs/sidebar-demo/custom-class',
+      },
+      // Other top-level items with no position (default Infinity)
+      { id: 'garden-beds.md', title: 'Garden Beds', path: '/docs/garden-beds' },
+      { id: 'harvesting.md', title: 'Harvesting', path: '/docs/harvesting' },
+    ]
+
+    const entries = toSidebarEntries(docs)
+    const keys = Object.keys(entries)
+
+    // sidebar-demo has explicit position 0, others default to Infinity
+    // So sidebar-demo comes first, then others alphabetically
+    expect(keys).toEqual(['sidebar-demo', 'garden-beds', 'harvesting'])
+  })
 })

package/src/sidebarEntries.ts

@@ -1,32 +1,120 @@
 import type { Entry } from '@levino/shipyard-base'
-import { mergeDeepLeft } from 'ramda'
 
-interface DocsData {
+export interface DocsData {
+  id: string
   title: string
   path: string
   link?: boolean
+  sidebarPosition?: number
+  sidebarLabel?: string
+  sidebarClassName?: string
 }
 
-export const toSidebarEntries = (docs: DocsData[]): Entry =>
-  docs.reduce((acc, { path, title, link = true }) => {
-    const newObject = path
-      .split('/')
-      .slice(1)
-      .reverse()
-      .reduce((acc, node, index): Entry => {
-        if (index === 0) {
-          return {
-            [node]: {
-              label: title,
-              ...(link ? { href: `${path}` } : {}),
-            },
-          }
-        }
-        return {
-          [node]: {
-            subEntry: acc,
-          },
-        }
-      }, {} as Entry)
-    return mergeDeepLeft(acc, newObject)
-  }, {} as Entry)
+interface TreeNode {
+  readonly key: string
+  readonly label: string
+  readonly href?: string
+  readonly position: number
+  readonly className?: string
+  readonly children: Readonly<Record<string, TreeNode>>
+}
+
+const DEFAULT_POSITION = Number.POSITIVE_INFINITY
+
+const createLeafNode = (key: string, doc: DocsData): TreeNode => ({
+  key,
+  label: doc.sidebarLabel ?? doc.title ?? key,
+  href: doc.link !== false ? doc.path : undefined,
+  position: doc.sidebarPosition ?? DEFAULT_POSITION,
+  className: doc.sidebarClassName,
+  children: {},
+})
+
+const createBranchNode = (key: string): TreeNode => ({
+  key,
+  label: key,
+  position: DEFAULT_POSITION,
+  children: {},
+})
+
+const mergeNodeWithDoc = (node: TreeNode, doc: DocsData): TreeNode => ({
+  ...node,
+  label: doc.sidebarLabel ?? doc.title ?? node.label,
+  href: doc.link !== false ? doc.path : node.href,
+  position: doc.sidebarPosition ?? node.position,
+  className: doc.sidebarClassName ?? node.className,
+})
+
+const insertAtPath = (
+  root: Readonly<Record<string, TreeNode>>,
+  pathParts: readonly string[],
+  doc: DocsData,
+): Readonly<Record<string, TreeNode>> => {
+  if (pathParts.length === 0) return root
+
+  const [head, ...tail] = pathParts
+  const existingNode = root[head]
+
+  if (tail.length === 0) {
+    const newNode = existingNode
+      ? mergeNodeWithDoc(existingNode, doc)
+      : createLeafNode(head, doc)
+    return { ...root, [head]: newNode }
+  }
+
+  const currentNode = existingNode ?? createBranchNode(head)
+  const updatedChildren = insertAtPath(currentNode.children, tail, doc)
+
+  return {
+    ...root,
+    [head]: { ...currentNode, children: updatedChildren },
+  }
+}
+
+const sortByPositionThenLabel = (
+  nodes: readonly TreeNode[],
+): readonly TreeNode[] =>
+  [...nodes].sort((a, b) =>
+    a.position !== b.position
+      ? a.position - b.position
+      : a.label.localeCompare(b.label),
+  )
+
+const treeNodeToEntry = (node: TreeNode): Entry[string] => {
+  const childNodes = Object.values(node.children)
+  const sortedChildren = sortByPositionThenLabel(childNodes)
+
+  const subEntry =
+    sortedChildren.length > 0
+      ? Object.fromEntries(
+          sortedChildren.map((child) => [child.key, treeNodeToEntry(child)]),
+        )
+      : undefined
+
+  return {
+    label: node.label,
+    ...(node.href && { href: node.href }),
+    ...(node.className && { className: node.className }),
+    ...(subEntry && { subEntry }),
+  }
+}
+
+const parseDocPath = (id: string): readonly string[] => {
+  const cleanId = id.replace(/\.[^/.]+$/, '')
+  const parts = cleanId.split('/')
+  const filename = parts[parts.length - 1]
+  return filename === 'index' ? parts.slice(0, -1) : parts
+}
+
+export const toSidebarEntries = (docs: readonly DocsData[]): Entry => {
+  const rootTree = docs.reduce<Readonly<Record<string, TreeNode>>>(
+    (acc, doc) => insertAtPath(acc, parseDocPath(doc.id), doc),
+    {},
+  )
+
+  const sortedNodes = sortByPositionThenLabel(Object.values(rootTree))
+
+  return Object.fromEntries(
+    sortedNodes.map((node) => [node.key, treeNodeToEntry(node)]),
+  )
+}