@raystack/chronicle 0.5.4 → 0.6.1

package/src/server/api/search.ts

@@ -1,10 +1,11 @@
 import MiniSearch from 'minisearch';
-import { defineHandler } from 'nitro';
+import { defineHandler, HTTPError } from 'nitro';
 import type { OpenAPIV3 } from 'openapi-types';
 import { getSpecSlug } from '@/lib/api-routes';
-import { loadConfig } from '@/lib/config';
+import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
-import { getPages, extractFrontmatter } from '@/lib/source';
+import { extractFrontmatter, getPagesForVersion } from '@/lib/source';
+import { LATEST_CONTEXT, type VersionContext } from '@/lib/version-source';
 
 interface SearchDocument {
   id: string;
@@ -14,8 +15,12 @@ interface SearchDocument {
   type: 'page' | 'api';
 }
 
-let searchIndex: MiniSearch<SearchDocument> | null = null;
-let cachedDocs: SearchDocument[] | null = null;
+const indexCache = new Map<string, MiniSearch<SearchDocument>>();
+const docsCache = new Map<string, SearchDocument[]>();
+
+function keyFor(ctx: VersionContext): string {
+  return ctx.dir ?? '__latest__';
+}
 
 function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
   const index = new MiniSearch<SearchDocument>({
@@ -31,8 +36,8 @@ function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
   return index;
 }
 
-async function scanContent(): Promise<SearchDocument[]> {
-  const pages = await getPages();
+async function scanContent(ctx: VersionContext): Promise<SearchDocument[]> {
+  const pages = await getPagesForVersion(ctx);
   return pages.map(p => {
     const fm = extractFrontmatter(p);
     return {
@@ -45,12 +50,13 @@ async function scanContent(): Promise<SearchDocument[]> {
   });
 }
 
-async function buildApiDocs(): Promise<SearchDocument[]> {
+async function buildApiDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   const config = loadConfig();
-  if (!config.api?.length) return [];
+  const apiConfigs = getApiConfigsForVersion(config, ctx.dir);
+  if (!apiConfigs.length) return [];
 
   const docs: SearchDocument[] = [];
-  const specs = await loadApiSpecs(config.api);
+  const specs = await loadApiSpecs(apiConfigs);
 
   for (const spec of specs) {
     const specSlug = getSpecSlug(spec);
@@ -60,7 +66,7 @@ async function buildApiDocs(): Promise<SearchDocument[]> {
       for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
         const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
         if (!op?.operationId) continue;
-        const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
+        const url = `${ctx.urlPrefix}/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
         docs.push({
           id: url,
           url,
@@ -75,29 +81,50 @@ async function buildApiDocs(): Promise<SearchDocument[]> {
   return docs;
 }
 
-async function getDocs(): Promise<SearchDocument[]> {
-  if (cachedDocs) return cachedDocs;
+async function getDocs(ctx: VersionContext): Promise<SearchDocument[]> {
+  const key = keyFor(ctx);
+  const cached = docsCache.get(key);
+  if (cached) return cached;
   const [contentDocs, apiDocs] = await Promise.all([
-    scanContent(),
-    buildApiDocs()
+    scanContent(ctx),
+    buildApiDocs(ctx)
   ]);
-  cachedDocs = [...contentDocs, ...apiDocs];
-  return cachedDocs;
+  const docs = [...contentDocs, ...apiDocs];
+  docsCache.set(key, docs);
+  return docs;
+}
+
+async function getIndex(ctx: VersionContext): Promise<MiniSearch<SearchDocument>> {
+  const key = keyFor(ctx);
+  const cached = indexCache.get(key);
+  if (cached) return cached;
+  const docs = await getDocs(ctx);
+  const index = createIndex(docs);
+  indexCache.set(key, index);
+  return index;
 }
 
-async function getIndex(): Promise<MiniSearch<SearchDocument>> {
-  if (searchIndex) return searchIndex;
-  const docs = await getDocs();
-  searchIndex = createIndex(docs);
-  return searchIndex;
+function resolveCtx(tag: string | null): VersionContext {
+  if (!tag) return LATEST_CONTEXT;
+  const config = loadConfig();
+  const version = config.versions?.find(v => v.dir === tag);
+  if (!version) {
+    throw new HTTPError({
+      status: 400,
+      message: `Unknown version tag: ${tag}`,
+    });
+  }
+  return { dir: version.dir, urlPrefix: `/${version.dir}` };
 }
 
 export default defineHandler(async event => {
   const query = event.url.searchParams.get('query') ?? '';
-  const index = await getIndex();
+  const tag = event.url.searchParams.get('tag');
+  const ctx = resolveCtx(tag);
+  const index = await getIndex(ctx);
 
   if (!query) {
-    const docs = await getDocs();
+    const docs = await getDocs(ctx);
     return docs
       .filter(d => d.type === 'page')
       .slice(0, 8)

package/src/server/api/specs.ts

@@ -1,9 +1,21 @@
-import { defineHandler } from 'nitro';
-import { loadConfig } from '@/lib/config';
+import { defineHandler, HTTPError } from 'nitro';
+import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 
-export default defineHandler(async () => {
+export default defineHandler(async event => {
+  const versionParam = event.url.searchParams.get('version');
+  const versionDir = versionParam === null || versionParam === '' ? null : versionParam;
+
   const config = loadConfig();
-  const specs = config.api?.length ? await loadApiSpecs(config.api) : [];
-  return specs;
+  if (versionDir && !config.versions?.some(v => v.dir === versionDir)) {
+    throw new HTTPError({
+      status: 400,
+      message: `Unknown version: ${versionDir}`,
+    });
+  }
+
+  const apiConfigs = getApiConfigsForVersion(config, versionDir);
+  if (!apiConfigs.length) return [];
+
+  return loadApiSpecs(apiConfigs);
 });

package/src/server/entry-client.tsx

@@ -4,8 +4,11 @@ import { hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router';
 import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
 import { mdxComponents } from '@/components/mdx';
+import { getApiConfigsForVersion } from '@/lib/config';
 import { PageProvider } from '@/lib/page-context';
-import type { ChronicleConfig, Frontmatter, Root, TableOfContents } from '@/types';
+import { resolveRoute, RouteType } from '@/lib/route-resolver';
+import { resolveVersionFromUrl, type VersionContext } from '@/lib/version-source';
+import type { ChronicleConfig, Frontmatter, PageNavLink, Root, TableOfContents } from '@/types';
 import type { ApiSpec } from '@/lib/openapi';
 import type { ReactNode } from 'react';
 import { App } from './App';
@@ -14,11 +17,19 @@ interface EmbeddedData {
   config: ChronicleConfig;
   tree: Root;
   slug: string[];
-  frontmatter: Frontmatter;
-  relativePath: string;
-  originalPath?: string;
+  version: VersionContext;
+  frontmatter: Frontmatter | null;
+  relativePath: string | null;
+  originalPath: string | null;
+  prev: PageNavLink | null;
+  next: PageNavLink | null;
 }
 
+const defaultConfig: ChronicleConfig = {
+  site: { title: 'Documentation' },
+  content: [{ dir: 'docs', label: 'Docs' }],
+};
+
 const contentModules = import.meta.glob<{ default?: React.ComponentType<any>; toc?: TableOfContents }>(
   '../../.content/**/*.{mdx,md}'
 );
@@ -43,23 +54,39 @@ async function hydrate() {
       window as unknown as { __PAGE_DATA__?: EmbeddedData }
     ).__PAGE_DATA__;
 
-    const config: ChronicleConfig = embedded?.config ?? {
-      title: 'Documentation'
-    };
+    const config: ChronicleConfig = embedded?.config ?? defaultConfig;
     const tree: Root = embedded?.tree ?? { name: 'root', children: [] };
-    const isApiPage =
-      window.location.pathname.startsWith('/apis') && !!config.api?.length;
-    const apiSpecs: ApiSpec[] = isApiPage
-      ? await fetch('/api/specs')
+
+    const route = resolveRoute(window.location.pathname, config);
+    // resolveVersionFromUrl always returns a valid context — even for redirect
+    // targets (e.g. /v1 -> /v1/docs) where route.version isn't on the union.
+    const routeVersion: VersionContext = resolveVersionFromUrl(
+      window.location.pathname,
+      config,
+    );
+    const version: VersionContext = embedded?.version ?? routeVersion;
+
+    const isApiRoute =
+      route.type === RouteType.ApiIndex || route.type === RouteType.ApiPage;
+    const apiConfigs = isApiRoute
+      ? getApiConfigsForVersion(config, routeVersion.dir)
+      : [];
+    const specsUrl = routeVersion.dir
+      ? `/api/specs?version=${encodeURIComponent(routeVersion.dir)}`
+      : '/api/specs';
+    const apiSpecs: ApiSpec[] = apiConfigs.length
+      ? await fetch(specsUrl)
           .then(r => r.json())
           .catch(() => [])
       : [];
 
     const mdxPath = embedded?.originalPath || embedded?.relativePath;
-    const page = mdxPath
+    const page = embedded && mdxPath && embedded.frontmatter
       ? {
-          slug: embedded!.slug,
-          frontmatter: embedded!.frontmatter,
+          slug: embedded.slug,
+          frontmatter: embedded.frontmatter,
+          prev: embedded.prev,
+          next: embedded.next,
           ...(await loadMdxModule(mdxPath)),
         }
       : null;
@@ -73,6 +100,7 @@ async function hydrate() {
             initialTree={tree}
             initialPage={page}
             initialApiSpecs={apiSpecs}
+            initialVersion={version}
             loadMdx={loadMdxModule}
           >
             <App />

package/src/server/entry-server.tsx

@@ -5,10 +5,11 @@ import { renderToReadableStream } from 'react-dom/server.edge';
 import { StaticRouter } from 'react-router';
 import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
 import { mdxComponents } from '@/components/mdx';
-import { loadConfig } from '@/lib/config';
+import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
-import { getPageTree, getPage, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { resolveRoute, RouteType } from '@/lib/route-resolver';
+import { getPageTree, getPage, getPageNav, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
 import { useNitroApp } from 'nitro/app';
 import { App } from './App';
 
@@ -19,17 +20,32 @@ export default {
   async fetch(req: Request) {
     const url = new URL(req.url);
     const pathname = url.pathname;
-    const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean);
 
     const config = loadConfig();
-    const apiSpecs = config.api?.length
-      ? await loadApiSpecs(config.api).catch(() => [])
+    const route = resolveRoute(pathname, config);
+
+    if (route.type === RouteType.Redirect) {
+      // biome-ignore lint/correctness/useHookAtTopLevel: useNitroApp is a Nitro DI accessor, not a React hook
+      useNitroApp().hooks.callHook('chronicle:ssr-rendered', pathname, route.status, 0);
+      return new Response(null, {
+        status: route.status,
+        headers: { Location: route.to },
+      });
+    }
+
+    const isApiRoute = route.type === RouteType.ApiIndex || route.type === RouteType.ApiPage;
+    const pageSlug = route.type === RouteType.DocsPage ? route.slug : [];
+
+    const apiConfigs = isApiRoute
+      ? getApiConfigsForVersion(config, route.version.dir)
       : [];
+    const apiSpecs = apiConfigs.length ? await loadApiSpecs(apiConfigs) : [];
 
     const [tree, page] = await Promise.all([
       getPageTree(),
-      getPage(slug),
+      route.type === RouteType.DocsPage ? getPage(route.slug) : Promise.resolve(null),
     ]);
+    const nav = page ? await getPageNav(pageSlug, tree) : { prev: null, next: null };
 
     const relativePath = page ? getRelativePath(page) : null;
     const originalPath = page ? getOriginalPath(page) : null;
@@ -37,22 +53,27 @@ export default {
 
     const pageData = page
       ? {
-          slug,
-          frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+          slug: pageSlug,
+          frontmatter: extractFrontmatter(page, pageSlug[pageSlug.length - 1]),
           content: mdxModule?.default
             ? React.createElement(mdxModule.default, { components: mdxComponents })
             : null,
           toc: mdxModule?.toc ?? [],
+          prev: nav.prev,
+          next: nav.next,
         }
       : null;
 
     const embeddedData = {
       config,
       tree,
-      slug,
+      slug: pageSlug,
+      version: route.version,
       frontmatter: pageData?.frontmatter ?? null,
       relativePath,
       originalPath,
+      prev: pageData?.prev ?? null,
+      next: pageData?.next ?? null,
     };
     const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c');
 
@@ -82,6 +103,7 @@ export default {
                   initialTree={tree}
                   initialPage={pageData}
                   initialApiSpecs={apiSpecs}
+                  initialVersion={route.version}
                   loadMdx={async () => ({ content: null, toc: [] })}
                 >
                   <App />
@@ -95,9 +117,9 @@ export default {
 
     const renderDuration = performance.now() - renderStart;
 
-    const isApiRoute = pathname.startsWith('/apis');
-    const status = !page && !isApiRoute && slug.length > 0 ? 404 : 200;
+    const status = route.type === RouteType.DocsPage && !page ? 404 : 200;
 
+    // biome-ignore lint/correctness/useHookAtTopLevel: useNitroApp is a Nitro DI accessor, not a React hook
     useNitroApp().hooks.callHook('chronicle:ssr-rendered', pathname, status, renderDuration);
 
     return new Response(stream, {

package/src/server/routes/[...slug].md.ts

@@ -1,7 +1,6 @@
 import fs from 'node:fs/promises';
 import matter from 'gray-matter';
 import { defineHandler, HTTPError } from 'nitro';
-import { loadConfig } from '@/lib/config';
 import { getPage, getOriginalPath } from '@/lib/source';
 import { safePath } from '@/server/utils/safe-path';
 
@@ -9,11 +8,6 @@ export default defineHandler(async event => {
   const pathname = event.path || event.req.url?.split('?')[0] || '';
   if (!pathname.endsWith('.md')) return;
 
-  const config = loadConfig();
-  if (!config.llms?.enabled) {
-    throw new HTTPError({ status: 404, message: 'Not Found' });
-  }
-
   const stripped = pathname.replace(/\.md$/, '');
   const parts = stripped === '/index' || stripped === '/'
     ? []

package/src/server/routes/[version]/llms.txt.ts

@@ -0,0 +1,26 @@
+import { getRouterParam } from 'h3';
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { buildLlmsTxt } from '@/lib/llms';
+import { extractFrontmatter, getPagesForVersion } from '@/lib/source';
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+
+  const versionDir = getRouterParam(event, 'version');
+  const version = config.versions?.find(v => v.dir === versionDir);
+  if (!version) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  const ctx = { dir: version.dir, urlPrefix: `/${version.dir}` };
+  const pages = await getPagesForVersion(ctx);
+  const body = buildLlmsTxt(
+    config,
+    pages.map(p => ({ url: p.url, title: extractFrontmatter(p).title })),
+    ctx,
+  );
+
+  event.res.headers.set('Content-Type', 'text/plain');
+  return body;
+});

package/src/server/routes/llms.txt.ts

@@ -1,21 +1,18 @@
-import { defineHandler, HTTPError } from 'nitro';
+import { defineHandler } from 'nitro';
 import { loadConfig } from '@/lib/config';
-import { getPages, extractFrontmatter } from '@/lib/source';
+import { buildLlmsTxt } from '@/lib/llms';
+import { extractFrontmatter, getPagesForVersion } from '@/lib/source';
+import { LATEST_CONTEXT } from '@/lib/version-source';
 
 export default defineHandler(async event => {
   const config = loadConfig();
 
-  if (!config.llms?.enabled) {
-    throw new HTTPError({ status: 404, message: 'Not Found' });
-  }
-
-  const pages = await getPages();
-  const index = pages.map(p => {
-    const fm = extractFrontmatter(p);
-    const mdUrl = p.url === '/' ? '/index.md' : `${p.url}.md`;
-    return `- [${fm.title}](${mdUrl})`;
-  }).join('\n');
-  const body = `# ${config.title}\n\n${config.description ?? ''}\n\n${index}`;
+  const pages = await getPagesForVersion(LATEST_CONTEXT);
+  const body = buildLlmsTxt(
+    config,
+    pages.map(p => ({ url: p.url, title: extractFrontmatter(p).title })),
+    LATEST_CONTEXT,
+  );
 
   event.res.headers.set('Content-Type', 'text/plain');
   return body;

package/src/server/routes/og.tsx

@@ -22,9 +22,9 @@ async function loadFont(): Promise<ArrayBuffer> {
 
 export default defineHandler(async event => {
   const config = loadConfig();
-  const title = event.url.searchParams.get('title') ?? config.title;
+  const title = event.url.searchParams.get('title') ?? config.site.title;
   const description = event.url.searchParams.get('description') ?? '';
-  const siteName = config.title;
+  const siteName = config.site.title;
 
   const font = await loadFont();
 

package/src/server/routes/sitemap.xml.ts

@@ -1,6 +1,6 @@
 import { defineHandler } from 'nitro';
 import { buildApiRoutes } from '@/lib/api-routes';
-import { loadConfig } from '@/lib/config';
+import { getAllVersions, getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { getPages } from '@/lib/source';
 
@@ -23,11 +23,19 @@ export default defineHandler(async event => {
     return `<url><loc>${baseUrl}/${page.slugs.join('/')}</loc>${lastmod}</url>`;
   });
 
-  const apiPages = config.api?.length
-    ? buildApiRoutes(await loadApiSpecs(config.api)).map(
-        route => `<url><loc>${baseUrl}/apis/${route.slug.join('/')}</loc></url>`
-      )
-    : [];
+  const apiPages: string[] = [];
+  for (const v of getAllVersions(config)) {
+    const versionDir = v.isLatest ? null : v.dir;
+    const apiConfigs = getApiConfigsForVersion(config, versionDir);
+    if (!apiConfigs.length) continue;
+    const prefix = versionDir ? `/${versionDir}` : '';
+    const routes = buildApiRoutes(await loadApiSpecs(apiConfigs));
+    for (const route of routes) {
+      apiPages.push(
+        `<url><loc>${baseUrl}${prefix}/apis/${route.slug.join('/')}</loc></url>`,
+      );
+    }
+  }
 
   const xml = `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

package/src/server/vite-config.ts

@@ -18,7 +18,6 @@ function resolveOutputDir(projectRoot: string, preset?: string): string {
 export interface ViteConfigOptions {
   packageRoot: string;
   projectRoot: string;
-  contentDir: string;
   configPath?: string;
   preset?: string;
 }
@@ -41,8 +40,9 @@ async function readChronicleConfig(projectRoot: string, configPath?: string): Pr
 export async function createViteConfig(
   options: ViteConfigOptions
 ): Promise<InlineConfig> {
-  const { packageRoot, projectRoot, contentDir, configPath, preset } = options;
+  const { packageRoot, projectRoot, configPath, preset } = options;
   const rawConfig = await readChronicleConfig(projectRoot, configPath);
+  const contentMirror = path.resolve(packageRoot, '.content');
 
   return {
     root: packageRoot,
@@ -86,8 +86,8 @@ export async function createViteConfig(
     resolve: {
       alias: {
         '@': path.resolve(packageRoot, 'src'),
+        'tslib': 'tslib/tslib.es6.js',
       },
-      conditions: ['module-sync', 'import', 'node'],
       dedupe: [
         'react',
         'react-dom',
@@ -98,11 +98,11 @@ export async function createViteConfig(
     },
     server: {
       fs: {
-        allow: [packageRoot, projectRoot, contentDir]
+        allow: [packageRoot, projectRoot, contentMirror]
       }
     },
     define: {
-      __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentDir),
+      __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentMirror),
       __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot),
       __CHRONICLE_CONFIG_RAW__: JSON.stringify(rawConfig),
     },

package/src/themes/default/ContentDirButtons.tsx

@@ -0,0 +1,66 @@
+import { ChevronDownIcon } from '@heroicons/react/24/outline';
+import { Button, Menu, Flex } from '@raystack/apsara';
+import { Link as RouterLink, useLocation, useNavigate } from 'react-router';
+import { getLandingEntries } from '@/lib/config';
+import { getActiveContentDir, splitContentButtons } from '@/lib/navigation';
+import { usePageContext } from '@/lib/page-context';
+
+const MAX_VISIBLE = 3;
+
+export function ContentDirButtons() {
+  const { config, version } = usePageContext();
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+
+  const entries = getLandingEntries(config, version.dir);
+  if (entries.length <= 1) return null;
+
+  const active = getActiveContentDir(pathname, config);
+  const { visible, overflow } = splitContentButtons(entries, MAX_VISIBLE);
+
+  return (
+    <Flex gap='small' align='center'>
+      {visible.map(entry => (
+        <RouterLink
+          key={entry.href}
+          to={entry.href}
+          style={{ textDecoration: 'none' }}
+        >
+          <Button
+            size='small'
+            variant={active === entry.contentDir ? 'solid' : 'outline'}
+            color='neutral'
+          >
+            {entry.label}
+          </Button>
+        </RouterLink>
+      ))}
+      {overflow.length > 0 ? (
+        <Menu>
+          <Menu.Trigger
+            render={
+              <Button
+                size='small'
+                variant='outline'
+                color='neutral'
+                trailingIcon={<ChevronDownIcon width={14} height={14} />}
+              />
+            }
+          >
+            More
+          </Menu.Trigger>
+          <Menu.Content>
+            {overflow.map(entry => (
+              <Menu.Item
+                key={entry.href}
+                onClick={() => navigate(entry.href)}
+              >
+                {entry.label}
+              </Menu.Item>
+            ))}
+          </Menu.Content>
+        </Menu>
+      ) : null}
+    </Flex>
+  );
+}