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

package/src/index.ts

@@ -4,6 +4,8 @@ import type { AstroIntegration } from 'astro'
 import { glob } from 'astro/loaders'
 import { z } from 'astro/zod'
 
+// Re-export fallback utilities
+export { extractFirstParagraph } from './fallbacks'
 // Re-export git metadata utilities
 export type { GitMetadata } from './gitMetadata'
 export { getEditUrl, getGitMetadata } from './gitMetadata'
@@ -20,37 +22,150 @@ export { getDocPath, getRouteParams } from './routeHelpers'
 export type { DocsData } from './sidebarEntries'
 export { toSidebarEntries } from './sidebarEntries'
 
-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(),
-  sidebar_custom_props: z.record(z.any()).optional(),
-  pagination_next: z.string().nullable().optional(),
-  pagination_prev: z.string().nullable().optional(),
-  /**
-   * Override the last update author for this specific page.
-   * Set to false to hide the author for this page.
-   */
-  last_update_author: z.union([z.string(), z.literal(false)]).optional(),
-  /**
-   * Override the last update timestamp for this specific page.
-   * Set to false to hide the timestamp for this page.
-   */
-  last_update_time: z.union([z.coerce.date(), z.literal(false)]).optional(),
-  /**
-   * Custom edit URL for this specific page.
-   * Set to null to disable edit link for this page.
-   */
-  custom_edit_url: z.string().nullable().optional(),
-})
+/**
+ * Schema for sidebar configuration grouped under a single object.
+ * Contains all sidebar-related fields for categories and pages.
+ */
+const sidebarSchema = z
+  .object({
+    /** Sort order in sidebar (default: Infinity - sorted alphabetically after positioned items) */
+    position: z.number().optional(),
+    /** Display label in sidebar (default: title -> H1 -> filename) */
+    label: z.string().optional(),
+    /** CSS class(es) for styling the sidebar entry */
+    className: z.string().optional(),
+    /** Arbitrary metadata for custom sidebar components */
+    customProps: z.record(z.any()).optional(),
+    /** Can category be collapsed (default: true) */
+    collapsible: z.boolean().default(true),
+    /** Start collapsed (default: true) */
+    collapsed: z.boolean().default(true),
+  })
+  .refine((data) => !(data.collapsed === true && data.collapsible === false), {
+    message:
+      'sidebar.collapsed cannot be true when sidebar.collapsible is false',
+  })
+
+export const docsSchema = z
+  .object({
+    // === Page Metadata ===
+    /** Custom document ID (default: file path) */
+    id: z.string().optional(),
+    /** Reference title for SEO, pagination, previews (default: H1) */
+    title: z.string().optional(),
+    /** Override title for SEO/browser tab (default: title) - Docusaurus snake_case convention */
+    title_meta: z.string().optional(),
+    /** Meta description (default: first paragraph) */
+    description: z.string().optional(),
+    /** SEO keywords */
+    keywords: z.array(z.string()).optional(),
+    /** Social preview image (og:image) */
+    image: z.string().optional(),
+    /** Custom canonical URL */
+    canonicalUrl: z.string().optional(),
+    /** Custom canonical URL - snake_case alias for Docusaurus compatibility */
+    canonical_url: z.string().optional(),
+
+    // === Page Rendering ===
+    /** Whether to render a page (default: true) */
+    render: z.boolean().default(true),
+    /** Exclude from production builds (default: false) */
+    draft: z.boolean().default(false),
+    /** Render page but hide from sidebar (default: false) */
+    unlisted: z.boolean().default(false),
+    /** Custom URL slug */
+    slug: z.string().optional(),
+
+    // === Layout Options ===
+    /** Hide the H1 heading (default: false) */
+    hideTitle: z.boolean().default(false),
+    /** Hide the H1 heading (default: false) - snake_case alias for Docusaurus compatibility */
+    hide_title: z.boolean().optional(),
+    /** Hide the TOC (default: false) */
+    hideTableOfContents: z.boolean().default(false),
+    /** Hide the TOC (default: false) - snake_case alias for Docusaurus compatibility */
+    hide_table_of_contents: z.boolean().optional(),
+    /** Full-width page without sidebar (default: false) */
+    hideSidebar: z.boolean().default(false),
+    /** Min heading level in TOC (default: 2) */
+    tocMinHeadingLevel: z.number().min(1).max(6).default(2),
+    /** Max heading level in TOC (default: 3) */
+    tocMaxHeadingLevel: z.number().min(1).max(6).default(3),
+
+    // === Sidebar Configuration (grouped) ===
+    sidebar: sidebarSchema.default({ collapsible: true, collapsed: true }),
+
+    // === Pagination ===
+    /** Label shown in prev/next buttons */
+    paginationLabel: z.string().optional(),
+    /** Label shown in prev/next buttons - snake_case alias for Docusaurus compatibility */
+    pagination_label: z.string().optional(),
+    /** Next page ID, or null to disable */
+    paginationNext: z.string().nullable().optional(),
+    /** Next page ID - snake_case alias for Docusaurus compatibility */
+    pagination_next: z.string().nullable().optional(),
+    /** Previous page ID, or null to disable */
+    paginationPrev: z.string().nullable().optional(),
+    /** Previous page ID - snake_case alias for Docusaurus compatibility */
+    pagination_prev: z.string().nullable().optional(),
+
+    // === Git Metadata Overrides ===
+    /**
+     * Override the last update author for this specific page.
+     * Set to false to hide the author for this page.
+     */
+    lastUpdateAuthor: z.union([z.string(), z.literal(false)]).optional(),
+    /**
+     * Override the last update timestamp for this specific page.
+     * Set to false to hide the timestamp for this page.
+     */
+    lastUpdateTime: z.union([z.literal(false), z.coerce.date()]).optional(),
+    /**
+     * Custom edit URL for this specific page.
+     * Set to null to disable edit link for this page.
+     */
+    customEditUrl: z.string().nullable().optional(),
+
+    // === Custom Meta Tags ===
+    customMetaTags: z
+      .array(
+        z.object({
+          name: z.string().optional(),
+          property: z.string().optional(),
+          content: z.string(),
+        }),
+      )
+      .optional(),
+    /** Custom meta tags - snake_case alias for Docusaurus compatibility */
+    custom_meta_tags: z
+      .array(
+        z.object({
+          name: z.string().optional(),
+          property: z.string().optional(),
+          content: z.string(),
+        }),
+      )
+      .optional(),
+  })
+  .transform((data) => ({
+    ...data,
+    // Merge snake_case aliases into camelCase fields
+    hideTitle: data.hide_title ?? data.hideTitle,
+    hideTableOfContents:
+      data.hide_table_of_contents ?? data.hideTableOfContents,
+    canonicalUrl: data.canonical_url ?? data.canonicalUrl,
+    customMetaTags: data.custom_meta_tags ?? data.customMetaTags,
+    paginationLabel: data.pagination_label ?? data.paginationLabel,
+    // For nullable fields, we need to check if the snake_case key exists (not just use ??)
+    // because null ?? undefined = undefined, but we want null to be preserved
+    paginationNext:
+      'pagination_next' in data ? data.pagination_next : data.paginationNext,
+    paginationPrev:
+      'pagination_prev' in data ? data.pagination_prev : data.paginationPrev,
+  }))
+  .refine((data) => data.tocMinHeadingLevel <= data.tocMaxHeadingLevel, {
+    message: 'tocMinHeadingLevel must be <= tocMaxHeadingLevel',
+  })
 
 /**
  * Configuration for llms.txt generation.
@@ -276,7 +391,10 @@ import Layout from '@levino/shipyard-docs/astro/Layout.astro'
 export async function getStaticPaths() {
   const collectionName = ${JSON.stringify(resolvedCollectionName)}
   const routeBasePath = ${JSON.stringify(normalizedBasePath)}
-  const docs = await getCollection(collectionName)
+  const allDocs = await getCollection(collectionName)
+
+  // Filter out pages with render: false - they should not generate pages
+  const docs = allDocs.filter((doc) => doc.data.render !== false)
 
   const getParams = (slug) => {
     if (i18n) {
@@ -309,13 +427,13 @@ const docsConfig = docsConfigs[routeBasePath] ?? {
 
 const { Content, headings } = await render(entry)
 
-const { custom_edit_url, last_update_author, last_update_time } = entry.data
+const { customEditUrl, lastUpdateAuthor, lastUpdateTime, hideTableOfContents, hideTitle, keywords, image, canonicalUrl, customMetaTags, title_meta: titleMeta } = entry.data
 
 let editUrl
-if (custom_edit_url === null) {
+if (customEditUrl === null) {
   editUrl = undefined
-} else if (custom_edit_url) {
-  editUrl = custom_edit_url
+} else if (customEditUrl) {
+  editUrl = customEditUrl
 } else {
   editUrl = getEditUrl(docsConfig.editUrl, entry.id)
 }
@@ -324,32 +442,32 @@ let lastUpdated
 let lastAuthor
 
 if (
-  (docsConfig.showLastUpdateTime && last_update_time !== false) ||
-  (docsConfig.showLastUpdateAuthor && last_update_author !== false)
+  (docsConfig.showLastUpdateTime && lastUpdateTime !== false) ||
+  (docsConfig.showLastUpdateAuthor && lastUpdateAuthor !== false)
 ) {
   const filePath = entry.filePath
 
   if (filePath) {
     const gitMetadata = getGitMetadata(filePath)
 
-    if (docsConfig.showLastUpdateTime && last_update_time !== false) {
+    if (docsConfig.showLastUpdateTime && lastUpdateTime !== false) {
       lastUpdated =
-        last_update_time instanceof Date
-          ? last_update_time
+        lastUpdateTime instanceof Date
+          ? lastUpdateTime
           : gitMetadata.lastUpdated
     }
 
-    if (docsConfig.showLastUpdateAuthor && last_update_author !== false) {
+    if (docsConfig.showLastUpdateAuthor && lastUpdateAuthor !== false) {
       lastAuthor =
-        typeof last_update_author === 'string'
-          ? last_update_author
+        typeof lastUpdateAuthor === 'string'
+          ? lastUpdateAuthor
           : gitMetadata.lastAuthor
     }
   }
 }
 ---
 
-<Layout headings={headings} routeBasePath={routeBasePath} editUrl={editUrl} lastUpdated={lastUpdated} lastAuthor={lastAuthor}>
+<Layout headings={headings} routeBasePath={routeBasePath} editUrl={editUrl} lastUpdated={lastUpdated} lastAuthor={lastAuthor} hideTableOfContents={hideTableOfContents} hideTitle={hideTitle} keywords={keywords} image={image} canonicalUrl={canonicalUrl} customMetaTags={customMetaTags} titleMeta={titleMeta}>
   <Content />
 </Layout>
 `
@@ -424,10 +542,13 @@ export const getStaticPaths: GetStaticPaths = async () => {
 
   // When i18n is enabled, only include docs from the default locale
   const defaultLocale = i18n?.defaultLocale
-  const docs = defaultLocale
+  const localeDocs = defaultLocale
     ? allDocs.filter((doc) => doc.id.startsWith(defaultLocale + '/') || doc.id === defaultLocale)
     : allDocs
 
+  // Filter out unlisted and non-rendered pages
+  const docs = localeDocs.filter((doc) => !doc.data.unlisted && doc.data.render !== false)
+
   return docs.map((doc) => {
     const cleanId = doc.id.replace(/\\.md$/, '')
     // For i18n, strip the locale prefix from the slug
@@ -491,10 +612,13 @@ export const GET: APIRoute = async ({ site }) => {
 
   // When i18n is enabled, only include docs from the default locale
   const defaultLocale = i18n?.defaultLocale
-  const docs = defaultLocale
+  const localeDocs = defaultLocale
     ? allDocs.filter((doc) => doc.id.startsWith(defaultLocale + '/') || doc.id === defaultLocale)
     : allDocs
 
+  // Filter out unlisted and non-rendered pages
+  const docs = localeDocs.filter((doc) => !doc.data.unlisted && doc.data.render !== false)
+
   const entries = await Promise.all(
     docs.map(async (doc) => {
       const { headings } = await render(doc)
@@ -521,7 +645,7 @@ export const GET: APIRoute = async ({ site }) => {
         path,
         title: doc.data.title ?? h1?.text ?? doc.id,
         description: doc.data.description,
-        position: doc.data.sidebar_position,
+        position: doc.data.sidebar?.position,
       }
     })
   )
@@ -556,10 +680,13 @@ export const GET: APIRoute = async ({ site }) => {
 
   // When i18n is enabled, only include docs from the default locale
   const defaultLocale = i18n?.defaultLocale
-  const docs = defaultLocale
+  const localeDocs = defaultLocale
     ? allDocs.filter((doc) => doc.id.startsWith(defaultLocale + '/') || doc.id === defaultLocale)
     : allDocs
 
+  // Filter out unlisted and non-rendered pages
+  const docs = localeDocs.filter((doc) => !doc.data.unlisted && doc.data.render !== false)
+
   const entries = await Promise.all(
     docs.map(async (doc) => {
       const { headings } = await render(doc)
@@ -589,7 +716,7 @@ export const GET: APIRoute = async ({ site }) => {
         path,
         title: doc.data.title ?? h1?.text ?? doc.id,
         description: doc.data.description,
-        position: doc.data.sidebar_position,
+        position: doc.data.sidebar?.position,
         content: rawContent,
       }
     })

package/src/pagination.test.ts

@@ -31,21 +31,25 @@ describe('getPaginationInfo', () => {
   const createDocs = (): DocsData[] => [
     {
       id: 'intro.md',
+      fileId: 'intro.md',
       title: 'Introduction',
       path: '/docs/intro',
     },
     {
       id: 'guide/getting-started.md',
+      fileId: 'guide/getting-started.md',
       title: 'Getting Started',
       path: '/docs/guide/getting-started',
     },
     {
       id: 'guide/advanced.md',
+      fileId: 'guide/advanced.md',
       title: 'Advanced',
       path: '/docs/guide/advanced',
     },
     {
       id: 'api.md',
+      fileId: 'api.md',
       title: 'API Reference',
       path: '/docs/api',
     },
@@ -102,27 +106,31 @@ describe('getPaginationInfo', () => {
     expect(pagination).toEqual({})
   })
 
-  it('should respect pagination_next override', () => {
+  it('should respect paginationNext override', () => {
     const sidebar = createSidebar()
     const docs: DocsData[] = [
       {
         id: 'intro.md',
+        fileId: 'intro.md',
         title: 'Introduction',
         path: '/docs/intro',
-        pagination_next: 'api.md', // Skip directly to api
+        paginationNext: 'api.md', // Skip directly to api
       },
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
       },
       {
         id: 'guide/advanced.md',
+        fileId: 'guide/advanced.md',
         title: 'Advanced',
         path: '/docs/guide/advanced',
       },
       {
         id: 'api.md',
+        fileId: 'api.md',
         title: 'API Reference',
         path: '/docs/api',
       },
@@ -137,29 +145,33 @@ describe('getPaginationInfo', () => {
     })
   })
 
-  it('should respect pagination_prev override', () => {
+  it('should respect paginationPrev override', () => {
     const sidebar = createSidebar()
     const docs: DocsData[] = [
       {
         id: 'intro.md',
+        fileId: 'intro.md',
         title: 'Introduction',
         path: '/docs/intro',
       },
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
       },
       {
         id: 'guide/advanced.md',
+        fileId: 'guide/advanced.md',
         title: 'Advanced',
         path: '/docs/guide/advanced',
       },
       {
         id: 'api.md',
+        fileId: 'api.md',
         title: 'API Reference',
         path: '/docs/api',
-        pagination_prev: 'intro.md', // Skip back to intro
+        paginationPrev: 'intro.md', // Skip back to intro
       },
     ]
 
@@ -172,17 +184,19 @@ describe('getPaginationInfo', () => {
     expect(pagination.next).toBeUndefined()
   })
 
-  it('should disable next pagination when pagination_next is null', () => {
+  it('should disable next pagination when paginationNext is null', () => {
     const sidebar = createSidebar()
     const docs: DocsData[] = [
       {
         id: 'intro.md',
+        fileId: 'intro.md',
         title: 'Introduction',
         path: '/docs/intro',
-        pagination_next: null, // Explicitly disable
+        paginationNext: null, // Explicitly disable
       },
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
       },
@@ -194,19 +208,21 @@ describe('getPaginationInfo', () => {
     expect(pagination.next).toBeUndefined()
   })
 
-  it('should disable prev pagination when pagination_prev is null', () => {
+  it('should disable prev pagination when paginationPrev is null', () => {
     const sidebar = createSidebar()
     const docs: DocsData[] = [
       {
         id: 'intro.md',
+        fileId: 'intro.md',
         title: 'Introduction',
         path: '/docs/intro',
       },
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
-        pagination_prev: null, // Explicitly disable
+        paginationPrev: null, // Explicitly disable
       },
     ]
 
@@ -228,10 +244,11 @@ describe('getPaginationInfo', () => {
     const docs: DocsData[] = [
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
-        pagination_next: null,
-        pagination_prev: null,
+        paginationNext: null,
+        paginationPrev: null,
       },
     ]
 
@@ -249,12 +266,14 @@ describe('getPaginationInfo', () => {
     const docs: DocsData[] = [
       {
         id: 'intro.md',
+        fileId: 'intro.md',
         title: 'Introduction',
         path: '/docs/intro',
         sidebarLabel: 'Intro', // Custom label
       },
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
       },
@@ -266,8 +285,39 @@ describe('getPaginationInfo', () => {
       docs,
     )
 
+    // sidebarLabel is used for the title, so it should be 'Intro' not 'Introduction'
     expect(pagination.prev).toEqual({
-      title: 'Introduction',
+      title: 'Intro',
+      href: '/docs/intro',
+    })
+  })
+
+  it('should use paginationLabel when available', () => {
+    const sidebar = createSidebar()
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+        sidebarLabel: 'Intro',
+        paginationLabel: 'Start Here', // Custom pagination label takes priority
+      },
+      {
+        id: 'guide/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/guide/getting-started',
+        paginationPrev: 'intro.md',
+      },
+    ]
+
+    const pagination = getPaginationInfo(
+      '/docs/guide/getting-started',
+      sidebar,
+      docs,
+    )
+
+    expect(pagination.prev).toEqual({
+      title: 'Start Here',
       href: '/docs/intro',
     })
   })
@@ -306,16 +356,19 @@ describe('getPaginationInfo', () => {
     const docs: DocsData[] = [
       {
         id: 'guide/basics/page-1.md',
+        fileId: 'guide/basics/page-1.md',
         title: 'Page 1',
         path: '/docs/guide/basics/page-1',
       },
       {
         id: 'guide/basics/page-2.md',
+        fileId: 'guide/basics/page-2.md',
         title: 'Page 2',
         path: '/docs/guide/basics/page-2',
       },
       {
         id: 'guide/advanced/page-3.md',
+        fileId: 'guide/advanced/page-3.md',
         title: 'Page 3',
         path: '/docs/guide/advanced/page-3',
       },
@@ -337,17 +390,19 @@ describe('getPaginationInfo', () => {
     })
   })
 
-  it('should handle invalid pagination_next reference gracefully', () => {
+  it('should handle invalid paginationNext reference gracefully', () => {
     const sidebar = createSidebar()
     const docs: DocsData[] = [
       {
         id: 'intro.md',
+        fileId: 'intro.md',
         title: 'Introduction',
         path: '/docs/intro',
-        pagination_next: 'nonexistent.md', // Invalid reference
+        paginationNext: 'nonexistent.md', // Invalid reference
       },
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
       },
@@ -359,19 +414,21 @@ describe('getPaginationInfo', () => {
     expect(pagination.next).toBeUndefined()
   })
 
-  it('should handle invalid pagination_prev reference gracefully', () => {
+  it('should handle invalid paginationPrev reference gracefully', () => {
     const sidebar = createSidebar()
     const docs: DocsData[] = [
       {
         id: 'intro.md',
+        fileId: 'intro.md',
         title: 'Introduction',
         path: '/docs/intro',
       },
       {
         id: 'guide/getting-started.md',
+        fileId: 'guide/getting-started.md',
         title: 'Getting Started',
         path: '/docs/guide/getting-started',
-        pagination_prev: 'nonexistent.md', // Invalid reference
+        paginationPrev: 'nonexistent.md', // Invalid reference
       },
     ]
 
@@ -384,4 +441,47 @@ describe('getPaginationInfo', () => {
     // Should not have a prev link because the reference is invalid
     expect(pagination.prev).toBeUndefined()
   })
+
+  it('should exclude unlisted pages from pagination (via sidebar)', () => {
+    // Note: unlisted pages are filtered from sidebar entries before being passed
+    // to getPaginationInfo, so they won't appear in pagination
+    const sidebar: Entry = {
+      intro: {
+        label: 'Introduction',
+        href: '/docs/intro',
+      },
+      // Hidden page is NOT in sidebar
+      visible: {
+        label: 'Visible',
+        href: '/docs/visible',
+      },
+    }
+
+    const docs: DocsData[] = [
+      {
+        id: 'intro.md',
+        title: 'Introduction',
+        path: '/docs/intro',
+      },
+      {
+        id: 'hidden.md',
+        title: 'Hidden Page',
+        path: '/docs/hidden',
+        unlisted: true,
+      },
+      {
+        id: 'visible.md',
+        title: 'Visible',
+        path: '/docs/visible',
+      },
+    ]
+
+    const pagination = getPaginationInfo('/docs/intro', sidebar, docs)
+
+    // Next should be 'visible', not 'hidden'
+    expect(pagination.next).toEqual({
+      title: 'Visible',
+      href: '/docs/visible',
+    })
+  })
 })