@raystack/chronicle 0.9.0 → 0.10.1

package/dist/cli/index.js

@@ -312,6 +312,18 @@ import { nitro } from "nitro/vite";
 import fs3 from "node:fs/promises";
 import path6 from "node:path";
 import remarkDirective from "remark-directive";
+function getDatabaseConnector(preset) {
+  switch (preset) {
+    case "bun":
+      return { connector: "bun-sqlite", options: { name: "chronicle-search" } };
+    case "cloudflare":
+    case "cloudflare-pages":
+    case "cloudflare-module":
+      return { connector: "cloudflare-d1", options: { bindingName: "CHRONICLE_DB" } };
+    default:
+      return { connector: "sqlite", options: { name: "chronicle-search" } };
+  }
+}
 function resolveOutputDir(projectRoot, preset) {
   if (preset === "vercel" || preset === "vercel-static")
     return path6.resolve(projectRoot, ".vercel/output");
@@ -429,10 +441,7 @@ async function createViteConfig(options) {
         database: true
       },
       database: {
-        default: {
-          connector: "sqlite",
-          options: { name: "chronicle-search" }
-        }
+        default: getDatabaseConnector(preset)
       }
     }
   };
@@ -561,6 +570,11 @@ var RESERVED_ROUTE_SEGMENTS = [
   "robots.txt",
   "sitemap.xml"
 ];
+var redirectSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  permanent: z.boolean().optional()
+});
 var chronicleConfigSchema = z.object({
   site: siteSchema,
   url: z.string().optional(),
@@ -573,6 +587,7 @@ var chronicleConfigSchema = z.object({
   navigation: navigationSchema.optional(),
   search: searchSchema.optional(),
   api: z.array(apiSchema).optional(),
+  redirects: z.array(redirectSchema).optional(),
   analytics: analyticsSchema.optional(),
   telemetry: telemetrySchema.optional()
 }).strict().refine((cfg) => allUnique(cfg.content, (c) => c.dir), {
@@ -807,6 +822,18 @@ var devCommand = new Command2("dev").description("Start development server").opt
   });
   await server.listen();
   server.printUrls();
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    try {
+      await server.close();
+    } catch {}
+    process.exit(0);
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
 });
 
 // src/cli/commands/init.ts
@@ -938,6 +965,18 @@ var startCommand = new Command5("start").description("Start production server").
     preview: { port, host: options.host }
   });
   server.printUrls();
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    try {
+      await server.close();
+    } catch {}
+    process.exit(0);
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
 });
 
 // src/cli/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -47,7 +47,7 @@
     "@opentelemetry/sdk-metrics": "^2.6.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@radix-ui/react-icons": "^1.3.2",
-    "@raystack/apsara": "1.0.0-rc.4",
+    "@raystack/apsara": "1.0.0-rc.7",
     "@shikijs/rehype": "^4.0.2",
     "@vitejs/plugin-react": "^6.0.1",
     "chalk": "^5.6.2",
@@ -59,6 +59,7 @@
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "h3": "^2.0.1-rc.16",
+    "http-status-codes": "^2.3.0",
     "lodash-es": "^4.17.23",
     "mermaid": "^11.13.0",
     "nitro": "3.0.260311-beta",

package/src/cli/commands/dev.ts

@@ -28,4 +28,16 @@ export const devCommand = new Command('dev')
 
     await server.listen();
     server.printUrls();
+
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      try {
+        await server.close();
+      } catch { /* ignore close errors */ }
+      process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
   });

package/src/cli/commands/start.ts

@@ -26,4 +26,16 @@ export const startCommand = new Command('start')
     });
 
     server.printUrls();
+
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      try {
+        await server.close();
+      } catch { /* ignore close errors */ }
+      process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
   });

package/src/components/api/playground-dialog.tsx

@@ -2,7 +2,7 @@
 
 import { useState, useCallback, useMemo } from 'react'
 import type { OpenAPIV3 } from 'openapi-types'
-import { Dialog, Button, Badge, IconButton, InputField, CopyButton, Select, Menu } from '@raystack/apsara'
+import { Dialog, Button, Badge, IconButton, Input, CopyButton, Select, Menu } from '@raystack/apsara'
 import { Cross2Icon, ChevronDownIcon, ChevronUpIcon, PlayIcon, PlusIcon } from '@radix-ui/react-icons'
 import { CounterClockwiseClockIcon, CodeIcon } from '@radix-ui/react-icons'
 import { MethodBadge } from '@/components/api/method-badge'
@@ -263,13 +263,13 @@ export function PlaygroundDialog({
                           <div className={styles.fieldRow}>
                             <span className={styles.fieldLabel}>Username</span>
                             <div className={styles.fieldInput}>
-                              <InputField size="small" placeholder="Enter username" value={basicUser} onChange={(e) => setBasicUser(e.target.value)} />
+                              <Input size="small" placeholder="Enter username" value={basicUser} onValueChange={setBasicUser} />
                             </div>
                           </div>
                           <div className={styles.fieldRow}>
                             <span className={styles.fieldLabel}>Password</span>
                             <div className={styles.fieldInput}>
-                              <InputField size="small" type="password" placeholder="Enter password" value={basicPass} onChange={(e) => setBasicPass(e.target.value)} />
+                              <Input size="small" type="password" placeholder="Enter password" value={basicPass} onValueChange={setBasicPass} />
                             </div>
                           </div>
                         </>
@@ -277,7 +277,7 @@ export function PlaygroundDialog({
                         <div className={styles.fieldRow}>
                           <span className={styles.fieldLabel}>{currentScheme.headerName}</span>
                           <div className={styles.fieldInput}>
-                            <InputField size="small" placeholder={currentScheme.placeholder} value={authToken} onChange={(e) => setAuthToken(e.target.value)} />
+                            <Input size="small" placeholder={currentScheme.placeholder} value={authToken} onValueChange={setAuthToken} />
                           </div>
                         </div>
                       ) : null}
@@ -285,7 +285,7 @@ export function PlaygroundDialog({
                         <div key={f.name} className={styles.fieldRow}>
                           <span className={styles.fieldLabel}>{f.name}</span>
                           <div className={styles.fieldInput}>
-                            <InputField size="small" placeholder="Enter value" value={headerValues[f.name] ?? ''} onChange={(e) => setHeaderValues({ ...headerValues, [f.name]: e.target.value })} />
+                            <Input size="small" placeholder="Enter value" value={headerValues[f.name] ?? ''} onValueChange={(v) => setHeaderValues({ ...headerValues, [f.name]: v })} />
                           </div>
                         </div>
                       ))}
@@ -307,11 +307,11 @@ export function PlaygroundDialog({
                     <div key={f.name} className={styles.fieldRow}>
                       <span className={styles.fieldLabel}>{f.name}</span>
                       <div className={styles.fieldInput}>
-                        <InputField
+                        <Input
                           size="small"
                           placeholder="Enter value"
                           value={pathValues[f.name] ?? ''}
-                          onChange={(e) => setPathValues({ ...pathValues, [f.name]: e.target.value })}
+                          onValueChange={(v) => setPathValues({ ...pathValues, [f.name]: v })}
                         />
                       </div>
                     </div>
@@ -332,11 +332,11 @@ export function PlaygroundDialog({
                     <div key={f.name} className={styles.fieldRow}>
                       <span className={styles.fieldLabel}>{f.name}</span>
                       <div className={styles.fieldInput}>
-                        <InputField
+                        <Input
                           size="small"
                           placeholder={f.description ?? 'Enter value'}
                           value={queryValues[f.name] ?? ''}
-                          onChange={(e) => setQueryValues({ ...queryValues, [f.name]: e.target.value })}
+                          onValueChange={(v) => setQueryValues({ ...queryValues, [f.name]: v })}
                         />
                       </div>
                     </div>
@@ -494,13 +494,13 @@ function BodyFieldRow({ field, value, onChange }: {
         {items.map((item, i) => (
           <div key={i} className={styles.arrayItemRow}>
             <div className={styles.fieldInput}>
-              <InputField
+              <Input
                 size="small"
                 placeholder={`${field.name}[${i}]`}
                 value={String(item)}
-                onChange={(e) => {
+                onValueChange={(v) => {
                   const updated = [...items]
-                  updated[i] = e.target.value
+                  updated[i] = v
                   onChange(updated)
                 }}
               />
@@ -539,11 +539,11 @@ function BodyFieldRow({ field, value, onChange }: {
     <div className={styles.fieldRow}>
       <span className={styles.fieldLabel}>{field.name} {field.required && <Badge variant="danger" size="micro">required</Badge>}</span>
       <div className={styles.fieldInput}>
-        <InputField
+        <Input
           size="small"
           placeholder={field.description ?? 'Enter value'}
           value={String(value ?? '')}
-          onChange={(e) => onChange(e.target.value)}
+          onValueChange={(v) => onChange(v)}
         />
       </div>
     </div>

package/src/components/mdx/link.tsx

@@ -1,12 +1,10 @@
 import { Link as ApsaraLink } from '@raystack/apsara';
-import type { ComponentProps, MouseEvent } from 'react';
-import { useNavigate } from 'react-router';
+import type { ComponentProps } from 'react';
+import { Link as RouterLink } from 'react-router';
 
 type LinkProps = ComponentProps<'a'>;
 
-export function Link({ href, children, onClick: onClickProp, ...props }: LinkProps) {
-  const navigate = useNavigate();
-
+export function Link({ href, children, ...props }: LinkProps) {
   if (!href) {
     return <span {...props}>{children}</span>;
   }
@@ -16,12 +14,7 @@ export function Link({ href, children, onClick: onClickProp, ...props }: LinkPro
 
   if (isExternal) {
     return (
-      <ApsaraLink
-        href={href}
-        target='_blank'
-        rel='noopener noreferrer'
-        {...props}
-      >
+      <ApsaraLink href={href} external {...props}>
         {children}
       </ApsaraLink>
     );
@@ -35,27 +28,8 @@ export function Link({ href, children, onClick: onClickProp, ...props }: LinkPro
     );
   }
 
-  const onClick = (e: MouseEvent<HTMLAnchorElement>) => {
-    if (
-      e.defaultPrevented ||
-      e.button !== 0 ||
-      e.metaKey ||
-      e.ctrlKey ||
-      e.shiftKey ||
-      e.altKey
-    ) {
-      return;
-    }
-
-    onClickProp?.(e);
-    if (e.defaultPrevented) return;
-
-    e.preventDefault();
-    navigate(href);
-  };
-
   return (
-    <ApsaraLink href={href} {...props} onClick={onClick}>
+    <ApsaraLink render={<RouterLink to={href} />} {...props}>
       {children}
     </ApsaraLink>
   );

package/src/lib/folder-utils.ts

@@ -0,0 +1,26 @@
+import type { Node, Folder } from 'fumadocs-core/page-tree';
+
+const NodeType = {
+  Page: 'page',
+  Folder: 'folder',
+} as const;
+
+export function parentPath(url: string): string {
+  const parts = url.split('/').filter(Boolean);
+  parts.pop();
+  return '/' + parts.join('/');
+}
+
+export function getFolderPath(node: Folder): string | null {
+  if (node.index) return node.index.url;
+  for (const child of node.children) {
+    if (child.type === NodeType.Page) return parentPath(child.url);
+  }
+  for (const child of node.children) {
+    if (child.type === NodeType.Folder) {
+      const childPath = getFolderPath(child as Folder);
+      if (childPath) return parentPath(childPath);
+    }
+  }
+  return null;
+}

package/src/lib/route-resolver.test.ts

@@ -60,7 +60,7 @@ describe('resolveRoute — root', () => {
     expect(resolveRoute('/', singleContent())).toEqual({
       type: RouteType.Redirect,
       to: '/docs',
-      status: 302,
+      status: 307,
     })
   })
 
@@ -75,7 +75,7 @@ describe('resolveRoute — root', () => {
     expect(resolveRoute('/', multiContentNoLanding())).toEqual({
       type: RouteType.Redirect,
       to: '/docs',
-      status: 302,
+      status: 307,
     })
   })
 
@@ -83,7 +83,7 @@ describe('resolveRoute — root', () => {
     expect(resolveRoute('/v2', versioned())).toEqual({
       type: RouteType.Redirect,
       to: '/v2/docs',
-      status: 302,
+      status: 307,
     })
   })
 

package/src/lib/route-resolver.ts

@@ -1,3 +1,4 @@
+import { StatusCodes } from 'http-status-codes'
 import type { ChronicleConfig } from '@/types'
 import { getLatestContentRoots, getVersionContentRoots } from './config'
 import { type VersionContext, resolveVersionFromUrl } from './version-source'
@@ -13,7 +14,7 @@ export const RouteType = {
 export type RouteType = (typeof RouteType)[keyof typeof RouteType]
 
 export type Route =
-  | { type: typeof RouteType.Redirect; to: string; status: 302 }
+  | { type: typeof RouteType.Redirect; to: string; status: StatusCodes.TEMPORARY_REDIRECT | StatusCodes.PERMANENT_REDIRECT }
   | { type: typeof RouteType.DocsIndex; version: VersionContext }
   | { type: typeof RouteType.DocsPage; version: VersionContext; slug: string[] }
   | { type: typeof RouteType.ApiIndex; version: VersionContext }
@@ -45,6 +46,15 @@ export function resolveRoute(
   pathname: string,
   config: ChronicleConfig,
 ): Route {
+  const redirect = config.redirects?.find((r) => r.from === pathname)
+  if (redirect) {
+    return {
+      type: RouteType.Redirect,
+      to: redirect.to,
+      status: redirect.permanent ? StatusCodes.PERMANENT_REDIRECT : StatusCodes.TEMPORARY_REDIRECT,
+    }
+  }
+
   const parts = pathname.split('/').filter(Boolean)
   const version = resolveVersionFromUrl(pathname, config)
   const remainder =
@@ -65,7 +75,7 @@ export function resolveRoute(
     return {
       type: RouteType.Redirect,
       to: `${version.urlPrefix}/${dirs[0]}`,
-      status: 302,
+      status: StatusCodes.TEMPORARY_REDIRECT,
     }
   }
 

package/src/lib/source-utils.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test'
+import type { Node, Folder } from 'fumadocs-core/page-tree'
+import { parentPath, getFolderPath } from './folder-utils'
+
+function page(url: string): Node {
+  return { type: 'page', name: 'Page', url } as Node
+}
+
+function folder(name: string, children: Node[], indexUrl?: string): Folder {
+  return {
+    type: 'folder',
+    name,
+    children,
+    ...(indexUrl ? { index: { url: indexUrl } } : {}),
+  } as Folder
+}
+
+describe('parentPath', () => {
+  test('returns parent of page URL', () => {
+    expect(parentPath('/docs/guides/install')).toBe('/docs/guides')
+  })
+
+  test('returns root for top-level page', () => {
+    expect(parentPath('/docs')).toBe('/')
+  })
+
+  test('handles trailing segments', () => {
+    expect(parentPath('/a/b/c/d')).toBe('/a/b/c')
+  })
+
+  test('handles root', () => {
+    expect(parentPath('/')).toBe('/')
+  })
+})
+
+describe('getFolderPath', () => {
+  test('returns index URL when folder has index', () => {
+    const f = folder('Guides', [page('/docs/guides/install')], '/docs/guides')
+    expect(getFolderPath(f)).toBe('/docs/guides')
+  })
+
+  test('derives path from direct child page', () => {
+    const f = folder('Guides', [page('/docs/guides/install')])
+    expect(getFolderPath(f)).toBe('/docs/guides')
+  })
+
+  test('derives path from subfolder child (not deeply nested)', () => {
+    const f = folder('Tasking', [
+      folder('Via Order Desk', [page('/docs/tasking/via_order_desk/package')])
+    ])
+    expect(getFolderPath(f)).toBe('/docs/tasking')
+  })
+
+  test('handles folder with & in path', () => {
+    const f = folder('Cart & Order', [page('/docs/cart&order/working_with_cart')])
+    expect(getFolderPath(f)).toBe('/docs/cart&order')
+  })
+
+  test('handles folder with space in path', () => {
+    const f = folder('My Folder', [page('/docs/my folder/intro')])
+    expect(getFolderPath(f)).toBe('/docs/my folder')
+  })
+
+  test('returns null for empty folder', () => {
+    const f = folder('Empty', [])
+    expect(getFolderPath(f)).toBeNull()
+  })
+
+  test('prefers direct child page over subfolder', () => {
+    const f = folder('Mixed', [
+      page('/docs/mixed/intro'),
+      folder('Sub', [page('/docs/mixed/sub/deep')])
+    ])
+    expect(getFolderPath(f)).toBe('/docs/mixed')
+  })
+
+  test('deeply nested only-subfolder chain', () => {
+    const f = folder('Root', [
+      folder('Mid', [
+        folder('Deep', [page('/a/b/c/d/page')])
+      ])
+    ])
+    expect(getFolderPath(f)).toBe('/a/b')
+  })
+})

package/src/lib/source.ts

@@ -3,6 +3,13 @@ import path from 'node:path';
 import { loader } from 'fumadocs-core/source';
 import { flattenTree } from 'fumadocs-core/page-tree';
 import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
+
+import { parentPath, getFolderPath } from './folder-utils';
+
+const NodeType = {
+  Page: 'page',
+  Folder: 'folder',
+} as const;
 import type { MDXContent } from 'mdx/types';
 import type { TableOfContents } from 'fumadocs-core/toc';
 import {
@@ -120,28 +127,10 @@ export function invalidate() {
   cachedNavMap = null;
 }
 
-function getFolderPath(node: Folder): string | null {
-  const firstPage = findFirstPage(node);
-  if (!firstPage) return null;
-  const parts = firstPage.url.split('/').filter(Boolean);
-  parts.pop();
-  return '/' + parts.join('/');
-}
-
-function findFirstPage(node: Folder): { url: string } | null {
-  for (const child of node.children) {
-    if (child.type === 'page') return child;
-    if (child.type === 'folder') {
-      const found = findFirstPage(child);
-      if (found) return found;
-    }
-  }
-  return node.index ?? null;
-}
 
 function getOrder(node: Node, pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): number | undefined {
-  if (node.type === 'page') return pageOrderMap.get(node.url);
-  if (node.type === 'folder') {
+  if (node.type === NodeType.Page) return pageOrderMap.get(node.url);
+  if (node.type === NodeType.Folder) {
     const folderPath = getFolderPath(node);
     if (folderPath) return folderOrderMap.get(folderPath);
   }

package/src/lib/tree-utils.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from 'bun:test'
+import type { Node } from 'fumadocs-core/page-tree'
+import { getFirstPageUrl, findFolderFirstPage, resolveDocsRedirect } from './tree-utils'
+
+function page(url: string, name = 'Page'): Node {
+  return { type: 'page', name, url } as Node
+}
+
+function folder(name: string, children: Node[], indexUrl?: string): Node {
+  return {
+    type: 'folder',
+    name,
+    children,
+    ...(indexUrl ? { index: { url: indexUrl } } : {}),
+  } as Node
+}
+
+describe('getFirstPageUrl', () => {
+  test('returns first page url', () => {
+    expect(getFirstPageUrl([page('/docs/intro')])).toBe('/docs/intro')
+  })
+
+  test('returns first page from nested folder', () => {
+    const nodes = [folder('Guides', [page('/docs/guides/install')])]
+    expect(getFirstPageUrl(nodes)).toBe('/docs/guides/install')
+  })
+
+  test('skips empty folders', () => {
+    const nodes = [folder('Empty', []), page('/docs/hello')]
+    expect(getFirstPageUrl(nodes)).toBe('/docs/hello')
+  })
+
+  test('returns null for empty list', () => {
+    expect(getFirstPageUrl([])).toBeNull()
+  })
+
+  test('returns null for folders with no pages', () => {
+    expect(getFirstPageUrl([folder('Empty', [])])).toBeNull()
+  })
+})
+
+describe('findFolderFirstPage', () => {
+  test('finds folder by index url', () => {
+    const nodes = [
+      folder('Guides', [page('/docs/guides/install'), page('/docs/guides/config')], '/docs/guides'),
+    ]
+    expect(findFolderFirstPage(nodes, '/docs/guides')).toBe('/docs/guides/install')
+  })
+
+  test('finds folder without index by child page path', () => {
+    const nodes = [
+      folder('Guides', [page('/docs/guides/install'), page('/docs/guides/config')]),
+    ]
+    expect(findFolderFirstPage(nodes, '/docs/guides')).toBe('/docs/guides/install')
+  })
+
+  test('finds nested folder', () => {
+    const nodes = [
+      folder('Docs', [
+        folder('Advanced', [page('/docs/advanced/perf'), page('/docs/advanced/debug')]),
+      ]),
+    ]
+    expect(findFolderFirstPage(nodes, '/docs/advanced')).toBe('/docs/advanced/perf')
+  })
+
+  test('returns null for non-matching path', () => {
+    const nodes = [folder('Guides', [page('/docs/guides/install')])]
+    expect(findFolderFirstPage(nodes, '/docs/api')).toBeNull()
+  })
+
+  test('returns null for empty folder', () => {
+    const nodes = [folder('Empty', [])]
+    expect(findFolderFirstPage(nodes, '/docs/empty')).toBeNull()
+  })
+})
+
+describe('resolveDocsRedirect', () => {
+  const tree = {
+    children: [
+      page('/docs/intro'),
+      folder('Guides', [page('/docs/guides/install')]),
+    ] as Node[],
+  }
+
+  test('redirects to index_page when set', () => {
+    expect(resolveDocsRedirect(['docs'], tree, { dir: 'docs', index_page: 'getting-started' }))
+      .toBe('/docs/getting-started')
+  })
+
+  test('redirects content root to first page', () => {
+    expect(resolveDocsRedirect(['docs'], tree, { dir: 'docs' }))
+      .toBe('/docs/intro')
+  })
+
+  test('redirects folder to first child', () => {
+    expect(resolveDocsRedirect(['docs', 'guides'], tree, { dir: 'docs' }))
+      .toBe('/docs/guides/install')
+  })
+
+  test('returns null for non-matching path', () => {
+    expect(resolveDocsRedirect(['docs', 'nonexistent'], tree, { dir: 'docs' }))
+      .toBeNull()
+  })
+
+  test('returns null without content config', () => {
+    expect(resolveDocsRedirect(['other'], tree)).toBeNull()
+  })
+
+  test('index_page takes priority over first page', () => {
+    expect(resolveDocsRedirect(['docs'], tree, { dir: 'docs', index_page: 'custom' }))
+      .toBe('/docs/custom')
+  })
+})

package/src/lib/tree-utils.ts

@@ -0,0 +1,57 @@
+import type { Node } from 'fumadocs-core/page-tree';
+
+export const NodeType = {
+  Page: 'page',
+  Folder: 'folder',
+  Separator: 'separator',
+} as const;
+
+export function getFirstPageUrl(nodes: Node[]): string | null {
+  for (const node of nodes) {
+    if (node.type === NodeType.Page) return node.url;
+    if (node.type === NodeType.Folder) {
+      const url = getFirstPageUrl(node.children);
+      if (url) return url;
+    }
+  }
+  return null;
+}
+
+function getFolderPath(node: Node): string | null {
+  if (node.type !== NodeType.Folder) return null;
+  if (node.index) return node.index.url;
+  const firstPage = getFirstPageUrl(node.children);
+  if (!firstPage) return null;
+  const parts = firstPage.split('/').filter(Boolean);
+  parts.pop();
+  return '/' + parts.join('/');
+}
+
+export function findFolderFirstPage(nodes: Node[], pathname: string): string | null {
+  for (const node of nodes) {
+    if (node.type === NodeType.Folder) {
+      const folderPath = getFolderPath(node);
+      if (folderPath === pathname) return getFirstPageUrl(node.children);
+      const found = findFolderFirstPage(node.children, pathname);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+export function resolveDocsRedirect(
+  slug: string[],
+  tree: { children: Node[] },
+  contentConfig?: { dir: string; index_page?: string },
+): string | null {
+  const isContentRoot = slug.length === 1 && slug[0] === contentConfig?.dir;
+
+  if (isContentRoot) {
+    if (contentConfig?.index_page) {
+      return `/${contentConfig.dir}/${contentConfig.index_page}`;
+    }
+    return getFirstPageUrl(tree.children);
+  }
+
+  return findFolderFirstPage(tree.children, `/${slug.join('/')}`);
+}

package/src/pages/DocsPage.tsx

@@ -1,32 +1,10 @@
 import { Navigate } from 'react-router';
+import { StatusCodes } from 'http-status-codes';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
+import { resolveDocsRedirect } from '@/lib/tree-utils';
 import { NotFound } from '@/pages/NotFound';
 import { getTheme } from '@/themes/registry';
-import type { Node } from 'fumadocs-core/page-tree';
-
-function getFirstPageUrl(nodes: Node[]): string | null {
-  for (const node of nodes) {
-    if (node.type === 'page') return node.url;
-    if (node.type === 'folder') {
-      const url = getFirstPageUrl(node.children);
-      if (url) return url;
-    }
-  }
-  return null;
-}
-
-function findFolderFirstPage(nodes: Node[], pathname: string): string | null {
-  for (const node of nodes) {
-    if (node.type === 'folder') {
-      const folderUrl = node.index?.url;
-      if (folderUrl === pathname) return getFirstPageUrl(node.children);
-      const found = findFolderFirstPage(node.children, pathname);
-      if (found) return found;
-    }
-  }
-  return null;
-}
 
 interface DocsPageProps {
   slug: string[];
@@ -35,19 +13,10 @@ interface DocsPageProps {
 export function DocsPage({ slug }: DocsPageProps) {
   const { config, tree, page, isLoading, errorStatus } = usePageContext();
 
-  if (errorStatus === 404) {
-    const pathname = `/${slug.join('/')}`;
+  if (errorStatus === StatusCodes.NOT_FOUND) {
     const contentConfig = config.content?.find(c => c.dir === slug[0]);
-    const isContentRoot = slug.length === 1 && slug[0] === contentConfig?.dir;
-    if (contentConfig?.index_page) {
-      return <Navigate to={`/${contentConfig.dir}/${contentConfig.index_page}`} replace />;
-    }
-    if (isContentRoot) {
-      const firstUrl = getFirstPageUrl(tree.children);
-      if (firstUrl) return <Navigate to={firstUrl} replace />;
-    }
-    const folderFirstUrl = findFolderFirstPage(tree.children, pathname);
-    if (folderFirstUrl) return <Navigate to={folderFirstUrl} replace />;
+    const redirectUrl = resolveDocsRedirect(slug, tree, contentConfig);
+    if (redirectUrl) return <Navigate to={redirectUrl} replace />;
     return <NotFound />;
   }
   if (errorStatus) return <NotFound />;

package/src/server/entry-server.tsx

@@ -10,6 +10,9 @@ import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
 import { getPageTree, getPage, getPageNav, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { getFirstApiUrl } from '@/lib/api-routes';
+import { StatusCodes } from 'http-status-codes';
+import { resolveDocsRedirect } from '@/lib/tree-utils';
 import { useNitroApp } from 'nitro/app';
 import { App } from './App';
 
@@ -45,6 +48,30 @@ export default {
       getPageTree(),
       route.type === RouteType.DocsPage ? getPage(route.slug) : Promise.resolve(null),
     ]);
+    // SSR redirects for index pages
+    if (route.type === RouteType.ApiIndex) {
+      const firstUrl = getFirstApiUrl(apiSpecs);
+      if (firstUrl) {
+        return new Response(null, { status: StatusCodes.TEMPORARY_REDIRECT, headers: { Location: firstUrl } });
+      }
+    }
+
+    if (route.type === RouteType.DocsPage && !page) {
+      const versionPrefix = route.version.urlPrefix;
+      const slugWithoutVersion = versionPrefix && route.slug[0] === route.version.dir
+        ? route.slug.slice(1)
+        : route.slug;
+      const contentEntries = route.version.dir
+        ? config.versions?.find(v => v.dir === route.version.dir)?.content ?? config.content
+        : config.content;
+      const contentConfig = contentEntries?.find((c: { dir: string }) => c.dir === slugWithoutVersion[0]);
+      const redirectUrl = resolveDocsRedirect(slugWithoutVersion, tree, contentConfig);
+      if (redirectUrl) {
+        const fullUrl = versionPrefix ? `${versionPrefix}${redirectUrl}` : redirectUrl;
+        return new Response(null, { status: StatusCodes.TEMPORARY_REDIRECT, headers: { Location: fullUrl } });
+      }
+    }
+
     const nav = page ? await getPageNav(pageSlug) : { prev: null, next: null };
 
     const relativePath = page ? getRelativePath(page) : null;
@@ -88,6 +115,8 @@ export default {
         <head>
           <meta charSet="UTF-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <link rel="icon" href="/favicon.ico" />
+          <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
           {assets.css.map((attr: { href: string }) => (
             <link key={attr.href} rel="stylesheet" {...attr} />
           ))}
@@ -120,7 +149,7 @@ export default {
 
     const renderDuration = performance.now() - renderStart;
 
-    const status = route.type === RouteType.DocsPage && !page ? 404 : 200;
+    const status = route.type === RouteType.DocsPage && !page ? StatusCodes.NOT_FOUND : StatusCodes.OK;
 
     // biome-ignore lint/correctness/useHookAtTopLevel: useNitroApp is a Nitro DI accessor, not a React hook
     useNitroApp().hooks.callHook('chronicle:ssr-rendered', pathname, status, renderDuration);

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

@@ -3,11 +3,15 @@ import matter from 'gray-matter';
 import { defineHandler, HTTPError } from 'nitro';
 import { getPage, getOriginalPath } from '@/lib/source';
 import { safePath } from '@/server/utils/safe-path';
+import { handleApiMarkdown } from '@/server/utils/api-markdown';
 
 export default defineHandler(async event => {
   const pathname = event.path || event.req.url?.split('?')[0] || '';
   if (!pathname.endsWith('.md')) return;
-  if (pathname.startsWith('/apis/')) return;
+
+  if (pathname.startsWith('/apis/')) {
+    return handleApiMarkdown(pathname);
+  }
 
   const stripped = pathname.replace(/\.md$/, '');
   const parts = stripped === '/index' || stripped === '/'

package/src/server/{routes/apis/[...slug].md.ts → utils/api-markdown.ts}

@@ -1,15 +1,12 @@
 import type { OpenAPIV3 } from 'openapi-types'
-import { defineHandler, HTTPError } from 'nitro'
+import { HTTPError } from 'nitro'
 import { loadConfig } from '@/lib/config'
 import { loadApiSpecs } from '@/lib/openapi'
 import { findApiOperation } from '@/lib/api-routes'
 import { flattenSchema, generateExampleJson, type SchemaField } from '@/lib/schema'
 import { generateCurl } from '@/lib/snippet-generators'
 
-export default defineHandler(async event => {
-  const pathname = event.path || event.req.url?.split('?')[0] || ''
-  if (!pathname.endsWith('.md')) return
-
+export async function handleApiMarkdown(pathname: string) {
   const stripped = pathname.replace(/\.md$/, '').replace(/^\/apis\//, '')
   const slug = stripped.split('/').filter(Boolean)
   if (slug.length < 2) {
@@ -26,7 +23,7 @@ export default defineHandler(async event => {
 
   const md = generateApiMarkdown(match.method, match.path, match.operation, match.spec.server.url, match.spec.auth)
   return new Response(md, { headers: { 'Content-Type': 'text/markdown; charset=utf-8' } })
-})
+}
 
 function generateApiMarkdown(
   method: string,

package/src/server/vite-config.ts

@@ -12,6 +12,19 @@ import remarkResolveLinks from '../lib/remark-resolve-links';
 import remarkReadingTime from 'remark-reading-time';
 import remarkUnusedDirectives from '../lib/remark-unused-directives';
 
+function getDatabaseConnector(preset?: string): { connector: string; options?: Record<string, unknown> } {
+  switch (preset) {
+    case 'bun':
+      return { connector: 'bun-sqlite', options: { name: 'chronicle-search' } };
+    case 'cloudflare':
+    case 'cloudflare-pages':
+    case 'cloudflare-module':
+      return { connector: 'cloudflare-d1', options: { bindingName: 'CHRONICLE_DB' } };
+    default:
+      return { connector: 'sqlite', options: { name: 'chronicle-search' } };
+  }
+}
+
 function resolveOutputDir(projectRoot: string, preset?: string): string {
   if (preset === 'vercel' || preset === 'vercel-static') return path.resolve(projectRoot, '.vercel/output');
   return path.resolve(projectRoot, '.output');
@@ -140,10 +153,7 @@ export async function createViteConfig(
         database: true,
       },
       database: {
-        default: {
-          connector: 'sqlite',
-          options: { name: 'chronicle-search' },
-        },
+        default: getDatabaseConnector(preset),
       },
     },
   };

package/src/themes/default/ContentDirButtons.tsx

@@ -19,7 +19,7 @@ export function ContentDirButtons() {
   const { visible, overflow } = splitContentButtons(entries, MAX_VISIBLE);
 
   return (
-    <Flex gap='small' align='center'>
+    <Flex gap={3} align='center'>
       {visible.map(entry => (
         <RouterLink
           key={entry.href}

package/src/themes/default/Layout.tsx

@@ -22,6 +22,7 @@ import { getLandingEntries } from '@/lib/config';
 import { getActiveContentDir } from '@/lib/navigation';
 import { usePageContext } from '@/lib/page-context';
 import type { Node, Root } from 'fumadocs-core/page-tree';
+import { NodeType } from '@/lib/tree-utils';
 import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
 import { OpenInAI } from './OpenInAI';
@@ -117,7 +118,7 @@ export function Layout({
           >
             <Sidebar.Header className={styles.sidebarHeader}>
               <SidebarLogo config={config} />
-              <Flex gap='small' align='center'>
+              <Flex gap={3} align='center'>
                 {config.search?.enabled && <Search />}
                 <ClientThemeSwitcher size={16} />
               </Flex>
@@ -186,8 +187,8 @@ export function Layout({
           <div className={styles.cardWrapper}>
             <div className={styles.card}>
               <nav className={styles.subNav}>
-                <Flex align='center' gap='small' className={styles.subNavLeft}>
-                  <Flex align='center' gap='extra-small'>
+                <Flex align='center' gap={3} className={styles.subNavLeft}>
+                  <Flex align='center' gap={2}>
                     <IconButton
                       size={2}
                       disabled={!prev}
@@ -207,7 +208,7 @@ export function Layout({
                   </Flex>
                   <Breadcrumbs slug={slug} tree={tree} />
                 </Flex>
-                <Flex align='center' gap='small'>
+                <Flex align='center' gap={3}>
                   {isApiRoute && <TestRequestButton />}
                   {isApiRoute && <ViewDocsButton />}
                   <OpenInAI />
@@ -224,6 +225,15 @@ export function Layout({
   );
 }
 
+function hasActiveDescendant(node: Node, pathname: string): boolean {
+  if (node.type === NodeType.Page) return pathname === node.url;
+  if (node.type === NodeType.Folder) {
+    if (node.index && pathname === node.index.url) return true;
+    return node.children.some(child => hasActiveDescendant(child, pathname));
+  }
+  return false;
+}
+
 function SidebarNode({
   item,
   pathname,
@@ -240,6 +250,7 @@ function SidebarNode({
   if (item.type === 'folder') {
     if (depth > 1) return null;
     const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
+    const hasActiveChild = hasActiveDescendant(item, pathname);
     return (
       <Sidebar.Group
         className={styles.navGroup}
@@ -247,6 +258,7 @@ function SidebarNode({
         label={item.name?.toString() ?? ''}
         leadingIcon={icon ?? undefined}
         collapsible={depth === 1}
+        defaultOpen={hasActiveChild}
         classNames={{
           items: styles.groupItems,
           header: styles.navGroupHeader,
@@ -305,7 +317,7 @@ function ApiSidebarNode({ item, pathname }: { item: Node; pathname: string }) {
 
   if (item.type === 'folder') {
     return (
-      <Flex direction='column' gap='small' className={styles.apiGroup}>
+      <Flex direction='column' gap={3} className={styles.apiGroup}>
         <span className={styles.apiGroupLabel}>{item.name?.toString()}</span>
         <Flex direction='column'>
           {item.children.map((child, i) => (
@@ -329,7 +341,7 @@ function ApiSidebarNode({ item, pathname }: { item: Node; pathname: string }) {
   return (
     <Flex
       align='center'
-      gap='small'
+      gap={3}
       className={`${styles.apiItem} ${isActive ? styles.apiItemActive : ''}`}
       render={<RouterLink to={href} />}
     >

package/src/themes/default/Page.module.css

@@ -125,3 +125,12 @@
 .content details > :not(summary) {
   padding: var(--rs-space-4) var(--rs-space-5);
 }
+
+.loader {
+  flex: 1;
+  margin-bottom: var(--rs-space-3);
+}
+
+.headerLoader {
+  margin-bottom: var(--rs-space-5);
+}

package/src/themes/default/Skeleton.tsx

@@ -6,21 +6,11 @@ export function PageSkeleton() {
   return (
     <Flex className={styles.page}>
       <article className={styles.article}>
-        <Skeleton width="40%" height="32px" />
-        <Skeleton.Provider duration={2}>
-          <Skeleton width="100%" height="16px" />
-          <Skeleton width="95%" height="16px" />
-          <Skeleton width="80%" height="16px" />
-          <Skeleton width="100%" height="16px" />
-          <Skeleton width="60%" height="16px" />
-        </Skeleton.Provider>
-        <Skeleton width="30%" height="24px" />
-        <Skeleton.Provider duration={2}>
-          <Skeleton width="100%" height="16px" />
-          <Skeleton width="90%" height="16px" />
-          <Skeleton width="100%" height="16px" />
-          <Skeleton width="70%" height="16px" />
-        </Skeleton.Provider>
+        <Skeleton width="40%" height="var(--rs-line-height-t2)" containerClassName={styles.headerLoader} />
+        <Skeleton width="60%" height="var(--rs-line-height-regular)" containerClassName={styles.headerLoader} />
+        {[...new Array(20)].map((_, i) => (
+          <Skeleton key={i} width="100%" height="var(--rs-line-height-regular)" containerClassName={styles.loader} />
+        ))}
       </article>
     </Flex>
   );

package/src/themes/default/VersionSwitcher.tsx

@@ -28,7 +28,7 @@ export function VersionSwitcher() {
           />
         }
       >
-        <Flex gap='small' align='center'>
+        <Flex gap={3} align='center'>
           {active?.label ?? 'Version'}
           {active?.badge ? (
             <Badge variant={active.badge.variant} size='micro'>
@@ -43,7 +43,7 @@ export function VersionSwitcher() {
             key={v.dir ?? '_latest'}
             onClick={() => navigate(getVersionHomeHref(config, v.dir))}
           >
-            <Flex gap='small' align='center'>
+            <Flex gap={3} align='center'>
               {v.label}
               {v.badge ? (
                 <Badge variant={v.badge.variant} size='micro'>

package/src/themes/paper/VersionSwitcher.tsx

@@ -29,7 +29,7 @@ export function VersionSwitcher() {
           />
         }
       >
-        <Flex gap='small' align='center' justify='start'>
+        <Flex gap={3} align='center' justify='start'>
           {active?.label ?? 'Version'}
           {active?.badge ? (
             <Badge variant={active.badge.variant} size='micro'>
@@ -44,7 +44,7 @@ export function VersionSwitcher() {
             key={v.dir ?? '_latest'}
             onClick={() => navigate(getVersionHomeHref(config, v.dir))}
           >
-            <Flex gap='small' align='center'>
+            <Flex gap={3} align='center'>
               {v.label}
               {v.badge ? (
                 <Badge variant={v.badge.variant} size='micro'>

package/src/types/config.ts

@@ -131,6 +131,12 @@ const RESERVED_ROUTE_SEGMENTS = [
   'sitemap.xml',
 ] as const
 
+const redirectSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  permanent: z.boolean().optional(),
+})
+
 export const chronicleConfigSchema = z
   .object({
     site: siteSchema,
@@ -144,6 +150,7 @@ export const chronicleConfigSchema = z
     navigation: navigationSchema.optional(),
     search: searchSchema.optional(),
     api: z.array(apiSchema).optional(),
+    redirects: z.array(redirectSchema).optional(),
     analytics: analyticsSchema.optional(),
     telemetry: telemetrySchema.optional(),
   })
@@ -225,6 +232,7 @@ export type SocialLink = z.infer<typeof socialLinkSchema>
 export type SearchConfig = z.infer<typeof searchSchema>
 export type ApiConfig = z.infer<typeof apiSchema>
 export type ApiServerConfig = z.infer<typeof apiServerSchema>
+export type RedirectConfig = z.infer<typeof redirectSchema>
 export type ApiAuthConfig = z.infer<typeof apiAuthSchema>
 export type AnalyticsConfig = z.infer<typeof analyticsSchema>
 export type GoogleAnalyticsConfig = z.infer<typeof googleAnalyticsSchema>

package/src/components/common/breadcrumb.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { Breadcrumb } from '@raystack/apsara'

package/src/components/common/button.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { Button } from '@raystack/apsara'

package/src/components/common/code-block.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { CodeBlock } from '@raystack/apsara'

package/src/components/common/dialog.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { Dialog } from '@raystack/apsara'

package/src/components/common/index.ts

@@ -1,10 +0,0 @@
-export { Sidebar } from './sidebar'
-export { Table } from './table'
-export { Dialog } from './dialog'
-export { InputField } from './input-field'
-export { Tabs } from './tabs'
-export { Breadcrumb } from './breadcrumb'
-export { Button } from './button'
-export { CodeBlock } from './code-block'
-export { Callout } from './callout'
-export { Switch } from './switch'

package/src/components/common/input-field.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { InputField } from '@raystack/apsara'

package/src/components/common/sidebar.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { Sidebar } from '@raystack/apsara'

package/src/components/common/switch.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { Switch } from '@raystack/apsara'

package/src/components/common/table.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { Table } from '@raystack/apsara'

package/src/components/common/tabs.tsx

@@ -1,3 +0,0 @@
-'use client'
-
-export { Tabs } from '@raystack/apsara'