@levino/shipyard-docs 0.4.6 → 0.4.7-rc-20251123141510

package/astro/Layout.astro

@@ -5,53 +5,73 @@ 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 type { DocsData } from '../src/sidebarEntries'
 import { toSidebarEntries } from '../src/sidebarEntries'
 
 interface Props {
   headings?: { depth: number; text: string; slug: string }[]
+  /**
+   * The base path for generating doc URLs.
+   * @default 'docs'
+   */
+  routeBasePath?: string
+  /**
+   * Pre-computed docs data for the sidebar. If provided, this will be used
+   * instead of fetching from the default 'docs' collection.
+   * Use this when you have multiple docs instances with different collections.
+   */
+  docsData?: DocsData[]
 }
 
-const { headings = [] } = Astro.props
+const { headings = [], routeBasePath = 'docs', docsData } = Astro.props
+
+// Normalize the route base path
+const normalizedBasePath = routeBasePath.replace(/^\/+|\/+$/g, '')
 
 const getPath = (id: string) =>
-  i18n ? `/${Astro.currentLocale}/docs/${id.slice(3)}` : `/docs/${id}`
+  i18n
+    ? `/${Astro.currentLocale}/${normalizedBasePath}/${id.slice(3)}`
+    : `/${normalizedBasePath}/${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 ??
+// Use provided docsData or fetch from the default 'docs' collection
+const docs =
+  docsData ??
+  (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,
-        link: shouldBeRendered,
-        sidebarPosition: sidebar_position,
-        sidebarLabel: sidebar_label,
-        sidebarClassName: sidebar_class_name,
-        sidebarCustomProps: sidebar_custom_props,
-      }
-    }),
-  )
-  .then((promises) => Promise.all(promises))
+          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)
 

package/astro/index.ts

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

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@levino/shipyard-docs",
-  "version": "0.4.6",
+  "version": "0.4.7-rc-20251123141510",
   "description": "",
   "type": "module",
   "main": "src/index.ts",
+  "scripts": {
+    "test:unit": "vitest run"
+  },
   "keywords": [],
   "author": "",
   "license": "ISC",

package/src/index.ts

@@ -1,7 +1,14 @@
 import type { AstroIntegration } from 'astro'
-
+import { glob } from 'astro/loaders'
 import { z } from 'astro/zod'
 
+export type { DocsRouteConfig } from './routeHelpers'
+// Re-export route helpers
+export { getDocPath, getRouteParams } from './routeHelpers'
+// Re-export types and utilities from sidebarEntries
+export type { DocsData } from './sidebarEntries'
+export { toSidebarEntries } from './sidebarEntries'
+
 export const docsSchema = z.object({
   sidebar: z
     .object({
@@ -16,23 +23,98 @@ export const docsSchema = z.object({
   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`,
-        })
-      }
-    },
-  },
+/**
+ * Configuration for a docs instance.
+ */
+export interface DocsConfig {
+  /**
+   * The base path where docs routes will be mounted.
+   * @default 'docs'
+   * @example 'guides' will mount docs at /guides/[...slug]
+   */
+  routeBasePath?: string
+}
+
+/**
+ * Helper function to create a docs content collection configuration.
+ * Use this in your content.config.ts to define docs collections.
+ *
+ * @param basePath - The base directory path where markdown files are located (relative to project root)
+ * @param pattern - Optional glob pattern to match files (defaults to '**\/*.md')
+ * @returns A loader and schema configuration for use with defineCollection
+ *
+ * @example
+ * ```ts
+ * import { defineCollection } from 'astro:content'
+ * import { createDocsCollection } from '@levino/shipyard-docs'
+ *
+ * const docs = defineCollection(createDocsCollection('./docs'))
+ * const guides = defineCollection(createDocsCollection('./guides'))
+ *
+ * export const collections = { docs, guides }
+ * ```
+ */
+export const createDocsCollection = (
+  basePath: string,
+  pattern: string = '**/*.md',
+) => ({
+  schema: docsSchema,
+  loader: glob({ pattern, base: basePath }),
 })
+
+/**
+ * Shipyard Docs integration for Astro.
+ *
+ * Supports multiple documentation instances with configurable route mounting.
+ *
+ * @param config - Optional configuration for the docs instance
+ * @returns An Astro integration
+ *
+ * @example
+ * ```ts
+ * // Single docs instance (default)
+ * shipyardDocs()
+ *
+ * // Custom route path
+ * shipyardDocs({ routeBasePath: 'guides' })
+ *
+ * // Multiple docs instances (requires custom route files - see documentation)
+ * shipyardDocs({ routeBasePath: 'docs' })
+ * shipyardDocs({ routeBasePath: 'guides' })
+ * ```
+ */
+export default (config: DocsConfig = {}): AstroIntegration => {
+  const { routeBasePath = 'docs' } = config
+
+  // Normalize the route base path (remove leading/trailing slashes safely)
+  let normalizedBasePath = routeBasePath
+  while (normalizedBasePath.startsWith('/')) {
+    normalizedBasePath = normalizedBasePath.slice(1)
+  }
+  while (normalizedBasePath.endsWith('/')) {
+    normalizedBasePath = normalizedBasePath.slice(0, -1)
+  }
+
+  return {
+    name: `shipyard-docs${normalizedBasePath !== 'docs' ? `-${normalizedBasePath}` : ''}`,
+    hooks: {
+      'astro:config:setup': ({ injectRoute, config: astroConfig }) => {
+        if (astroConfig.i18n) {
+          // With i18n: use locale prefix
+          injectRoute({
+            pattern: `/[locale]/${normalizedBasePath}/[...slug]`,
+            entrypoint: `@levino/shipyard-docs/astro/DocsEntry.astro`,
+            prerender: true,
+          })
+        } else {
+          // Without i18n: direct path
+          injectRoute({
+            pattern: `/${normalizedBasePath}/[...slug]`,
+            entrypoint: `@levino/shipyard-docs/astro/DocsEntry.astro`,
+            prerender: true,
+          })
+        }
+      },
+    },
+  }
+}

package/src/routeHelpers.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+import { getDocPath, getRouteParams } from './routeHelpers'
+
+describe('getRouteParams', () => {
+  describe('without i18n', () => {
+    it('should return slug from simple path', () => {
+      const params = getRouteParams('getting-started', false)
+      expect(params).toEqual({ slug: 'getting-started' })
+    })
+
+    it('should return slug from nested path', () => {
+      const params = getRouteParams('guides/advanced/topic', false)
+      expect(params).toEqual({ slug: 'guides/advanced/topic' })
+    })
+
+    it('should return undefined slug for empty path', () => {
+      const params = getRouteParams('', false)
+      expect(params).toEqual({ slug: undefined })
+    })
+  })
+
+  describe('with i18n', () => {
+    it('should extract locale and slug from path', () => {
+      const params = getRouteParams('en/getting-started', true)
+      expect(params).toEqual({ locale: 'en', slug: 'getting-started' })
+    })
+
+    it('should extract locale and nested slug', () => {
+      const params = getRouteParams('de/guides/advanced/topic', true)
+      expect(params).toEqual({ locale: 'de', slug: 'guides/advanced/topic' })
+    })
+
+    it('should handle locale-only path (index page)', () => {
+      const params = getRouteParams('en', true)
+      expect(params).toEqual({ locale: 'en', slug: undefined })
+    })
+
+    it('should handle path with locale and direct page', () => {
+      const params = getRouteParams('fr/intro', true)
+      expect(params).toEqual({ locale: 'fr', slug: 'intro' })
+    })
+  })
+})
+
+describe('getDocPath', () => {
+  describe('without i18n', () => {
+    it('should generate path with default base path', () => {
+      const path = getDocPath('getting-started', 'docs', false)
+      expect(path).toBe('/docs/getting-started')
+    })
+
+    it('should generate path with custom base path', () => {
+      const path = getDocPath('getting-started', 'guides', false)
+      expect(path).toBe('/guides/getting-started')
+    })
+
+    it('should handle nested paths', () => {
+      const path = getDocPath('api/endpoints/users', 'docs', false)
+      expect(path).toBe('/docs/api/endpoints/users')
+    })
+
+    it('should normalize base path with leading slash', () => {
+      const path = getDocPath('intro', '/guides', false)
+      expect(path).toBe('/guides/intro')
+    })
+
+    it('should normalize base path with trailing slash', () => {
+      const path = getDocPath('intro', 'guides/', false)
+      expect(path).toBe('/guides/intro')
+    })
+
+    it('should normalize base path with both slashes', () => {
+      const path = getDocPath('intro', '/guides/', false)
+      expect(path).toBe('/guides/intro')
+    })
+
+    it('should handle multiple leading/trailing slashes', () => {
+      const path = getDocPath('intro', '///guides///', false)
+      expect(path).toBe('/guides/intro')
+    })
+  })
+
+  describe('with i18n', () => {
+    it('should generate localized path', () => {
+      const path = getDocPath('en/getting-started', 'docs', true, 'en')
+      expect(path).toBe('/en/docs/getting-started')
+    })
+
+    it('should generate localized path for different locale', () => {
+      const path = getDocPath('de/einfuehrung', 'docs', true, 'de')
+      expect(path).toBe('/de/docs/einfuehrung')
+    })
+
+    it('should generate localized path with custom base path', () => {
+      const path = getDocPath('en/tutorial', 'guides', true, 'en')
+      expect(path).toBe('/en/guides/tutorial')
+    })
+
+    it('should handle nested paths with locale', () => {
+      const path = getDocPath('en/api/endpoints/users', 'docs', true, 'en')
+      expect(path).toBe('/en/docs/api/endpoints/users')
+    })
+
+    it('should handle index page (id without nested path)', () => {
+      const path = getDocPath('en', 'docs', true, 'en')
+      expect(path).toBe('/en/docs/en')
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle empty id without i18n', () => {
+      const path = getDocPath('', 'docs', false)
+      expect(path).toBe('/docs/')
+    })
+
+    it('should handle deeply nested base path', () => {
+      const path = getDocPath('intro', 'api/reference/v2', false)
+      expect(path).toBe('/api/reference/v2/intro')
+    })
+  })
+})

package/src/routeHelpers.ts

@@ -0,0 +1,78 @@
+import type { CollectionEntry } from 'astro:content'
+
+/**
+ * Configuration for generating static paths for a docs collection.
+ */
+export interface DocsRouteConfig {
+  /**
+   * The base path for the docs routes (without leading/trailing slashes).
+   * @example 'docs', 'guides', 'api/reference'
+   */
+  routeBasePath: string
+
+  /**
+   * Whether i18n is enabled for this docs instance.
+   * When true, expects docs to have locale prefixes in their IDs.
+   */
+  hasI18n: boolean
+}
+
+/**
+ * Generate route parameters from a doc entry's slug.
+ *
+ * @param slug - The slug from the doc entry (e.g., 'en/getting-started' or 'getting-started')
+ * @param hasI18n - Whether i18n is enabled
+ * @returns Route parameters object
+ */
+export const getRouteParams = (slug: string, hasI18n: boolean) => {
+  if (hasI18n) {
+    const [locale, ...rest] = slug.split('/')
+    return {
+      slug: rest.length ? rest.join('/') : undefined,
+      locale,
+    }
+  }
+  return {
+    slug: slug || undefined,
+  }
+}
+
+/**
+ * Generate the full URL path for a doc entry.
+ *
+ * @param id - The doc entry ID
+ * @param routeBasePath - The base path for routes
+ * @param hasI18n - Whether i18n is enabled
+ * @param currentLocale - The current locale (for i18n)
+ * @returns The full URL path
+ */
+export const getDocPath = (
+  id: string,
+  routeBasePath: string,
+  hasI18n: boolean,
+  currentLocale?: string,
+) => {
+  // Remove leading and trailing slashes safely (avoid polynomial regex)
+  let normalizedBasePath = routeBasePath
+  while (normalizedBasePath.startsWith('/')) {
+    normalizedBasePath = normalizedBasePath.slice(1)
+  }
+  while (normalizedBasePath.endsWith('/')) {
+    normalizedBasePath = normalizedBasePath.slice(0, -1)
+  }
+
+  if (hasI18n && currentLocale) {
+    // Remove locale prefix from id (e.g., 'en/guide/intro' -> 'guide/intro')
+    const pathWithoutLocale = id.includes('/')
+      ? id.slice(id.indexOf('/') + 1)
+      : id
+    return `/${currentLocale}/${normalizedBasePath}/${pathWithoutLocale}`
+  }
+
+  return `/${normalizedBasePath}/${id}`
+}
+
+/**
+ * Type for docs collection entry with inferred data structure.
+ */
+export type DocsEntry = CollectionEntry<'docs'>