@levino/shipyard-docs 0.4.7 → 0.5.0-rc-20251126212334

package/astro/DocPagination.astro

@@ -0,0 +1,97 @@
+---
+import type { PaginationLink } from '../src/pagination'
+
+interface Props {
+  prev?: PaginationLink
+  next?: PaginationLink
+  prevLabel?: string
+  nextLabel?: string
+}
+
+const { prev, next, prevLabel = 'Previous', nextLabel = 'Next' } = Astro.props
+
+// Only render if there's at least one link
+const shouldRender = prev || next
+---
+
+{
+  shouldRender && (
+    <nav
+      class="pagination-nav mt-8 border-t border-base-300 pt-6"
+      aria-label="Docs navigation"
+    >
+      {prev ? (
+        <a
+          href={prev.href}
+          class="pagination-nav__link pagination-nav__link--prev"
+          rel="prev"
+        >
+          <span class="pagination-nav__sublabel">{prevLabel}</span>
+          <span class="pagination-nav__label">{prev.title}</span>
+        </a>
+      ) : (
+        <span />
+      )}
+
+      {next ? (
+        <a
+          href={next.href}
+          class="pagination-nav__link pagination-nav__link--next"
+          rel="next"
+        >
+          <span class="pagination-nav__sublabel">{nextLabel}</span>
+          <span class="pagination-nav__label">{next.title}</span>
+        </a>
+      ) : (
+        <span />
+      )}
+    </nav>
+  )
+}
+
+<style>
+  .pagination-nav {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 1rem;
+  }
+
+  .pagination-nav__link {
+    display: block;
+    padding: 1rem;
+    border: 1px solid oklch(var(--bc) / 0.2);
+    border-radius: var(--rounded-box, 1rem);
+    transition: border-color 0.2s;
+    line-height: 1.25;
+  }
+
+  .pagination-nav__link:hover {
+    border-color: oklch(var(--p));
+    text-decoration: none;
+  }
+
+  .pagination-nav__link--next {
+    text-align: right;
+  }
+
+  .pagination-nav__sublabel {
+    display: block;
+    font-size: 0.75rem;
+    opacity: 0.7;
+    margin-bottom: 0.25rem;
+  }
+
+  .pagination-nav__label {
+    display: block;
+    font-weight: 600;
+    word-break: break-word;
+  }
+
+  .pagination-nav__link--prev .pagination-nav__label::before {
+    content: '« ';
+  }
+
+  .pagination-nav__link--next .pagination-nav__label::after {
+    content: ' »';
+  }
+</style>

package/astro/Layout.astro

@@ -5,8 +5,10 @@ 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 { getPaginationInfo } from '../src/pagination'
 import type { DocsData } from '../src/sidebarEntries'
 import { toSidebarEntries } from '../src/sidebarEntries'
+import DocPagination from './DocPagination.astro'
 
 interface Props {
   headings?: { depth: number; text: string; slug: string }[]
@@ -28,10 +30,21 @@ const { headings = [], routeBasePath = 'docs', docsData } = Astro.props
 // Normalize the route base path
 const normalizedBasePath = routeBasePath.replace(/^\/+|\/+$/g, '')
 
-const getPath = (id: string) =>
-  i18n
-    ? `/${Astro.currentLocale}/${normalizedBasePath}/${id.slice(3)}`
-    : `/${normalizedBasePath}/${id}`
+const getPath = (id: string) => {
+  // Remove the .md extension if present and handle index pages
+  const cleanId = id.replace(/\.md$/, '')
+  const isIndex = cleanId.endsWith('/index') || cleanId === 'index'
+
+  if (i18n) {
+    // For i18n, slice off the locale prefix (e.g., 'en/')
+    const pathPart = cleanId.slice(3)
+    const finalPath = isIndex ? pathPart.replace(/\/?index$/, '') : pathPart
+    return `/${Astro.currentLocale}/${normalizedBasePath}/${finalPath}`
+  }
+
+  const finalPath = isIndex ? cleanId.replace(/\/?index$/, '') : cleanId
+  return `/${normalizedBasePath}/${finalPath}`
+}
 
 // Use provided docsData or fetch from the default 'docs' collection
 const docs =
@@ -48,6 +61,8 @@ const docs =
             sidebar_label,
             sidebar_class_name,
             sidebar_custom_props,
+            pagination_next,
+            pagination_prev,
           },
         } = doc
         return {
@@ -68,6 +83,8 @@ const docs =
           sidebarLabel: sidebar_label,
           sidebarClassName: sidebar_class_name,
           sidebarCustomProps: sidebar_custom_props,
+          pagination_next,
+          pagination_prev,
         }
       }),
     )
@@ -79,6 +96,9 @@ const entries: NavigationTree =
   i18n && Astro.currentLocale
     ? (fullTree[Astro.currentLocale]?.subEntry ?? {})
     : fullTree
+
+// Compute pagination info for the current page
+const pagination = getPaginationInfo(Astro.url.pathname, entries, docs)
 ---
 
 <BaseLayout sidebarNavigation={entries}>
@@ -88,6 +108,7 @@ const entries: NavigationTree =
         <Breadcrumbs navigation={entries} />
         <TableOfContents links={headings} class="xl:hidden" />
         <slot />
+        <DocPagination prev={pagination.prev} next={pagination.next} />
       </div>
     </div>
     <div class="hidden xl:block col-span-3">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-docs",
-  "version": "0.4.7",
+  "version": "0.5.0-rc-20251126212334",
   "description": "",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -2,6 +2,9 @@ import type { AstroIntegration } from 'astro'
 import { glob } from 'astro/loaders'
 import { z } from 'astro/zod'
 
+// Re-export pagination types and utilities
+export type { PaginationInfo, PaginationLink } from './pagination'
+export { getPaginationInfo } from './pagination'
 export type { DocsRouteConfig } from './routeHelpers'
 // Re-export route helpers
 export { getDocPath, getRouteParams } from './routeHelpers'
@@ -21,6 +24,8 @@ export const docsSchema = z.object({
   sidebar_position: z.number().optional(),
   sidebar_label: z.string().optional(),
   sidebar_class_name: z.string().optional(),
+  pagination_next: z.string().nullable().optional(),
+  pagination_prev: z.string().nullable().optional(),
 })
 
 /**

package/src/pagination.test.ts

@@ -0,0 +1,387 @@
+import type { Entry } from '@levino/shipyard-base'
+import { describe, expect, it } from 'vitest'
+import { getPaginationInfo } from './pagination'
+import type { DocsData } from './sidebarEntries'
+
+describe('getPaginationInfo', () => {
+  const createSidebar = (): Entry => ({
+    intro: {
+      label: 'Introduction',
+      href: '/docs/intro',
+    },
+    guide: {
+      label: 'Guide',
+      subEntry: {
+        'getting-started': {
+          label: 'Getting Started',
+          href: '/docs/guide/getting-started',
+        },
+        advanced: {
+          label: 'Advanced',
+          href: '/docs/guide/advanced',
+        },
+      },
+    },
+    api: {
+      label: 'API Reference',
+      href: '/docs/api',
+    },
+  })
+
+  const createDocs = (): DocsData[] => [
+    {
+      id: 'intro.md',
+      title: 'Introduction',
+      path: '/docs/intro',
+    },
+    {
+      id: 'guide/getting-started.md',
+      title: 'Getting Started',
+      path: '/docs/guide/getting-started',
+    },
+    {
+      id: 'guide/advanced.md',
+      title: 'Advanced',
+      path: '/docs/guide/advanced',
+    },
+    {
+      id: 'api.md',
+      title: 'API Reference',
+      path: '/docs/api',
+    },
+  ]
+
+  it('should return prev and next for a middle page', () => {
+    const sidebar = createSidebar()
+    const docs = createDocs()
+    const pagination = getPaginationInfo(
+      '/docs/guide/getting-started',
+      sidebar,
+      docs,
+    )
+
+    expect(pagination.prev).toEqual({
+      title: 'Introduction',
+      href: '/docs/intro',
+    })
+    expect(pagination.next).toEqual({
+      title: 'Advanced',
+      href: '/docs/guide/advanced',
+    })
+  })
+
+  it('should return only next for first page', () => {
+    const sidebar = createSidebar()
+    const docs = createDocs()
+    const pagination = getPaginationInfo('/docs/intro', sidebar, docs)
+
+    expect(pagination.prev).toBeUndefined()
+    expect(pagination.next).toEqual({
+      title: 'Getting Started',
+      href: '/docs/guide/getting-started',
+    })
+  })
+
+  it('should return only prev for last page', () => {
+    const sidebar = createSidebar()
+    const docs = createDocs()
+    const pagination = getPaginationInfo('/docs/api', sidebar, docs)
+
+    expect(pagination.prev).toEqual({
+      title: 'Advanced',
+      href: '/docs/guide/advanced',
+    })
+    expect(pagination.next).toBeUndefined()
+  })
+
+  it('should return empty object for page not in sidebar', () => {
+    const sidebar = createSidebar()
+    const docs = createDocs()
+    const pagination = getPaginationInfo('/docs/unknown', sidebar, docs)
+
+    expect(pagination).toEqual({})
+  })
+
+  it('should respect pagination_next override', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+        pagination_next: 'api.md', // Skip directly to api
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+      },
+      {
+        id: 'guide/advanced.md',
+        title: 'Advanced',
+        path: '/docs/guide/advanced',
+      },
+      {
+        id: 'api.md',
+        title: 'API Reference',
+        path: '/docs/api',
+      },
+    ]
+
+    const pagination = getPaginationInfo('/docs/intro', sidebar, docs)
+
+    expect(pagination.prev).toBeUndefined()
+    expect(pagination.next).toEqual({
+      title: 'API Reference',
+      href: '/docs/api',
+    })
+  })
+
+  it('should respect pagination_prev override', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+      },
+      {
+        id: 'guide/advanced.md',
+        title: 'Advanced',
+        path: '/docs/guide/advanced',
+      },
+      {
+        id: 'api.md',
+        title: 'API Reference',
+        path: '/docs/api',
+        pagination_prev: 'intro.md', // Skip back to intro
+      },
+    ]
+
+    const pagination = getPaginationInfo('/docs/api', sidebar, docs)
+
+    expect(pagination.prev).toEqual({
+      title: 'Introduction',
+      href: '/docs/intro',
+    })
+    expect(pagination.next).toBeUndefined()
+  })
+
+  it('should disable next pagination when pagination_next is null', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+        pagination_next: null, // Explicitly disable
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+      },
+    ]
+
+    const pagination = getPaginationInfo('/docs/intro', sidebar, docs)
+
+    expect(pagination.prev).toBeUndefined()
+    expect(pagination.next).toBeUndefined()
+  })
+
+  it('should disable prev pagination when pagination_prev is null', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+        pagination_prev: null, // Explicitly disable
+      },
+    ]
+
+    const pagination = getPaginationInfo(
+      '/docs/guide/getting-started',
+      sidebar,
+      docs,
+    )
+
+    expect(pagination.prev).toBeUndefined()
+    expect(pagination.next).toEqual({
+      title: 'Advanced',
+      href: '/docs/guide/advanced',
+    })
+  })
+
+  it('should disable all pagination when both are null', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+        pagination_next: null,
+        pagination_prev: null,
+      },
+    ]
+
+    const pagination = getPaginationInfo(
+      '/docs/guide/getting-started',
+      sidebar,
+      docs,
+    )
+
+    expect(pagination).toEqual({})
+  })
+
+  it('should use sidebarLabel when available', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+        sidebarLabel: 'Intro', // Custom label
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+      },
+    ]
+
+    const pagination = getPaginationInfo(
+      '/docs/guide/getting-started',
+      sidebar,
+      docs,
+    )
+
+    expect(pagination.prev).toEqual({
+      title: 'Introduction',
+      href: '/docs/intro',
+    })
+  })
+
+  it('should handle nested sidebar structure correctly', () => {
+    const sidebar: Entry = {
+      guide: {
+        label: 'Guide',
+        subEntry: {
+          basics: {
+            label: 'Basics',
+            subEntry: {
+              'page-1': {
+                label: 'Page 1',
+                href: '/docs/guide/basics/page-1',
+              },
+              'page-2': {
+                label: 'Page 2',
+                href: '/docs/guide/basics/page-2',
+              },
+            },
+          },
+          advanced: {
+            label: 'Advanced',
+            subEntry: {
+              'page-3': {
+                label: 'Page 3',
+                href: '/docs/guide/advanced/page-3',
+              },
+            },
+          },
+        },
+      },
+    }
+
+    const docs: DocsData[] = [
+      {
+        id: 'guide/basics/page-1.md',
+        title: 'Page 1',
+        path: '/docs/guide/basics/page-1',
+      },
+      {
+        id: 'guide/basics/page-2.md',
+        title: 'Page 2',
+        path: '/docs/guide/basics/page-2',
+      },
+      {
+        id: 'guide/advanced/page-3.md',
+        title: 'Page 3',
+        path: '/docs/guide/advanced/page-3',
+      },
+    ]
+
+    const pagination = getPaginationInfo(
+      '/docs/guide/basics/page-2',
+      sidebar,
+      docs,
+    )
+
+    expect(pagination.prev).toEqual({
+      title: 'Page 1',
+      href: '/docs/guide/basics/page-1',
+    })
+    expect(pagination.next).toEqual({
+      title: 'Page 3',
+      href: '/docs/guide/advanced/page-3',
+    })
+  })
+
+  it('should handle invalid pagination_next reference gracefully', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+        pagination_next: 'nonexistent.md', // Invalid reference
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+      },
+    ]
+
+    const pagination = getPaginationInfo('/docs/intro', sidebar, docs)
+
+    // Should not have a next link because the reference is invalid
+    expect(pagination.next).toBeUndefined()
+  })
+
+  it('should handle invalid pagination_prev reference gracefully', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+        pagination_prev: 'nonexistent.md', // Invalid reference
+      },
+    ]
+
+    const pagination = getPaginationInfo(
+      '/docs/guide/getting-started',
+      sidebar,
+      docs,
+    )
+
+    // Should not have a prev link because the reference is invalid
+    expect(pagination.prev).toBeUndefined()
+  })
+})

package/src/pagination.ts

@@ -0,0 +1,191 @@
+import type { Entry } from '@levino/shipyard-base'
+import type { DocsData } from './sidebarEntries'
+
+export interface PaginationLink {
+  title: string
+  href: string
+}
+
+export interface PaginationInfo {
+  prev?: PaginationLink
+  next?: PaginationLink
+}
+
+interface FlattenedEntry {
+  title: string
+  href: string
+}
+
+/**
+ * Normalizes a path by removing trailing slashes (except for root path).
+ * This ensures consistent path comparison regardless of trailing slash variations.
+ */
+const normalizePath = (path: string): string => {
+  if (path === '/') return path
+  return path.replace(/\/+$/, '')
+}
+
+/**
+ * Flattens a hierarchical sidebar entry structure into an ordered array of pages.
+ * This preserves the order in which pages appear in the sidebar, including nested items.
+ *
+ * @param entries - The hierarchical sidebar entries
+ * @returns An array of flattened entries with title and href
+ */
+const flattenSidebarEntries = (entries: Entry): FlattenedEntry[] => {
+  const result: FlattenedEntry[] = []
+
+  const traverse = (entryRecord: Entry) => {
+    for (const [_key, value] of Object.entries(entryRecord)) {
+      // Add the current entry if it has an href (i.e., it's a page, not just a category)
+      if (value.href && value.label) {
+        result.push({
+          title: value.label,
+          href: value.href,
+        })
+      }
+
+      // Recursively traverse children
+      if (value.subEntry) {
+        traverse(value.subEntry)
+      }
+    }
+  }
+
+  traverse(entries)
+  return result
+}
+
+/**
+ * Finds the previous and next pages for a given document based on its position
+ * in the sidebar navigation.
+ *
+ * @param currentPath - The path of the current page (e.g., '/docs/getting-started')
+ * @param sidebarEntries - The hierarchical sidebar entries
+ * @param allDocs - All documentation pages (for looking up frontmatter overrides)
+ * @returns An object containing prev and/or next pagination links
+ */
+export const getPaginationInfo = (
+  currentPath: string,
+  sidebarEntries: Entry,
+  allDocs: readonly DocsData[],
+): PaginationInfo => {
+  // Normalize the current path to handle trailing slash variations
+  const normalizedCurrentPath = normalizePath(currentPath)
+
+  // Find the current doc to check for pagination overrides
+  const currentDoc = allDocs.find(
+    (doc) => normalizePath(doc.path) === normalizedCurrentPath,
+  )
+
+  // Check for explicit pagination overrides in frontmatter
+  const paginationNext = currentDoc?.['pagination_next' as keyof DocsData]
+  const paginationPrev = currentDoc?.['pagination_prev' as keyof DocsData]
+
+  // If explicitly disabled (null), return empty pagination
+  if (paginationNext === null && paginationPrev === null) {
+    return {}
+  }
+
+  // Flatten the sidebar to get ordered list of pages
+  const flatPages = flattenSidebarEntries(sidebarEntries)
+
+  // Find current page index (using normalized paths for comparison)
+  const currentIndex = flatPages.findIndex(
+    (page) => normalizePath(page.href) === normalizedCurrentPath,
+  )
+
+  // Check if this is an index/landing page not in the sidebar
+  // Index pages are identified by having a doc but not being in the sidebar.
+  // They typically have a path like /en/docs or /docs (the base docs path).
+  // We detect this by checking if the current doc exists but isn't in flatPages.
+  // Additionally, check if the doc ID matches common index patterns:
+  // - Just a locale (e.g., 'en' from 'en/index.md')
+  // - Empty or 'index'
+  const docIdParts = currentDoc?.id?.split('/') ?? []
+  const lastIdPart = docIdParts[docIdParts.length - 1]
+  const isIndexPage =
+    currentIndex === -1 &&
+    currentDoc &&
+    // Doc exists but not in sidebar - could be an index page
+    // Check if the doc ID suggests it's an index (locale-only ID, 'index', or empty after locale)
+    (docIdParts.length === 1 || lastIdPart === 'index' || lastIdPart === '')
+
+  if (currentIndex === -1 && !isIndexPage) {
+    // Current page not found in sidebar and not an index page - no pagination
+    return {}
+  }
+
+  const result: PaginationInfo = {}
+
+  // Special handling for index pages: they come before all sidebar items
+  if (isIndexPage) {
+    // Index page has no previous, and first sidebar item as next
+    if (paginationPrev !== null && typeof paginationPrev === 'string') {
+      const targetDoc = allDocs.find((doc) => doc.id === paginationPrev)
+      if (targetDoc?.path) {
+        result.prev = {
+          title: targetDoc.sidebarLabel ?? targetDoc.title,
+          href: targetDoc.path,
+        }
+      }
+    }
+    // No prev for index page (unless explicitly set above)
+
+    if (paginationNext === null) {
+      // Explicitly disabled
+      result.next = undefined
+    } else if (typeof paginationNext === 'string') {
+      const targetDoc = allDocs.find((doc) => doc.id === paginationNext)
+      if (targetDoc?.path) {
+        result.next = {
+          title: targetDoc.sidebarLabel ?? targetDoc.title,
+          href: targetDoc.path,
+        }
+      }
+    } else if (flatPages.length > 0) {
+      // Use the first sidebar item as next
+      result.next = flatPages[0]
+    }
+
+    return result
+  }
+
+  // Handle previous page
+  if (paginationPrev === null) {
+    // Explicitly disabled
+    result.prev = undefined
+  } else if (typeof paginationPrev === 'string') {
+    // Explicitly set to a specific page ID
+    const targetDoc = allDocs.find((doc) => doc.id === paginationPrev)
+    if (targetDoc?.path) {
+      result.prev = {
+        title: targetDoc.sidebarLabel ?? targetDoc.title,
+        href: targetDoc.path,
+      }
+    }
+  } else if (currentIndex > 0) {
+    // Use the previous page in sidebar order
+    result.prev = flatPages[currentIndex - 1]
+  }
+
+  // Handle next page
+  if (paginationNext === null) {
+    // Explicitly disabled
+    result.next = undefined
+  } else if (typeof paginationNext === 'string') {
+    // Explicitly set to a specific page ID
+    const targetDoc = allDocs.find((doc) => doc.id === paginationNext)
+    if (targetDoc?.path) {
+      result.next = {
+        title: targetDoc.sidebarLabel ?? targetDoc.title,
+        href: targetDoc.path,
+      }
+    }
+  } else if (currentIndex < flatPages.length - 1) {
+    // Use the next page in sidebar order
+    result.next = flatPages[currentIndex + 1]
+  }
+
+  return result
+}

package/src/sidebarEntries.ts

@@ -8,6 +8,8 @@ export interface DocsData {
   sidebarPosition?: number
   sidebarLabel?: string
   sidebarClassName?: string
+  pagination_next?: string | null
+  pagination_prev?: string | null
 }
 
 interface TreeNode {