@levino/shipyard-docs 0.0.0-rc-20251122114952

package/astro/DocsEntry.astro

@@ -0,0 +1,37 @@
+---
+import { i18n } from 'astro:config/server'
+import { getCollection, render } from 'astro:content'
+import Layout from './Layout.astro'
+
+export async function getStaticPaths() {
+  const docs = await getCollection('docs')
+
+  const getParams = (slug: string) => {
+    if (i18n) {
+      const [locale, ...rest] = slug.split('/')
+      return {
+        slug: rest.length ? rest.join('/') : undefined,
+        locale,
+      }
+    } else {
+      // For non-i18n, treat the entire slug as the path
+      return {
+        slug: slug || undefined,
+      }
+    }
+  }
+
+  return docs.map((entry) => ({
+    params: getParams(entry.id),
+    props: { entry },
+  }))
+}
+
+// 2. For your template, you can get the entry directly from the prop
+const { entry } = Astro.props
+const { Content, headings } = await render(entry)
+---
+
+<Layout headings={headings}>
+  <Content />
+</Layout>

package/astro/Layout.astro

@@ -0,0 +1,79 @@
+---
+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 { 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}`
+
+const docs = await getCollection('docs')
+  .then(
+    EffectArray.map(async (doc) => {
+      const {
+        id,
+        data: {
+          title,
+          sidebar: { render: shouldBeRendered, label },
+          sidebar_position,
+          sidebar_label,
+          sidebar_class_name,
+          sidebar_custom_props,
+        },
+      } = doc
+      return {
+        id,
+        path: getPath(id),
+        title:
+          label ??
+          title ??
+          Option.getOrUndefined(
+            EffectArray.findFirst(
+              (await render(doc)).headings,
+              ({ depth }) => depth === 1,
+            ),
+          )?.text ??
+          id,
+        link: shouldBeRendered,
+        sidebarPosition: sidebar_position,
+        sidebarLabel: sidebar_label,
+        sidebarClassName: sidebar_class_name,
+        sidebarCustomProps: sidebar_custom_props,
+      }
+    }),
+  )
+  .then((promises) => Promise.all(promises))
+
+const fullTree = toSidebarEntries(docs)
+
+const entries: NavigationTree =
+  i18n && Astro.currentLocale
+    ? (fullTree[Astro.currentLocale]?.subEntry ?? {})
+    : fullTree
+---
+
+<BaseLayout sidebarNavigation={entries}>
+  <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/astro/index.ts

@@ -0,0 +1 @@
+export { default as DocsEntry } from './DocsEntry.astro'

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@levino/shipyard-docs",
+  "version": "0.0.0-rc-20251122114952",
+  "description": "",
+  "type": "module",
+  "main": "src/index.ts",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "peerDependencies": {
+    "astro": "^5.7"
+  },
+  "dependencies": {
+    "effect": "^3.12.5",
+    "ramda": "^0.31",
+    "@levino/shipyard-base": "0.0.0-rc-20251122114952"
+  },
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.16",
+    "@types/ramda": "^0.31",
+    "astro": "^5.7",
+    "vitest": "^2.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/levino/shipyard"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./layout": "./astro/Layout.astro",
+    "./astro": "./astro/index.ts",
+    "./astro/*": "./astro/*"
+  },
+  "files": [
+    "astro",
+    "src"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+import type { AstroIntegration } from 'astro'
+
+import { z } from 'astro/zod'
+
+export const docsSchema = z.object({
+  sidebar: z
+    .object({
+      render: z.boolean().default(true),
+      label: z.string().optional(),
+    })
+    .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 => ({
+  name: 'shipyard-docs',
+  hooks: {
+    'astro:config:setup': ({ injectRoute, config }) => {
+      if (config.i18n) {
+        // With i18n: use locale prefix
+        injectRoute({
+          pattern: `/[locale]/docs/[...slug]`,
+          entrypoint: `@levino/shipyard-docs/astro/DocsEntry.astro`,
+        })
+      } else {
+        // Without i18n: direct path
+        injectRoute({
+          pattern: `/docs/[...slug]`,
+          entrypoint: `@levino/shipyard-docs/astro/DocsEntry.astro`,
+        })
+      }
+    },
+  },
+})

package/src/sidebarEntries.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest'
+import type { DocsData } from './sidebarEntries'
+import { toSidebarEntries } from './sidebarEntries'
+
+describe('toSidebarEntries', () => {
+  it('should create a basic sidebar structure from flat docs', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
+      },
+      {
+        id: 'guide/advanced/topic.md',
+        title: 'Topic',
+        path: '/docs/guide/advanced/topic',
+      },
+      { 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' },
+            },
+          },
+        },
+      },
+      api: { label: 'API', href: '/docs/api' },
+    })
+  })
+
+  it('should respect sidebar_label', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'guide/intro.md',
+        title: 'Introduction',
+        path: '/docs/guide/intro',
+        sidebarLabel: 'Intro',
+      },
+    ]
+
+    const entries = toSidebarEntries(docs)
+    expect(entries.guide.subEntry?.intro.label).toBe('Intro')
+  })
+
+  it('should respect sidebar_position', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'guide/b.md',
+        title: 'B',
+        path: '/docs/guide/b',
+        sidebarPosition: 2,
+      },
+      {
+        id: 'guide/a.md',
+        title: 'A',
+        path: '/docs/guide/a',
+        sidebarPosition: 1,
+      },
+      {
+        id: 'guide/c.md',
+        title: 'C',
+        path: '/docs/guide/c',
+      },
+    ]
+
+    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

@@ -0,0 +1,120 @@
+import type { Entry } from '@levino/shipyard-base'
+
+export interface DocsData {
+  id: string
+  title: string
+  path: string
+  link?: boolean
+  sidebarPosition?: number
+  sidebarLabel?: string
+  sidebarClassName?: string
+}
+
+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)]),
+  )
+}