@levino/shipyard-docs 0.5.2 → 0.6.0

package/astro/Layout.astro

@@ -14,6 +14,12 @@ import DocMetadata from './DocMetadata.astro'
 import DocPagination from './DocPagination.astro'
 import LlmsTxtSidebarLabel from './LlmsTxtSidebarLabel.astro'
 
+type CustomMetaTag = {
+  name?: string
+  property?: string
+  content: string
+}
+
 interface Props {
   headings?: { depth: number; text: string; slug: string }[]
   /**
@@ -39,6 +45,36 @@ interface Props {
    * The name of the author who last updated this page.
    */
   lastAuthor?: string
+  /**
+   * Whether to hide the table of contents on this page.
+   * @default false
+   */
+  hideTableOfContents?: boolean
+  /**
+   * SEO keywords for the page.
+   */
+  keywords?: string[]
+  /**
+   * Social preview image URL (og:image).
+   */
+  image?: string
+  /**
+   * Custom canonical URL for the page.
+   */
+  canonicalUrl?: string
+  /**
+   * Custom meta tags to add to the page head.
+   */
+  customMetaTags?: CustomMetaTag[]
+  /**
+   * Whether to hide the H1 title heading on this page.
+   * @default false
+   */
+  hideTitle?: boolean
+  /**
+   * Override title for SEO/browser tab (overrides the regular title in <title> tag).
+   */
+  titleMeta?: string
 }
 
 const {
@@ -48,6 +84,13 @@ const {
   editUrl,
   lastUpdated,
   lastAuthor,
+  hideTableOfContents = false,
+  hideTitle = false,
+  keywords,
+  image,
+  canonicalUrl,
+  customMetaTags,
+  titleMeta,
 } = Astro.props
 
 // Normalize the route base path
@@ -82,21 +125,22 @@ const docs =
         const {
           id,
           data: {
+            id: customId,
             title,
-            sidebar: { render: shouldBeRendered, label },
-            sidebar_position,
-            sidebar_label,
-            sidebar_class_name,
-            sidebar_custom_props,
-            pagination_next,
-            pagination_prev,
+            sidebar,
+            render: shouldRender,
+            unlisted,
+            paginationLabel,
+            paginationNext,
+            paginationPrev,
           },
         } = doc
         return {
           id,
+          customId,
           path: getPath(id),
           title:
-            label ??
+            sidebar.label ??
             title ??
             Option.getOrUndefined(
               EffectArray.findFirst(
@@ -105,13 +149,17 @@ const docs =
               ),
             )?.text ??
             id,
-          link: shouldBeRendered,
-          sidebarPosition: sidebar_position,
-          sidebarLabel: sidebar_label,
-          sidebarClassName: sidebar_class_name,
-          sidebarCustomProps: sidebar_custom_props,
-          pagination_next,
-          pagination_prev,
+          link: shouldRender,
+          sidebarPosition: sidebar.position,
+          sidebarLabel: sidebar.label,
+          sidebarClassName: sidebar.className,
+          sidebarCustomProps: sidebar.customProps,
+          collapsible: sidebar.collapsible,
+          collapsed: sidebar.collapsed,
+          unlisted,
+          paginationLabel,
+          paginationNext,
+          paginationPrev,
         }
       }),
     )
@@ -144,21 +192,23 @@ if (docsConfig?.llmsTxtEnabled) {
 }
 ---
 
-<BaseLayout sidebarNavigation={entries}>
+<BaseLayout sidebarNavigation={entries} keywords={keywords} image={image} canonicalUrl={canonicalUrl} customMetaTags={customMetaTags} title={titleMeta}>
   <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">
+    <div class:list={['col-span-12', { 'xl:col-span-9': !hideTableOfContents }]}>
+      <div class:list={['prose', 'max-w-none', { 'hide-title': hideTitle }]}>
         <Breadcrumbs navigation={entries} />
-        <TableOfContents links={headings} class="xl:hidden" />
+        {!hideTableOfContents && <TableOfContents links={headings} class="xl:hidden" />}
         <slot />
         <DocMetadata editUrl={editUrl} lastUpdated={lastUpdated} lastAuthor={lastAuthor} />
         <DocPagination prev={pagination.prev} next={pagination.next} />
       </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 />
+    {!hideTableOfContents && (
+      <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>
+    )}
   </div>
 </BaseLayout>

package/package.json

@@ -1,22 +1,32 @@
 {
   "name": "@levino/shipyard-docs",
-  "version": "0.5.2",
-  "description": "",
+  "version": "0.6.0",
+  "description": "Documentation plugin for shipyard with automatic sidebar, pagination, and git metadata",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
     "test:unit": "vitest run"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "withastro",
+    "frameworks",
+    "documentation",
+    "docs",
+    "sidebar",
+    "markdown"
+  ],
+  "author": "Levin Keller",
+  "license": "MIT",
+  "homepage": "https://shipyard.levinkeller.de",
   "peerDependencies": {
     "astro": "^5.15"
   },
   "dependencies": {
     "effect": "^3.12.5",
     "ramda": "^0.31",
-    "@levino/shipyard-base": "^0.5.11"
+    "@levino/shipyard-base": "^0.6.0"
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.16",

package/src/fallbacks.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest'
+import { extractFirstParagraph } from './fallbacks'
+
+describe('extractFirstParagraph', () => {
+  it('should extract a simple paragraph', () => {
+    const body = 'This is the first paragraph.'
+    expect(extractFirstParagraph(body)).toBe('This is the first paragraph.')
+  })
+
+  it('should extract first paragraph and ignore subsequent content', () => {
+    const body = `This is the first paragraph.
+
+This is the second paragraph.`
+    expect(extractFirstParagraph(body)).toBe('This is the first paragraph.')
+  })
+
+  it('should skip headings and extract first paragraph', () => {
+    const body = `# Main Heading
+
+This is the first paragraph.
+
+More content here.`
+    expect(extractFirstParagraph(body)).toBe('This is the first paragraph.')
+  })
+
+  it('should skip multiple headings', () => {
+    const body = `# Heading 1
+## Heading 2
+### Heading 3
+
+First paragraph content.`
+    expect(extractFirstParagraph(body)).toBe('First paragraph content.')
+  })
+
+  it('should combine multi-line paragraphs', () => {
+    const body = `First line of paragraph.
+Second line of same paragraph.
+Third line.
+
+Next paragraph.`
+    expect(extractFirstParagraph(body)).toBe(
+      'First line of paragraph. Second line of same paragraph. Third line.',
+    )
+  })
+
+  it('should skip code blocks', () => {
+    const body = `\`\`\`javascript
+const code = 'example'
+\`\`\`
+
+Actual first paragraph.`
+    expect(extractFirstParagraph(body)).toBe('Actual first paragraph.')
+  })
+
+  it('should skip images', () => {
+    const body = `![Alt text](image.png)
+
+First paragraph after image.`
+    expect(extractFirstParagraph(body)).toBe('First paragraph after image.')
+  })
+
+  it('should skip list items', () => {
+    const body = `- Item 1
+- Item 2
+* Item 3
+1. Numbered item
+
+First actual paragraph.`
+    expect(extractFirstParagraph(body)).toBe('First actual paragraph.')
+  })
+
+  it('should skip blockquotes', () => {
+    const body = `> This is a quote
+> More quote
+
+First paragraph.`
+    expect(extractFirstParagraph(body)).toBe('First paragraph.')
+  })
+
+  it('should skip horizontal rules', () => {
+    const body = `---
+
+First paragraph.`
+    expect(extractFirstParagraph(body)).toBe('First paragraph.')
+  })
+
+  it('should skip HTML comments', () => {
+    const body = `<!-- This is a comment -->
+
+First paragraph.`
+    expect(extractFirstParagraph(body)).toBe('First paragraph.')
+  })
+
+  it('should return undefined for empty content', () => {
+    expect(extractFirstParagraph('')).toBeUndefined()
+  })
+
+  it('should return undefined for content with only headings', () => {
+    const body = `# Heading 1
+## Heading 2`
+    expect(extractFirstParagraph(body)).toBeUndefined()
+  })
+
+  it('should return undefined for content with only non-paragraph elements', () => {
+    const body = `- List item
+- Another item
+> Quote
+
+---
+
+\`\`\`code\`\`\``
+    expect(extractFirstParagraph(body)).toBeUndefined()
+  })
+
+  it('should handle content starting with paragraph directly', () => {
+    const body = `Direct paragraph without preceding newlines.
+
+Second paragraph.`
+    expect(extractFirstParagraph(body)).toBe(
+      'Direct paragraph without preceding newlines.',
+    )
+  })
+
+  it('should handle mixed markdown elements before paragraph', () => {
+    const body = `# Title
+
+![Image](img.png)
+
+> Quote
+
+- List
+
+Finally, the first paragraph.`
+    expect(extractFirstParagraph(body)).toBe('Finally, the first paragraph.')
+  })
+})

package/src/fallbacks.ts

@@ -0,0 +1,82 @@
+/**
+ * Utility functions for fallback values in documentation pages.
+ * Used when frontmatter fields are not explicitly provided.
+ */
+
+/**
+ * Extracts the first paragraph from markdown content.
+ * Used as a fallback for the description field when not provided in frontmatter.
+ *
+ * @param body - The markdown content body (without frontmatter)
+ * @returns The first paragraph text, or undefined if no paragraph found
+ */
+export const extractFirstParagraph = (body: string): string | undefined => {
+  // Skip headings (lines starting with `#`)
+  // Return first non-empty paragraph text
+  const lines = body.split('\n')
+  const paragraphLines: string[] = []
+  let inCodeBlock = false
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+
+    // Track code block state
+    if (trimmed.startsWith('```')) {
+      inCodeBlock = !inCodeBlock
+      continue
+    }
+
+    // Skip content inside code blocks
+    if (inCodeBlock) {
+      continue
+    }
+
+    // Skip empty lines before we've started collecting
+    if (!trimmed) {
+      if (paragraphLines.length > 0) {
+        // End of first paragraph
+        break
+      }
+      continue
+    }
+
+    // Skip headings
+    if (trimmed.startsWith('#')) {
+      continue
+    }
+
+    // Skip images
+    if (trimmed.startsWith('![')) {
+      continue
+    }
+
+    // Skip HTML comments
+    if (trimmed.startsWith('<!--')) {
+      continue
+    }
+
+    // Skip list items (they're not paragraphs)
+    if (
+      trimmed.startsWith('-') ||
+      trimmed.startsWith('*') ||
+      /^\d+\./.test(trimmed)
+    ) {
+      continue
+    }
+
+    // Skip blockquotes
+    if (trimmed.startsWith('>')) {
+      continue
+    }
+
+    // Skip horizontal rules
+    if (/^[-*_]{3,}$/.test(trimmed)) {
+      continue
+    }
+
+    // This is part of a paragraph
+    paragraphLines.push(trimmed)
+  }
+
+  return paragraphLines.length > 0 ? paragraphLines.join(' ') : undefined
+}