@levino/shipyard-docs 0.5.1 → 0.5.2

package/README.md

@@ -1,6 +1,6 @@
 # @levino/shipyard-docs
 
-Documentation plugin for [Shipyard](https://shipyard.levinkeller.de), a general-purpose page builder for Astro.
+Documentation plugin for [shipyard](https://shipyard.levinkeller.de), a general-purpose page builder for Astro.
 
 ## Installation
 

package/astro/Layout.astro

@@ -5,12 +5,14 @@ import { docsConfigs } from 'virtual:shipyard-docs-configs'
 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 { experimental_AstroContainer as AstroContainer } from 'astro/container'
 import { Array as EffectArray, Option } from 'effect'
 import { getPaginationInfo } from '../src/pagination'
 import type { DocsData } from '../src/sidebarEntries'
 import { toSidebarEntries } from '../src/sidebarEntries'
 import DocMetadata from './DocMetadata.astro'
 import DocPagination from './DocPagination.astro'
+import LlmsTxtSidebarLabel from './LlmsTxtSidebarLabel.astro'
 
 interface Props {
   headings?: { depth: number; text: string; slug: string }[]
@@ -122,8 +124,24 @@ const entries: NavigationTree =
     ? (fullTree[Astro.currentLocale]?.subEntry ?? {})
     : fullTree
 
-// Compute pagination info for the current page
+// Compute pagination info for the current page BEFORE adding llms.txt
+// (llms.txt should not be part of pagination navigation)
 const pagination = getPaginationInfo(Astro.url.pathname, entries, docs)
+
+// Add llms.txt link to sidebar if enabled for this docs instance
+// This is added AFTER pagination computation so it doesn't affect prev/next navigation
+const docsConfig = docsConfigs[normalizedBasePath]
+const llmsTxtHref = `/${normalizedBasePath}/llms.txt`
+// Render the LlmsTxtSidebarLabel component to HTML using Astro Container
+if (docsConfig?.llmsTxtEnabled) {
+  const container = await AstroContainer.create()
+  const llmsTxtLabelHtml = await container.renderToString(LlmsTxtSidebarLabel, {
+    props: { href: llmsTxtHref },
+  })
+  entries['llms.txt'] = {
+    labelHtml: llmsTxtLabelHtml,
+  }
+}
 ---
 
 <BaseLayout sidebarNavigation={entries}>

package/astro/LlmsTxtSidebarLabel.astro

@@ -0,0 +1,63 @@
+---
+interface Props {
+  href: string
+}
+
+const { href } = Astro.props
+---
+
+<llms-txt-label data-href={href}>
+  <span class="flex items-center justify-between gap-1">
+    <a href={href}>llms.txt</a>
+    <button
+      type="button"
+      class="btn btn-ghost btn-xs p-0.5"
+      title="Copy URL to clipboard"
+      aria-label="Copy URL to clipboard"
+      data-copy-url={href}
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke-width="1.5"
+        stroke="currentColor"
+        class="w-4 h-4"
+      >
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          d="M15.75 17.25v3.375c0 .621-.504 1.125-1.125 1.125h-9.75a1.125 1.125 0 0 1-1.125-1.125V7.875c0-.621.504-1.125 1.125-1.125H6.75a9.06 9.06 0 0 1 1.5.124m7.5 10.376h3.375c.621 0 1.125-.504 1.125-1.125V11.25c0-4.46-3.243-8.161-7.5-8.876a9.06 9.06 0 0 0-1.5-.124H9.375c-.621 0-1.125.504-1.125 1.125v3.5m7.5 10.375H9.375a1.125 1.125 0 0 1-1.125-1.125v-9.25m12 6.625v-1.875a3.375 3.375 0 0 0-3.375-3.375h-1.5a1.125 1.125 0 0 1-1.125-1.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H9.75"
+        ></path>
+      </svg>
+    </button>
+  </span>
+</llms-txt-label>
+
+<script>
+  class LlmsTxtLabel extends HTMLElement {
+    connectedCallback() {
+      const href = this.dataset.href
+      if (!href) return
+
+      const button = this.querySelector('button')
+      if (!button) return
+
+      button.addEventListener('click', async (event) => {
+        event.preventDefault()
+        event.stopPropagation()
+
+        const fullUrl = new URL(href, window.location.origin).toString()
+        try {
+          await navigator.clipboard.writeText(fullUrl)
+          button.classList.add('text-success')
+          setTimeout(() => button.classList.remove('text-success'), 1500)
+        } catch (error) {
+          console.error('Failed to copy URL:', error)
+        }
+      })
+    }
+  }
+
+  customElements.define('llms-txt-label', LlmsTxtLabel)
+</script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-docs",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "",
   "type": "module",
   "main": "src/index.ts",
@@ -16,7 +16,7 @@
   "dependencies": {
     "effect": "^3.12.5",
     "ramda": "^0.31",
-    "@levino/shipyard-base": "^0.5.9"
+    "@levino/shipyard-base": "^0.5.11"
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.16",

package/src/index.ts

@@ -7,6 +7,9 @@ import { z } from 'astro/zod'
 // Re-export git metadata utilities
 export type { GitMetadata } from './gitMetadata'
 export { getEditUrl, getGitMetadata } from './gitMetadata'
+// Re-export llms.txt utilities
+export type { LlmsDocEntry, LlmsTxtConfig } from './llmsTxt'
+export { generateLlmsFullTxt, generateLlmsTxt } from './llmsTxt'
 // Re-export pagination types and utilities
 export type { PaginationInfo, PaginationLink } from './pagination'
 export { getPaginationInfo } from './pagination'
@@ -49,6 +52,39 @@ export const docsSchema = z.object({
   custom_edit_url: z.string().nullable().optional(),
 })
 
+/**
+ * Configuration for llms.txt generation.
+ * When enabled, generates llms.txt and llms-full.txt files following
+ * the specification at https://llmstxt.org/
+ */
+export interface LlmsTxtDocsConfig {
+  /**
+   * Whether to enable llms.txt generation.
+   * @default false
+   */
+  enabled?: boolean
+  /**
+   * The project name to use as the H1 heading in llms.txt.
+   * If not provided, will need to be set for the file to be useful.
+   */
+  projectName?: string
+  /**
+   * A concise summary of the project displayed as a blockquote.
+   * This should help LLMs quickly understand what the project is about.
+   */
+  summary?: string
+  /**
+   * Optional additional description paragraphs.
+   * Displayed after the summary blockquote.
+   */
+  description?: string
+  /**
+   * Custom section title for the documentation links.
+   * @default 'Documentation'
+   */
+  sectionTitle?: string
+}
+
 /**
  * Configuration for a docs instance.
  */
@@ -83,6 +119,23 @@ export interface DocsConfig {
    * @default false
    */
   showLastUpdateAuthor?: boolean
+  /**
+   * Configuration for llms.txt generation.
+   * Enables automatic generation of llms.txt and llms-full.txt files
+   * that help LLMs understand and index your documentation.
+   *
+   * @example
+   * ```ts
+   * shipyardDocs({
+   *   llmsTxt: {
+   *     enabled: true,
+   *     projectName: 'My Project',
+   *     summary: 'A framework for building amazing apps',
+   *   }
+   * })
+   * ```
+   */
+  llmsTxt?: LlmsTxtDocsConfig
 }
 
 /**
@@ -113,7 +166,7 @@ export const createDocsCollection = (
 })
 
 /**
- * Shipyard Docs integration for Astro.
+ * shipyard Docs integration for Astro.
  *
  * Supports multiple documentation instances with configurable route mounting.
  *
@@ -147,6 +200,7 @@ const docsConfigs: Record<
     showLastUpdateAuthor: boolean
     routeBasePath: string
     collectionName: string
+    llmsTxtEnabled: boolean
   }
 > = {}
 
@@ -157,6 +211,7 @@ export default (config: DocsConfig = {}): AstroIntegration => {
     editUrl,
     showLastUpdateTime = false,
     showLastUpdateAuthor = false,
+    llmsTxt,
   } = config
 
   // Normalize the route base path (remove leading/trailing slashes safely)
@@ -178,6 +233,7 @@ export default (config: DocsConfig = {}): AstroIntegration => {
     showLastUpdateAuthor,
     routeBasePath: normalizedBasePath,
     collectionName: resolvedCollectionName,
+    llmsTxtEnabled: !!llmsTxt?.enabled,
   }
 
   // Virtual module for this specific route's config
@@ -342,6 +398,234 @@ if (
             prerender: true,
           })
         }
+
+        // Generate llms.txt routes if enabled
+        if (llmsTxt?.enabled) {
+          const llmsTxtConfig = {
+            projectName: llmsTxt.projectName ?? 'Documentation',
+            summary: llmsTxt.summary,
+            description: llmsTxt.description,
+            sectionTitle: llmsTxt.sectionTitle ?? 'Documentation',
+          }
+
+          // Generate individual plain text endpoints for each doc page
+          // These are mounted at /_llms-txt/[slug].txt
+          const llmsTxtPagesFileName = `llms-txt-pages-${normalizedBasePath}.ts`
+          const llmsTxtPagesFilePath = join(generatedDir, llmsTxtPagesFileName)
+
+          const llmsTxtPagesFileContent = `import type { APIRoute, GetStaticPaths } from 'astro'
+import { i18n } from 'astro:config/server'
+import { getCollection, render } from 'astro:content'
+
+const collectionName = ${JSON.stringify(resolvedCollectionName)}
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const allDocs = await getCollection(collectionName)
+
+  // When i18n is enabled, only include docs from the default locale
+  const defaultLocale = i18n?.defaultLocale
+  const docs = defaultLocale
+    ? allDocs.filter((doc) => doc.id.startsWith(defaultLocale + '/') || doc.id === defaultLocale)
+    : allDocs
+
+  return docs.map((doc) => {
+    const cleanId = doc.id.replace(/\\.md$/, '')
+    // For i18n, strip the locale prefix from the slug
+    let slug = cleanId
+    if (i18n && defaultLocale) {
+      const [locale, ...rest] = cleanId.split('/')
+      slug = rest.length ? rest.join('/') : locale
+    }
+    // Handle index pages - use special suffix
+    if (slug.endsWith('/index')) {
+      slug = slug.slice(0, -6) + '/_index'
+    } else if (slug === 'index') {
+      slug = '_index'
+    }
+
+    return {
+      // For [...slug], the param should be the full path string (Astro handles the split)
+      params: { slug },
+      props: { doc },
+    }
+  })
+}
+
+export const GET: APIRoute = async ({ props }) => {
+  const { doc } = props as { doc: Awaited<ReturnType<typeof getCollection>>[number] }
+  const { headings } = await render(doc)
+  const h1 = headings.find((h) => h.depth === 1)
+
+  // Build the plain text content with title and raw markdown body
+  const title = doc.data.title ?? h1?.text ?? doc.id
+  const description = doc.data.description ? doc.data.description + '\\n\\n' : ''
+  const body = doc.body ?? ''
+
+  const content = '# ' + title + '\\n\\n' + description + body
+
+  return new Response(content, {
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+    },
+  })
+}
+`
+          writeFileSync(llmsTxtPagesFilePath, llmsTxtPagesFileContent)
+
+          // Generate llms.txt endpoint file
+          const llmsTxtFileName = `llms-txt-${normalizedBasePath}.ts`
+          const llmsTxtFilePath = join(generatedDir, llmsTxtFileName)
+
+          const llmsTxtFileContent = `import type { APIRoute } from 'astro'
+import { i18n } from 'astro:config/server'
+import { getCollection, render } from 'astro:content'
+import { generateLlmsTxt } from '@levino/shipyard-docs'
+
+const llmsTxtConfig = ${JSON.stringify(llmsTxtConfig)}
+const collectionName = ${JSON.stringify(resolvedCollectionName)}
+const routeBasePath = ${JSON.stringify(normalizedBasePath)}
+
+export const GET: APIRoute = async ({ site }) => {
+  const baseUrl = site?.toString() ?? 'https://example.com'
+  const allDocs = await getCollection(collectionName)
+
+  // When i18n is enabled, only include docs from the default locale
+  const defaultLocale = i18n?.defaultLocale
+  const docs = defaultLocale
+    ? allDocs.filter((doc) => doc.id.startsWith(defaultLocale + '/') || doc.id === defaultLocale)
+    : allDocs
+
+  const entries = await Promise.all(
+    docs.map(async (doc) => {
+      const { headings } = await render(doc)
+      const h1 = headings.find((h) => h.depth === 1)
+      const cleanId = doc.id.replace(/\\.md$/, '')
+
+      // Generate slug for the _llms-txt path
+      let slug = cleanId
+      if (i18n && defaultLocale) {
+        const [locale, ...rest] = cleanId.split('/')
+        slug = rest.length ? rest.join('/') : locale
+      }
+      // Handle index pages - use special suffix
+      if (slug.endsWith('/index')) {
+        slug = slug.slice(0, -6) + '/_index'
+      } else if (slug === 'index') {
+        slug = '_index'
+      }
+
+      // Path points to the plain text file
+      const path = '/' + routeBasePath + '/_llms-txt/' + slug + '.txt'
+
+      return {
+        path,
+        title: doc.data.title ?? h1?.text ?? doc.id,
+        description: doc.data.description,
+        position: doc.data.sidebar_position,
+      }
+    })
+  )
+
+  const content = generateLlmsTxt(entries, llmsTxtConfig, baseUrl)
+
+  return new Response(content, {
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+    },
+  })
+}
+`
+          writeFileSync(llmsTxtFilePath, llmsTxtFileContent)
+
+          // Generate llms-full.txt endpoint file
+          const llmsFullTxtFileName = `llms-full-txt-${normalizedBasePath}.ts`
+          const llmsFullTxtFilePath = join(generatedDir, llmsFullTxtFileName)
+
+          const llmsFullTxtFileContent = `import type { APIRoute } from 'astro'
+import { i18n } from 'astro:config/server'
+import { getCollection, render } from 'astro:content'
+import { generateLlmsFullTxt } from '@levino/shipyard-docs'
+
+const llmsTxtConfig = ${JSON.stringify(llmsTxtConfig)}
+const collectionName = ${JSON.stringify(resolvedCollectionName)}
+const routeBasePath = ${JSON.stringify(normalizedBasePath)}
+
+export const GET: APIRoute = async ({ site }) => {
+  const baseUrl = site?.toString() ?? 'https://example.com'
+  const allDocs = await getCollection(collectionName)
+
+  // When i18n is enabled, only include docs from the default locale
+  const defaultLocale = i18n?.defaultLocale
+  const docs = defaultLocale
+    ? allDocs.filter((doc) => doc.id.startsWith(defaultLocale + '/') || doc.id === defaultLocale)
+    : allDocs
+
+  const entries = await Promise.all(
+    docs.map(async (doc) => {
+      const { headings } = await render(doc)
+      const h1 = headings.find((h) => h.depth === 1)
+      const cleanId = doc.id.replace(/\\.md$/, '')
+
+      // Generate slug for the _llms-txt path
+      let slug = cleanId
+      if (i18n && defaultLocale) {
+        const [locale, ...rest] = cleanId.split('/')
+        slug = rest.length ? rest.join('/') : locale
+      }
+      // Handle index pages - use special suffix
+      if (slug.endsWith('/index')) {
+        slug = slug.slice(0, -6) + '/_index'
+      } else if (slug === 'index') {
+        slug = '_index'
+      }
+
+      // Path points to the plain text file
+      const path = '/' + routeBasePath + '/_llms-txt/' + slug + '.txt'
+
+      // Read the raw markdown content from the file
+      const rawContent = doc.body ?? ''
+
+      return {
+        path,
+        title: doc.data.title ?? h1?.text ?? doc.id,
+        description: doc.data.description,
+        position: doc.data.sidebar_position,
+        content: rawContent,
+      }
+    })
+  )
+
+  const content = generateLlmsFullTxt(entries, llmsTxtConfig, baseUrl)
+
+  return new Response(content, {
+    headers: {
+      'Content-Type': 'text/plain; charset=utf-8',
+    },
+  })
+}
+`
+          writeFileSync(llmsFullTxtFilePath, llmsFullTxtFileContent)
+
+          // Inject route for individual plain text pages (catch-all for nested paths)
+          injectRoute({
+            pattern: `/${normalizedBasePath}/_llms-txt/[...slug].txt`,
+            entrypoint: llmsTxtPagesFilePath,
+            prerender: true,
+          })
+
+          // Inject routes for llms.txt and llms-full.txt under the docs path
+          injectRoute({
+            pattern: `/${normalizedBasePath}/llms.txt`,
+            entrypoint: llmsTxtFilePath,
+            prerender: true,
+          })
+
+          injectRoute({
+            pattern: `/${normalizedBasePath}/llms-full.txt`,
+            entrypoint: llmsFullTxtFilePath,
+            prerender: true,
+          })
+        }
       },
     },
   }

package/src/llmsTxt.ts

@@ -0,0 +1,183 @@
+/**
+ * llms.txt generation utilities for shipyard-docs.
+ *
+ * This module provides utilities to generate llms.txt and llms-full.txt files
+ * following the specification at https://llmstxt.org/
+ *
+ * The llms.txt format helps LLMs efficiently parse and understand documentation
+ * by providing a structured markdown index of all documentation pages.
+ */
+
+/**
+ * Configuration for llms.txt generation.
+ */
+export interface LlmsTxtConfig {
+  /**
+   * Whether to enable llms.txt generation.
+   * @default false
+   */
+  enabled?: boolean
+  /**
+   * The project name to use as the H1 heading.
+   * If not provided, the title from the shipyard-base configuration will be used.
+   */
+  projectName?: string
+  /**
+   * A concise summary of the project displayed as a blockquote.
+   * This should help LLMs quickly understand what the project is about.
+   */
+  summary?: string
+  /**
+   * Optional additional description paragraphs.
+   * Displayed after the summary blockquote.
+   */
+  description?: string
+  /**
+   * Custom section title for the documentation links.
+   * @default 'Documentation'
+   */
+  sectionTitle?: string
+}
+
+/**
+ * Represents a documentation page for llms.txt generation.
+ */
+export interface LlmsDocEntry {
+  /**
+   * The URL path to the documentation page.
+   */
+  path: string
+  /**
+   * The title of the documentation page.
+   */
+  title: string
+  /**
+   * Optional description of what the page covers.
+   */
+  description?: string
+  /**
+   * The full rendered content of the page (used for llms-full.txt).
+   */
+  content?: string
+  /**
+   * Position for sorting (lower numbers come first).
+   */
+  position?: number
+}
+
+/**
+ * Generates the content for llms.txt following the specification.
+ *
+ * @param entries - Array of documentation entries to include
+ * @param config - Configuration options
+ * @param baseUrl - Base URL of the site (e.g., 'https://docs.example.com')
+ * @returns The generated llms.txt content as a string
+ */
+export function generateLlmsTxt(
+  entries: LlmsDocEntry[],
+  config: LlmsTxtConfig,
+  baseUrl: string,
+): string {
+  const lines: string[] = []
+
+  // H1 title (required)
+  const projectName = config.projectName ?? 'Documentation'
+  lines.push(`# ${projectName}`)
+  lines.push('')
+
+  // Blockquote summary (recommended)
+  if (config.summary) {
+    lines.push(`> ${config.summary}`)
+    lines.push('')
+  }
+
+  // Additional description
+  if (config.description) {
+    lines.push(config.description)
+    lines.push('')
+  }
+
+  // Documentation section
+  const sectionTitle = config.sectionTitle ?? 'Documentation'
+  lines.push(`## ${sectionTitle}`)
+  lines.push('')
+
+  // Sort entries by position, then by title
+  const sortedEntries = [...entries].sort((a, b) => {
+    const posA = a.position ?? Number.POSITIVE_INFINITY
+    const posB = b.position ?? Number.POSITIVE_INFINITY
+    if (posA !== posB) return posA - posB
+    return a.title.localeCompare(b.title)
+  })
+
+  // Generate links
+  for (const entry of sortedEntries) {
+    const url = new URL(entry.path, baseUrl).toString()
+    const description = entry.description ? `: ${entry.description}` : ''
+    lines.push(`- [${entry.title}](${url})${description}`)
+  }
+
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * Generates the content for llms-full.txt with complete documentation content.
+ *
+ * @param entries - Array of documentation entries with content
+ * @param config - Configuration options
+ * @param baseUrl - Base URL of the site
+ * @returns The generated llms-full.txt content as a string
+ */
+export function generateLlmsFullTxt(
+  entries: LlmsDocEntry[],
+  config: LlmsTxtConfig,
+  baseUrl: string,
+): string {
+  const lines: string[] = []
+
+  // H1 title (required)
+  const projectName = config.projectName ?? 'Documentation'
+  lines.push(`# ${projectName}`)
+  lines.push('')
+
+  // Blockquote summary (recommended)
+  if (config.summary) {
+    lines.push(`> ${config.summary}`)
+    lines.push('')
+  }
+
+  // Additional description
+  if (config.description) {
+    lines.push(config.description)
+    lines.push('')
+  }
+
+  lines.push('---')
+  lines.push('')
+
+  // Sort entries by position, then by title
+  const sortedEntries = [...entries].sort((a, b) => {
+    const posA = a.position ?? Number.POSITIVE_INFINITY
+    const posB = b.position ?? Number.POSITIVE_INFINITY
+    if (posA !== posB) return posA - posB
+    return a.title.localeCompare(b.title)
+  })
+
+  // Include full content of each document
+  for (const entry of sortedEntries) {
+    const url = new URL(entry.path, baseUrl).toString()
+    lines.push(`## ${entry.title}`)
+    lines.push('')
+    lines.push(`URL: ${url}`)
+    lines.push('')
+    if (entry.content) {
+      lines.push(entry.content.trim())
+      lines.push('')
+    }
+    lines.push('---')
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}