@levino/shipyard-docs 0.8.4 → 0.8.5-rc-20260529092234

package/astro/DocsEntry.astro

@@ -5,41 +5,17 @@ import { docsConfigs } from 'virtual:shipyard-docs-configs'
 import { getEditUrl, getGitMetadata } from '../src/gitMetadata'
 import Layout from './Layout.astro'
 
-export async function getStaticPaths() {
-  // Get all configured docs collections
-  const allPaths = await Promise.all(
-    Object.entries(docsConfigs).map(async ([basePath, config]) => {
-      const docs = await getCollection(config.collectionName as CollectionKey)
-
-      const getParams = (slug: string) => {
-        if (i18n) {
-          const [locale, ...rest] = slug.split('/')
-          return {
-            slug: rest.length ? rest.join('/') : undefined,
-            locale,
-          }
-        } else {
-          // For non-i18n, treat the entire slug as the path
-          return {
-            slug: slug || undefined,
-          }
-        }
-      }
-
-      return docs.map((doc) => ({
-        params: getParams(doc.id),
-        props: { entry: doc, routeBasePath: basePath },
-      }))
-    }),
-  )
-
-  return allPaths.flat()
+interface Props {
+  entry?: Awaited<ReturnType<typeof getCollection>>[number]
+  routeBasePath?: string
+  collectionName?: string
+  version?: string
+  actualVersion?: string
+  isLatestAlias?: boolean
+  docLocale?: string
 }
 
-// For your template, you can get the entry directly from the prop
-const { entry, routeBasePath } = Astro.props
-
-// Get the config for this specific docs instance
+const routeBasePath = Astro.props.routeBasePath ?? 'docs'
 const docsConfig = docsConfigs[routeBasePath] ??
   docsConfigs.docs ?? {
     showLastUpdateTime: false,
@@ -47,20 +23,88 @@ const docsConfig = docsConfigs[routeBasePath] ??
     routeBasePath: 'docs',
     collectionName: 'docs',
   }
+const collectionName = Astro.props.collectionName ?? docsConfig.collectionName
+
+// The /latest/ alias redirect is handled by the route wrapper
+// (astro/pages/DocsEntry.astro) before this component renders, because a
+// Response returned from a child component is not used as the page response.
+
+// In SSR mode (prerender: false), getStaticPaths is not called so Astro.props
+// will be empty. We need to fetch the entry from the collection based on URL
+// params.
+let { entry } = Astro.props
+const { slug: pageSlug, locale, version: urlVersion } = Astro.params
+
+if (!entry) {
+  const allDocs = await getCollection(collectionName as CollectionKey)
+  const docs = allDocs.filter((doc) => doc.data.render !== false)
+
+  // Reconstruct the entry ID from URL params
+  let entryId: string
+  if (i18n && locale) {
+    // For versioned docs, include version in the entry ID
+    if (urlVersion) {
+      entryId = pageSlug
+        ? `${urlVersion}/${locale}/${pageSlug}`
+        : `${urlVersion}/${locale}`
+    } else {
+      entryId = pageSlug ? `${locale}/${pageSlug}` : locale
+    }
+  } else {
+    if (urlVersion) {
+      entryId = pageSlug ? `${urlVersion}/${pageSlug}` : urlVersion
+    } else {
+      entryId = pageSlug ?? ''
+    }
+  }
+
+  // Find the matching entry
+  entry = docs.find((doc) => doc.id === entryId)
+
+  // If no exact match, try matching with /index suffix (for index pages)
+  // For empty entryId (root path like /docs), look for 'index'
+  // For category paths (like /docs/details), look for 'details/index'
+  if (!entry) {
+    const indexEntryId = entryId ? `${entryId}/index` : 'index'
+    entry = docs.find((doc) => doc.id === indexEntryId)
+  }
+
+  // If still no match, return 404
+  if (!entry) {
+    return Astro.redirect('/404')
+  }
+}
 
 const { Content, headings } = await render(entry)
 
-// Get frontmatter data for per-page overrides
-const { custom_edit_url, last_update_author, last_update_time } = entry.data
+const {
+  customEditUrl,
+  lastUpdateAuthor,
+  lastUpdateTime,
+  hideTableOfContents,
+  hideTitle,
+  keywords,
+  image,
+  canonicalUrl,
+  customMetaTags,
+  title,
+  title_meta,
+  description,
+} = entry.data
+
+// Use title_meta for the <title>/og:title if provided, otherwise fall back to
+// the reference title. Without this fallback, docs pages that only define
+// `title` render an empty <title>/og:title and broken social previews.
+const titleMeta = title_meta ?? title
 
 // Compute edit URL
 let editUrl: string | undefined
-if (custom_edit_url === null) {
+if (customEditUrl === null) {
   // Explicitly disabled for this page
   editUrl = undefined
-} else if (custom_edit_url) {
+} else if (customEditUrl) {
   // Custom URL provided
-  editUrl = custom_edit_url
+  editUrl = customEditUrl
 } else if (entry.filePath) {
   // Use filePath instead of entry.id because Astro's glob loader
   // strips "index" from entry.id for index pages (e.g., en/index -> en)
@@ -80,35 +124,45 @@ let lastUpdated: Date | undefined
 let lastAuthor: string | undefined
 
 if (
-  (docsConfig.showLastUpdateTime && last_update_time !== false) ||
-  (docsConfig.showLastUpdateAuthor && last_update_author !== false)
+  (docsConfig.showLastUpdateTime && lastUpdateTime !== false) ||
+  (docsConfig.showLastUpdateAuthor && lastUpdateAuthor !== false)
 ) {
-  // We need to get the file path for git metadata
-  // The entry.filePath gives us the absolute path to the markdown file
   const filePath = entry.filePath
 
   if (filePath) {
     const gitMetadata = getGitMetadata(filePath)
 
-    // Use frontmatter override or git metadata for timestamp
-    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
     }
 
-    // Use frontmatter override or git metadata for author
-    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}
+  description={description}
+>
   <Content />
 </Layout>

package/astro/pages/DocsEntry.astro

@@ -0,0 +1,71 @@
+---
+import { i18n } from 'astro:config/server'
+import { type CollectionKey, getCollection } from 'astro:content'
+import { docsConfigs } from 'virtual:shipyard-docs-configs'
+import type { GetStaticPaths } from 'astro'
+import {
+  buildLatestAliasRedirect,
+  computeDocsEntryPaths,
+  getDocsInstanceConfig,
+  renderLatestAliasRedirectHtml,
+} from '../../src/docsStaticPaths'
+import DocsEntry from '../DocsEntry.astro'
+
+export const getStaticPaths = (async ({ routePattern }) => {
+  const instance = getDocsInstanceConfig(routePattern, docsConfigs)
+  const allDocs = await getCollection(instance.collectionName as CollectionKey)
+  const docs = allDocs.filter((doc) => doc.data.render !== false)
+  return computeDocsEntryPaths(docs, {
+    collectionName: instance.collectionName,
+    routeBasePath: instance.routeBasePath,
+    versions: instance.versions,
+    hasI18n: !!i18n,
+  })
+}) satisfies GetStaticPaths
+
+// getStaticPaths runs in a separate module scope, so derive the instance again
+// here from the route pattern to resolve collectionName/routeBasePath.
+const instance = getDocsInstanceConfig(Astro.routePattern, docsConfigs)
+const resolvedCollectionName =
+  Astro.props.collectionName ?? instance.collectionName
+const resolvedRouteBasePath =
+  Astro.props.routeBasePath ?? instance.routeBasePath
+
+// SEO-friendly redirect for prerendered /latest/ alias URLs to canonical
+// version URLs. This must happen in the page (route) component — a Response
+// returned from a child component is not used as the page response.
+const { slug: pageSlug } = Astro.params
+const redirectInfo = buildLatestAliasRedirect({
+  isLatestAlias: Astro.props.isLatestAlias,
+  actualVersion: Astro.props.actualVersion,
+  routeBasePath: resolvedRouteBasePath,
+  docLocale: Astro.props.docLocale,
+  pageSlug: typeof pageSlug === 'string' ? pageSlug : undefined,
+})
+
+if (redirectInfo) {
+  const canonicalHref = Astro.site
+    ? new URL(redirectInfo.targetUrl, Astro.site).href
+    : redirectInfo.targetUrl
+  return new Response(
+    renderLatestAliasRedirectHtml(
+      redirectInfo.targetUrl,
+      redirectInfo.fromUrl,
+      canonicalHref,
+    ),
+    {
+      status: 301,
+      headers: {
+        'Content-Type': 'text/html; charset=utf-8',
+        Location: redirectInfo.targetUrl,
+      },
+    },
+  )
+}
+---
+
+<DocsEntry
+  {...Astro.props}
+  routeBasePath={resolvedRouteBasePath}
+  collectionName={resolvedCollectionName}
+/>

package/astro/pages/DocsVersionRedirect.astro

@@ -0,0 +1,28 @@
+---
+import { i18n } from 'astro:config/server'
+import { docsConfigs } from 'virtual:shipyard-docs-configs'
+import type { GetStaticPaths } from 'astro'
+import {
+  getDocsInstanceConfig,
+  getDocsRedirectPaths,
+} from '../../src/docsStaticPaths'
+
+export const getStaticPaths = (() => {
+  return getDocsRedirectPaths(i18n)
+}) satisfies GetStaticPaths
+
+const instance = getDocsInstanceConfig(Astro.routePattern, docsConfigs)
+const routeBasePath = instance.routeBasePath
+const versions = instance.versions
+const currentVersionPath =
+  versions?.available.find((v) => v.version === versions.current)?.path ??
+  versions?.current
+
+const { locale } = Astro.params
+
+const targetUrl = locale
+  ? `/${locale}/${routeBasePath}/${currentVersionPath}/`
+  : `/${routeBasePath}/${currentVersionPath}/`
+
+return Astro.redirect(targetUrl, 302)
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-docs",
-  "version": "0.8.4",
+  "version": "0.8.5-rc-20260529092234",
   "description": "Documentation plugin for shipyard with automatic sidebar, pagination, and git metadata",
   "type": "module",
   "main": "src/index.ts",
@@ -27,7 +27,7 @@
     "effect": "^3.20.0",
     "ramda": "^0.31",
     "unist-util-visit": "^5.0.0",
-    "@levino/shipyard-base": "^0.8.4"
+    "@levino/shipyard-base": "0.8.5-rc-20260529092234"
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.16",

package/src/docsStaticPaths.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest'
+import {
+  computeDocsEntryPaths,
+  type DocsConfigsRegistry,
+  type DocsEntryLike,
+  getDocsInstanceConfig,
+} from './docsStaticPaths'
+import type { VersionConfig } from './index'
+
+const makeConfig = (
+  routeBasePath: string,
+  versions?: VersionConfig,
+): DocsConfigsRegistry[string] => ({
+  showLastUpdateTime: false,
+  showLastUpdateAuthor: false,
+  routeBasePath,
+  collectionName: routeBasePath,
+  llmsTxtEnabled: false,
+  versions,
+})
+
+describe('getDocsInstanceConfig', () => {
+  const registry: DocsConfigsRegistry = {
+    docs: makeConfig('docs'),
+    'api/reference': makeConfig('api/reference'),
+  }
+
+  it('matches non-i18n route pattern', () => {
+    expect(
+      getDocsInstanceConfig('/docs/[...slug]', registry).routeBasePath,
+    ).toBe('docs')
+  })
+
+  it('matches i18n route pattern', () => {
+    expect(
+      getDocsInstanceConfig('/[locale]/docs/[...slug]', registry).routeBasePath,
+    ).toBe('docs')
+  })
+
+  it('matches multi-segment basePath', () => {
+    expect(
+      getDocsInstanceConfig('/api/reference/[...slug]', registry).routeBasePath,
+    ).toBe('api/reference')
+  })
+
+  it('matches multi-segment basePath with i18n', () => {
+    expect(
+      getDocsInstanceConfig('/[locale]/api/reference/[...slug]', registry)
+        .routeBasePath,
+    ).toBe('api/reference')
+  })
+
+  it('matches versioned route pattern', () => {
+    expect(
+      getDocsInstanceConfig('/docs/[version]/[...slug]', registry)
+        .routeBasePath,
+    ).toBe('docs')
+  })
+
+  it('matches the bare basePath pattern (redirect route)', () => {
+    expect(
+      getDocsInstanceConfig('/[locale]/docs', registry).routeBasePath,
+    ).toBe('docs')
+  })
+
+  it('throws when no instance matches', () => {
+    expect(() => getDocsInstanceConfig('/blog/[...slug]', registry)).toThrow(
+      /No docs instance found/,
+    )
+  })
+})
+
+describe('computeDocsEntryPaths', () => {
+  const docs: DocsEntryLike[] = [
+    { id: 'getting-started', data: {} },
+    { id: 'guides/intro', data: {} },
+    { id: 'hidden', data: { render: false } },
+  ]
+
+  it('computes non-i18n paths', () => {
+    const paths = computeDocsEntryPaths(docs, {
+      collectionName: 'docs',
+      routeBasePath: 'docs',
+      hasI18n: false,
+    })
+    expect(paths).toHaveLength(2)
+    expect(paths[0].params).toEqual({ slug: 'getting-started' })
+    expect(paths[0].props.routeBasePath).toBe('docs')
+    expect(paths[0].props.isLatestAlias).toBe(false)
+    expect(paths[1].params).toEqual({ slug: 'guides/intro' })
+  })
+
+  it('computes i18n paths with locale + slug split', () => {
+    const i18nDocs: DocsEntryLike[] = [
+      { id: 'en/getting-started', data: {} },
+      // Astro's glob loader strips "index" so an index page has id "en"
+      { id: 'en', data: {} },
+    ]
+    const paths = computeDocsEntryPaths(i18nDocs, {
+      collectionName: 'docs',
+      routeBasePath: 'docs',
+      hasI18n: true,
+    })
+    expect(paths).toHaveLength(2)
+    expect(paths[0].params).toEqual({ locale: 'en', slug: 'getting-started' })
+    expect(paths[0].props.docLocale).toBe('en')
+    // "en" (locale-root index) -> slug undefined
+    expect(paths[1].params).toEqual({ locale: 'en', slug: undefined })
+  })
+
+  it('generates a latest alias for current-version docs', () => {
+    const versions: VersionConfig = {
+      current: 'v2.0',
+      available: [
+        { version: 'v2.0', path: 'v2' },
+        { version: 'v1.0', path: 'v1' },
+      ],
+      deprecated: [],
+    }
+    const versionedDocs: DocsEntryLike[] = [
+      { id: 'v2.0/en/getting-started', data: {} },
+      { id: 'v1.0/en/getting-started', data: {} },
+    ]
+    const paths = computeDocsEntryPaths(versionedDocs, {
+      collectionName: 'docs',
+      routeBasePath: 'docs',
+      versions,
+      hasI18n: true,
+    })
+
+    // v2.0 doc -> main (version path 'v2') + latest alias
+    // v1.0 doc -> main only ('v1')
+    expect(paths).toHaveLength(3)
+
+    const v2Main = paths.find(
+      (p) => p.params.version === 'v2' && !p.props.isLatestAlias,
+    )
+    expect(v2Main).toBeDefined()
+    expect(v2Main?.params).toEqual({
+      locale: 'en',
+      slug: 'getting-started',
+      version: 'v2',
+    })
+
+    const latestAlias = paths.find((p) => p.props.isLatestAlias)
+    expect(latestAlias).toBeDefined()
+    expect(latestAlias?.params.version).toBe('latest')
+    expect(latestAlias?.props.actualVersion).toBe('v2')
+
+    const v1Main = paths.find((p) => p.params.version === 'v1')
+    expect(v1Main).toBeDefined()
+    expect(v1Main?.props.isLatestAlias).toBe(false)
+  })
+})

package/src/docsStaticPaths.ts

@@ -0,0 +1,226 @@
+import type { VersionConfig } from './index'
+import { createVersionPathMap } from './routeHelpers'
+import { getVersionFromDocId, stripVersionFromDocId } from './versionHelpers'
+
+/**
+ * Minimal shape of a docs collection entry needed for path computation.
+ */
+export interface DocsEntryLike {
+  id: string
+  data: {
+    render?: boolean
+  }
+}
+
+interface I18nConfig {
+  locales: (string | { codes: string[] })[]
+}
+
+/**
+ * Shape of a single docs instance config stored in the
+ * `virtual:shipyard-docs-configs` registry.
+ */
+export interface DocsInstanceConfig {
+  editUrl?: string
+  showLastUpdateTime: boolean
+  showLastUpdateAuthor: boolean
+  routeBasePath: string
+  collectionName: string
+  llmsTxtEnabled: boolean
+  versions?: VersionConfig
+}
+
+export type DocsConfigsRegistry = Record<string, DocsInstanceConfig>
+
+/**
+ * Resolve which docs instance a given route pattern belongs to.
+ *
+ * Mirrors the blog package's `getInstanceConfig`: strips an optional
+ * `/[locale]/` prefix and the leading slash, then matches against the known
+ * basePaths in the registry. basePaths may contain slashes (e.g.
+ * `api/reference`), so we match against registered keys rather than splitting
+ * on `/`.
+ */
+export const getDocsInstanceConfig = (
+  routePattern: string,
+  docsConfigs: DocsConfigsRegistry,
+): DocsInstanceConfig => {
+  const stripped = routePattern.replace(/^\/?(\[locale\]\/)?/, '')
+  for (const [basePath, config] of Object.entries(docsConfigs)) {
+    if (stripped === basePath || stripped.startsWith(`${basePath}/`)) {
+      return config
+    }
+  }
+  throw new Error(`No docs instance found for route pattern: ${routePattern}`)
+}
+
+export interface ComputeDocsEntryPathsOptions {
+  collectionName: string
+  routeBasePath: string
+  versions?: VersionConfig | null
+  hasI18n: boolean
+}
+
+/**
+ * Compute the static paths for the DocsEntry route.
+ *
+ * Behaviour is identical to the previously generated `getStaticPaths`:
+ * - one main path per rendered doc
+ * - for versioned docs that belong to the current version, an additional
+ *   `latest` alias path that redirects to the canonical version URL
+ */
+export const computeDocsEntryPaths = (
+  allDocs: readonly DocsEntryLike[],
+  {
+    collectionName: _collectionName,
+    routeBasePath,
+    versions,
+    hasI18n,
+  }: ComputeDocsEntryPathsOptions,
+) => {
+  const hasVersions = !!versions
+  const docs = allDocs.filter((doc) => doc.data.render !== false)
+
+  const versionPathMap =
+    hasVersions && versions ? createVersionPathMap(versions) : null
+
+  const getParams = (slug: string, version?: string) => {
+    if (hasI18n) {
+      const [locale, ...rest] = slug.split('/')
+      const baseParams = {
+        slug: rest.length ? rest.join('/') : undefined,
+        locale,
+      }
+      return version ? { ...baseParams, version } : baseParams
+    }
+    const baseParams = {
+      slug: slug || undefined,
+    }
+    return version ? { ...baseParams, version } : baseParams
+  }
+
+  const paths: {
+    params: Record<string, string | undefined>
+    props: {
+      entry: DocsEntryLike
+      routeBasePath: string
+      version?: string
+      actualVersion?: string
+      isLatestAlias: boolean
+      docLocale?: string
+    }
+  }[] = []
+
+  for (const entry of docs) {
+    let version: string | undefined
+    let docIdWithoutVersion = entry.id
+
+    if (hasVersions && versions && versionPathMap) {
+      const extractedVersion = getVersionFromDocId(entry.id)
+      if (extractedVersion) {
+        version = versionPathMap.get(extractedVersion) ?? extractedVersion
+        docIdWithoutVersion = stripVersionFromDocId(entry.id)
+      }
+    }
+
+    const docLocale = hasI18n ? docIdWithoutVersion.split('/')[0] : undefined
+
+    paths.push({
+      params: getParams(docIdWithoutVersion, version),
+      props: {
+        entry,
+        routeBasePath,
+        version,
+        isLatestAlias: false,
+        docLocale,
+      },
+    })
+
+    if (hasVersions && versions && version) {
+      const extractedVersion = getVersionFromDocId(entry.id)
+      const currentVersion = versions.current
+      if (extractedVersion === currentVersion) {
+        paths.push({
+          params: getParams(docIdWithoutVersion, 'latest'),
+          props: {
+            entry,
+            routeBasePath,
+            version: 'latest',
+            actualVersion: version,
+            isLatestAlias: true,
+            docLocale,
+          },
+        })
+      }
+    }
+  }
+
+  return paths
+}
+
+export interface LatestAliasRedirectInput {
+  isLatestAlias?: boolean
+  actualVersion?: string
+  routeBasePath: string
+  docLocale?: string
+  pageSlug?: string
+}
+
+/**
+ * Build the SEO-friendly redirect descriptor for a `/latest/` alias URL.
+ * Returns `null` when the current request is not a latest alias.
+ *
+ * The `/latest/` alias paths are only generated as static paths (props come
+ * from getStaticPaths), so this is driven entirely by props — SSR requests
+ * never carry `isLatestAlias`.
+ */
+export const buildLatestAliasRedirect = ({
+  isLatestAlias,
+  actualVersion,
+  routeBasePath,
+  docLocale,
+  pageSlug,
+}: LatestAliasRedirectInput): { targetUrl: string; fromUrl: string } | null => {
+  if (!isLatestAlias || !actualVersion) return null
+  const targetUrl = docLocale
+    ? pageSlug
+      ? `/${docLocale}/${routeBasePath}/${actualVersion}/${pageSlug}`
+      : `/${docLocale}/${routeBasePath}/${actualVersion}/`
+    : pageSlug
+      ? `/${routeBasePath}/${actualVersion}/${pageSlug}`
+      : `/${routeBasePath}/${actualVersion}/`
+  const fromUrl = docLocale
+    ? pageSlug
+      ? `/${docLocale}/${routeBasePath}/latest/${pageSlug}`
+      : `/${docLocale}/${routeBasePath}/latest/`
+    : pageSlug
+      ? `/${routeBasePath}/latest/${pageSlug}`
+      : `/${routeBasePath}/latest/`
+  return { targetUrl, fromUrl }
+}
+
+/**
+ * Render the minimal redirect HTML page body for a latest-alias redirect.
+ */
+export const renderLatestAliasRedirectHtml = (
+  targetUrl: string,
+  fromUrl: string,
+  canonicalHref: string,
+): string =>
+  `<!doctype html><title>Redirecting to: ${targetUrl}</title><meta http-equiv="refresh" content="0;url=${targetUrl}"><meta name="robots" content="noindex"><link rel="canonical" href="${canonicalHref}"><body>\t<a href="${targetUrl}">Redirecting from <code>${fromUrl}</code> to <code>${targetUrl}</code></a></body>`
+
+/**
+ * Compute static paths for the versioned-root redirect route.
+ * Returns one path per locale when i18n is enabled, else a single empty path.
+ */
+export const getDocsRedirectPaths = (
+  i18n: I18nConfig | null | undefined | false,
+) => {
+  if (i18n) {
+    return i18n.locales.map((locale) => {
+      const localeCode = typeof locale === 'string' ? locale : locale.codes[0]
+      return { params: { locale: localeCode } }
+    })
+  }
+  return [{ params: {} }]
+}

package/src/index.ts

@@ -824,260 +824,19 @@ export default (config: DocsConfig = {}): AstroIntegration => {
             ? prerenderConfig
             : astroConfig.output !== 'server'
 
-        // Create a generated entry file for this specific docs instance
-        // This ensures each route has its own getStaticPaths that only returns its own paths
+        // Directory for generated JS/TS route files (llms.txt endpoints).
+        // No .astro files are generated as strings anymore — the docs entry and
+        // version-redirect routes ship as real .astro files under astro/pages.
         const generatedDir = join(
           astroConfig.root?.pathname || process.cwd(),
           'node_modules',
           '.shipyard-docs',
         )
 
-        if (!existsSync(generatedDir)) {
-          mkdirSync(generatedDir, { recursive: true })
-        }
-
-        const entryFileName = `DocsEntry-${normalizedBasePath}.astro`
-        const entryFilePath = join(generatedDir, entryFileName)
-
-        // Generate the entry file with the correct routeBasePath and collectionName
-        // Note: We inline the values directly in getStaticPaths because Astro's compiler
-        // hoists getStaticPaths to a separate module context where top-level constants aren't available
-        const hasVersions = !!versions
-        const entryFileContent = `---
-import { i18n } from 'astro:config/server'
-import { getCollection, render } from 'astro:content'
-import { docsConfigs } from 'virtual:shipyard-docs-configs'
-import { createVersionPathMap, getEditUrl, getGitMetadata, getVersionFromDocId, stripVersionFromDocId } from '@levino/shipyard-docs'
-import Layout from '@levino/shipyard-docs/astro/Layout.astro'
-
-const collectionName = ${JSON.stringify(resolvedCollectionName)}
-const routeBasePath = ${JSON.stringify(normalizedBasePath)}
-
-export async function getStaticPaths() {
-  // Note: collectionName and routeBasePath must be inlined here because Astro compiles
-  // getStaticPaths separately and module-level constants are not available
-  const collectionName = ${JSON.stringify(resolvedCollectionName)}
-  const routeBasePath = ${JSON.stringify(normalizedBasePath)}
-  const hasVersions = ${JSON.stringify(hasVersions)}
-  const versionsConfig = ${JSON.stringify(versions || null)}
-  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)
-
-  // Pre-compute version path map for O(1) lookups instead of O(V) per document
-  const versionPathMap = hasVersions && versionsConfig
-    ? createVersionPathMap(versionsConfig)
-    : null
-
-  const getParams = (slug, version) => {
-    if (i18n) {
-      const [locale, ...rest] = slug.split('/')
-      const baseParams = {
-        slug: rest.length ? rest.join('/') : undefined,
-        locale,
-      }
-      return version ? { ...baseParams, version } : baseParams
-    } else {
-      const baseParams = {
-        slug: slug || undefined,
-      }
-      return version ? { ...baseParams, version } : baseParams
-    }
-  }
-
-  const paths = []
-
-  for (const entry of docs) {
-    // For versioned docs, extract version from the doc ID (e.g., "v1.0/en/getting-started")
-    let version = null
-    let docIdWithoutVersion = entry.id
-
-    if (hasVersions && versionsConfig && versionPathMap) {
-      const extractedVersion = getVersionFromDocId(entry.id)
-      if (extractedVersion) {
-        // Use pre-computed map for O(1) lookup instead of array.find()
-        version = versionPathMap.get(extractedVersion) ?? extractedVersion
-        docIdWithoutVersion = stripVersionFromDocId(entry.id)
-      }
-    }
-
-    // Extract locale from docIdWithoutVersion for i18n builds
-    const docLocale = i18n ? docIdWithoutVersion.split('/')[0] : undefined
-
-    // Add the main path for this doc
-    paths.push({
-      params: getParams(docIdWithoutVersion, version),
-      props: { entry, routeBasePath, version, isLatestAlias: false, docLocale },
-    })
-
-    // If this doc is in the current version, also generate a 'latest' alias path that redirects
-    if (hasVersions && versionsConfig && version) {
-      const extractedVersion = getVersionFromDocId(entry.id)
-      const currentVersion = versionsConfig.current
-      if (extractedVersion === currentVersion) {
-        paths.push({
-          params: getParams(docIdWithoutVersion, 'latest'),
-          props: { entry, routeBasePath, version: 'latest', actualVersion: version, isLatestAlias: true, docLocale },
-        })
-      }
-    }
-  }
-
-  return paths
-}
-
-// In SSR mode (prerender: false), getStaticPaths is not called so Astro.props.entry will be undefined.
-// We need to fetch the entry from the collection based on URL params.
-let { entry, routeBasePath: propsRouteBasePath, version, actualVersion, isLatestAlias, docLocale } = Astro.props
-const { slug: pageSlug, locale, version: urlVersion } = Astro.params
-
-// SSR mode: fetch entry dynamically when props are not available from getStaticPaths
-if (!entry) {
-  const allDocs = await getCollection(collectionName)
-  const docs = allDocs.filter((doc) => doc.data.render !== false)
-
-  // Reconstruct the entry ID from URL params
-  let entryId
-  if (i18n && locale) {
-    // For versioned docs, include version in the entry ID
-    if (urlVersion) {
-      entryId = pageSlug ? urlVersion + '/' + locale + '/' + pageSlug : urlVersion + '/' + locale
-    } else {
-      entryId = pageSlug ? locale + '/' + pageSlug : locale
-    }
-  } else {
-    if (urlVersion) {
-      entryId = pageSlug ? urlVersion + '/' + pageSlug : urlVersion
-    } else {
-      entryId = pageSlug ?? ''
-    }
-  }
-
-  // Find the matching entry
-  entry = docs.find((doc) => doc.id === entryId)
-
-  // If no exact match, try matching with /index suffix (for index pages)
-  // For empty entryId (root path like /docs), look for 'index'
-  // For category paths (like /docs/details), look for 'details/index'
-  if (!entry) {
-    const indexEntryId = entryId ? entryId + '/index' : 'index'
-    entry = docs.find((doc) => doc.id === indexEntryId)
-  }
-
-  // If still no match, return 404
-  if (!entry) {
-    return Astro.redirect('/404')
-  }
-
-  // Set version from URL params for SSR mode
-  version = urlVersion
-  isLatestAlias = false
-  docLocale = locale
-}
-
-// SEO-friendly redirect for /latest/ URLs to canonical version URLs
-// We handle the redirect inline below since Astro.redirect() doesn't work reliably
-// with i18n fallback pages
-const redirectInfo = isLatestAlias && actualVersion ? {
-  locale: docLocale,
-  targetUrl: docLocale
-    ? (pageSlug
-        ? \`/\${docLocale}/\${routeBasePath}/\${actualVersion}/\${pageSlug}\`
-        : \`/\${docLocale}/\${routeBasePath}/\${actualVersion}/\`)
-    : (pageSlug
-        ? \`/\${routeBasePath}/\${actualVersion}/\${pageSlug}\`
-        : \`/\${routeBasePath}/\${actualVersion}/\`),
-  fromUrl: docLocale
-    ? (pageSlug
-        ? \`/\${docLocale}/\${routeBasePath}/latest/\${pageSlug}\`
-        : \`/\${docLocale}/\${routeBasePath}/latest/\`)
-    : (pageSlug
-        ? \`/\${routeBasePath}/latest/\${pageSlug}\`
-        : \`/\${routeBasePath}/latest/\`),
-} : null
-
-// If this is a redirect, return early with a minimal redirect page
-if (redirectInfo) {
-  return new Response(\`<!doctype html><title>Redirecting to: \${redirectInfo.targetUrl}</title><meta http-equiv="refresh" content="0;url=\${redirectInfo.targetUrl}"><meta name="robots" content="noindex"><link rel="canonical" href="\${Astro.site ? new URL(redirectInfo.targetUrl, Astro.site).href : redirectInfo.targetUrl}"><body>\\t<a href="\${redirectInfo.targetUrl}">Redirecting from <code>\${redirectInfo.fromUrl}</code> to <code>\${redirectInfo.targetUrl}</code></a></body>\`, {
-    status: 301,
-    headers: {
-      'Content-Type': 'text/html; charset=utf-8',
-      'Location': redirectInfo.targetUrl,
-    },
-  })
-}
-
-const docsConfig = docsConfigs[routeBasePath] ?? {
-  showLastUpdateTime: false,
-  showLastUpdateAuthor: false,
-  routeBasePath: 'docs',
-  collectionName: 'docs',
-}
-
-// Version is available for use in Layout/components if needed
-// For 'latest' alias URLs, actualVersion contains the real version
-const currentVersion = isLatestAlias ? actualVersion : version
-const displayVersion = version // The version shown in the URL
-
-const { Content, headings } = await render(entry)
-
-const { customEditUrl, lastUpdateAuthor, lastUpdateTime, hideTableOfContents, hideTitle, keywords, image, canonicalUrl, customMetaTags, title_meta: titleMeta, description } = entry.data
-
-let editUrl
-if (customEditUrl === null) {
-  editUrl = undefined
-} else if (customEditUrl) {
-  editUrl = customEditUrl
-} else if (entry.filePath) {
-  // Use filePath instead of entry.id because Astro's glob loader
-  // strips "index" from entry.id for index pages (e.g., en/index -> en)
-  // Strip the collection base directory to get the relative path
-  const collectionBase = \`\${docsConfig.collectionName}/\`
-  const relativePath = entry.filePath.startsWith(collectionBase)
-    ? entry.filePath.slice(collectionBase.length)
-    : entry.filePath
-  editUrl = getEditUrl(docsConfig.editUrl, relativePath)
-} else {
-  // Fallback to entry.id if filePath is not available
-  editUrl = getEditUrl(docsConfig.editUrl, entry.id)
-}
-
-let lastUpdated
-let lastAuthor
-
-if (
-  (docsConfig.showLastUpdateTime && lastUpdateTime !== false) ||
-  (docsConfig.showLastUpdateAuthor && lastUpdateAuthor !== false)
-) {
-  const filePath = entry.filePath
-
-  if (filePath) {
-    const gitMetadata = getGitMetadata(filePath)
-
-    if (docsConfig.showLastUpdateTime && lastUpdateTime !== false) {
-      lastUpdated =
-        lastUpdateTime instanceof Date
-          ? lastUpdateTime
-          : gitMetadata.lastUpdated
-    }
-
-    if (docsConfig.showLastUpdateAuthor && lastUpdateAuthor !== false) {
-      lastAuthor =
-        typeof lastUpdateAuthor === 'string'
-          ? lastUpdateAuthor
-          : gitMetadata.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} description={description}>
-  <Content />
-</Layout>
-`
-
-        writeFileSync(entryFilePath, entryFileContent)
+        const ENTRYPOINT_DOCS_ENTRY =
+          '@levino/shipyard-docs/astro/pages/DocsEntry.astro'
+        const ENTRYPOINT_DOCS_VERSION_REDIRECT =
+          '@levino/shipyard-docs/astro/pages/DocsVersionRedirect.astro'
 
         // Create virtual modules to expose docs configurations
         updateConfig({
@@ -1172,51 +931,24 @@ export function hasVersioning(routeBasePath = 'docs') {
           // With i18n: use locale prefix
           if (versions) {
             // Versioned routes: /[locale]/[routeBasePath]/[version]/[...slug]
-            // Note: 'latest' alias paths are generated in getStaticPaths and redirect in the frontmatter
+            // Note: 'latest' alias paths are generated in getStaticPaths and redirect in the component
             injectRoute({
               pattern: `/[locale]/${normalizedBasePath}/[version]/[...slug]`,
-              entrypoint: entryFilePath,
+              entrypoint: ENTRYPOINT_DOCS_ENTRY,
               prerender,
             })
 
-            // Generate redirect from docs root to current version
-            const redirectFileName = `docs-redirect-${normalizedBasePath}.astro`
-            const redirectFilePath = join(generatedDir, redirectFileName)
-            const currentVersionPath =
-              versions.available.find((v) => v.version === versions.current)
-                ?.path ?? versions.current
-            const redirectFileContent = `---
-import { i18n } from 'astro:config/server'
-
-export function getStaticPaths() {
-  const locales = i18n?.locales ?? ['en']
-  return locales.map((locale) => {
-    const localeCode = typeof locale === 'string' ? locale : locale.path
-    return { params: { locale: localeCode } }
-  })
-}
-
-const { locale } = Astro.params
-const currentVersion = ${JSON.stringify(currentVersionPath)}
-const routeBasePath = ${JSON.stringify(normalizedBasePath)}
-
-// Redirect to the current version's index
-return Astro.redirect(\`/\${locale}/\${routeBasePath}/\${currentVersion}/\`, 302)
----
-`
-            writeFileSync(redirectFilePath, redirectFileContent)
-
             // Inject redirect route for docs root (without trailing slash)
             injectRoute({
               pattern: `/[locale]/${normalizedBasePath}`,
-              entrypoint: redirectFilePath,
+              entrypoint: ENTRYPOINT_DOCS_VERSION_REDIRECT,
               prerender,
             })
           } else {
             // Non-versioned routes: /[locale]/[routeBasePath]/[...slug]
             injectRoute({
               pattern: `/[locale]/${normalizedBasePath}/[...slug]`,
-              entrypoint: entryFilePath,
+              entrypoint: ENTRYPOINT_DOCS_ENTRY,
               prerender,
             })
           }
@@ -1224,40 +956,24 @@ return Astro.redirect(\`/\${locale}/\${routeBasePath}/\${currentVersion}/\`, 302
           // Without i18n: direct path
           if (versions) {
             // Versioned routes: /[routeBasePath]/[version]/[...slug]
-            // Note: 'latest' alias paths are generated in getStaticPaths and redirect in the frontmatter
+            // Note: 'latest' alias paths are generated in getStaticPaths and redirect in the component
             injectRoute({
               pattern: `/${normalizedBasePath}/[version]/[...slug]`,
-              entrypoint: entryFilePath,
+              entrypoint: ENTRYPOINT_DOCS_ENTRY,
               prerender,
             })
 
-            // Generate redirect from docs root to current version
-            const redirectFileName = `docs-redirect-${normalizedBasePath}.astro`
-            const redirectFilePath = join(generatedDir, redirectFileName)
-            const currentVersionPath =
-              versions.available.find((v) => v.version === versions.current)
-                ?.path ?? versions.current
-            const redirectFileContent = `---
-const currentVersion = ${JSON.stringify(currentVersionPath)}
-const routeBasePath = ${JSON.stringify(normalizedBasePath)}
-
-// Redirect to the current version's index
-return Astro.redirect(\`/\${routeBasePath}/\${currentVersion}/\`, 302)
----
-`
-            writeFileSync(redirectFilePath, redirectFileContent)
-
             // Inject redirect route for docs root (without trailing slash)
             injectRoute({
               pattern: `/${normalizedBasePath}`,
-              entrypoint: redirectFilePath,
+              entrypoint: ENTRYPOINT_DOCS_VERSION_REDIRECT,
               prerender,
             })
           } else {
             // Non-versioned routes: /[routeBasePath]/[...slug]
             injectRoute({
               pattern: `/${normalizedBasePath}/[...slug]`,
-              entrypoint: entryFilePath,
+              entrypoint: ENTRYPOINT_DOCS_ENTRY,
               prerender,
             })
           }
@@ -1272,6 +988,11 @@ return Astro.redirect(\`/\${routeBasePath}/\${currentVersion}/\`, 302)
             sectionTitle: llmsTxt.sectionTitle ?? 'Documentation',
           }
 
+          // Ensure the directory for generated JS/TS endpoints exists
+          if (!existsSync(generatedDir)) {
+            mkdirSync(generatedDir, { recursive: true })
+          }
+
           // Generate individual plain text endpoints for each doc page
           // These are mounted at /_llms-txt/[slug].txt
           const llmsTxtPagesFileName = `llms-txt-pages-${normalizedBasePath}.ts`