@raystack/chronicle 0.8.0 → 0.10.0

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");
@@ -424,6 +436,12 @@ async function createViteConfig(options) {
       publicAssets: [{ dir: path6.resolve(projectRoot, "public") }],
       output: {
         dir: resolveOutputDir(projectRoot, preset)
+      },
+      experimental: {
+        database: true
+      },
+      database: {
+        default: getDatabaseConnector(preset)
       }
     }
   };
@@ -449,7 +467,7 @@ import chalk from "chalk";
 import { parse } from "yaml";
 
 // src/types/config.ts
-import uniqBy from "lodash/uniqBy.js";
+import { uniqBy } from "lodash-es";
 import { z } from "zod";
 var logoSchema = z.object({
   light: z.string().optional(),
@@ -552,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(),
@@ -564,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), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -23,7 +23,7 @@
     "@biomejs/biome": "^2.3.13",
     "@raystack/tools-config": "0.56.0",
     "@types/hast": "^3.0.4",
-    "@types/lodash": "^4.17.23",
+    "@types/lodash-es": "^4.17.12",
     "@types/mdast": "^4.0.4",
     "@types/mdx": "^2.0.13",
     "@types/node": "^25.1.0",
@@ -59,9 +59,9 @@
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "h3": "^2.0.1-rc.16",
-    "lodash": "^4.17.23",
+    "http-status-codes": "^2.3.0",
+    "lodash-es": "^4.17.23",
     "mermaid": "^11.13.0",
-    "minisearch": "^7.2.0",
     "nitro": "3.0.260311-beta",
     "openapi-types": "^12.1.3",
     "react": "^19.0.0",

package/src/components/ui/search.module.css

@@ -13,6 +13,7 @@
 
 .list {
   max-height: 400px;
+  gap: var(--rs-space-3);
 }
 
 .list :global([cmdk-group-heading]) {
@@ -24,13 +25,14 @@
 }
 
 .item {
-  height: 32px;
+  min-height: 40px;
   padding: var(--rs-space-3);
   gap: var(--rs-space-3);
   border-radius: var(--rs-radius-2);
   cursor: pointer;
 }
 
+
 .item[data-selected="true"] {
   background: var(--rs-color-background-base-primary-hover);
 }
@@ -43,8 +45,9 @@
 
 .resultText {
   display: flex;
-  align-items: center;
-  gap: 8px;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
 }
 
 .headingText {
@@ -68,16 +71,35 @@
 }
 
 .icon {
-  width: 18px;
-  height: 18px;
+  width: 48px;
+  height: 24px;
   color: var(--rs-color-foreground-base-secondary);
   flex-shrink: 0;
 }
 
+.itemContent :global([class*="badge-module"]) {
+  min-width: 48px;
+  justify-content: center;
+}
+
 .item[data-selected="true"] .icon {
   color: var(--rs-color-foreground-accent-primary-hover);
 }
 
+.snippetText {
+  font-size: var(--rs-font-size-mini);
+  line-height: var(--rs-line-height-mini);
+  color: var(--rs-color-foreground-base-tertiary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.matchHighlight {
+  color: var(--rs-color-foreground-accent-primary);
+  font-weight: var(--rs-font-weight-medium);
+}
+
 .pageText :global(mark),
 .headingText :global(mark) {
   background: transparent;

package/src/components/ui/search.tsx

@@ -4,7 +4,7 @@ import {
   MagnifyingGlassIcon
 } from '@heroicons/react/24/outline';
 import { Command, IconButton, Text } from '@raystack/apsara';
-import debounce from 'lodash/debounce';
+import { debounce } from 'lodash-es';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
@@ -16,6 +16,8 @@ interface SearchResult {
   url: string;
   type: string;
   content: string;
+  match?: 'title' | 'heading' | 'body';
+  snippet?: string;
 }
 
 interface SearchProps {
@@ -121,7 +123,7 @@ export function Search({ classNames }: SearchProps) {
 
       <Command.Dialog open={open} onOpenChange={setOpen}>
         <Command.DialogContent className={styles.dialogContent}>
-          <Command>
+          <Command items={displayResults}>
             <Command.Input
               placeholder='Search'
               leadingIcon={<MagnifyingGlassIcon width={16} height={16} />}
@@ -171,23 +173,17 @@ export function Search({ classNames }: SearchProps) {
                     <div className={styles.itemContent}>
                       {getResultIcon(result)}
                       <div className={styles.resultText}>
-                        {result.type === 'heading' ? (
-                          <>
-                            <Text className={styles.headingText}>
-                              <HighlightedText
-                                html={stripMethod(result.content)}
-                              />
-                            </Text>
-                            <Text className={styles.separator}>-</Text>
-                            <Text className={styles.pageText}>
-                              {getPageTitle(result.url)}
-                            </Text>
-                          </>
-                        ) : (
-                          <Text className={styles.pageText}>
-                            <HighlightedText
-                              html={stripMethod(result.content)}
-                            />
+                        <Text className={styles.pageText}>
+                          <HighlightQuery text={stripMethod(result.content)} query={search} />
+                        </Text>
+                        {result.snippet && result.match === 'heading' && (
+                          <Text className={styles.snippetText}>
+                            # <HighlightQuery text={result.snippet} query={search} />
+                          </Text>
+                        )}
+                        {result.snippet && result.match === 'body' && (
+                          <Text className={styles.snippetText}>
+                            <HighlightQuery text={result.snippet} query={search} />
                           </Text>
                         )}
                       </div>
@@ -236,6 +232,19 @@ function HighlightedText({
   );
 }
 
+function HighlightQuery({ text, query }: { text: string; query: string }) {
+  if (!query) return <>{text}</>;
+  const idx = text.toLowerCase().indexOf(query.toLowerCase());
+  if (idx < 0) return <>{text}</>;
+  return (
+    <>
+      {text.slice(0, idx)}
+      <span className={styles.matchHighlight}>{text.slice(idx, idx + query.length)}</span>
+      {text.slice(idx + query.length)}
+    </>
+  );
+}
+
 function getResultIcon(result: SearchResult): React.ReactNode {
   if (!result.url.startsWith('/apis/')) {
     return result.type === 'page' ? (

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/page-context.tsx

@@ -116,7 +116,7 @@ export function PageProvider({
   const fetchPageData = useCallback(async (slug: string[]): Promise<PageData> => {
     const apiPath = slug.length === 0
       ? '/api/page'
-      : `/api/page?slug=${slug.join(',')}`;
+      : `/api/page?slug=${slug.map(s => encodeURIComponent(s)).join(',')}`;
     const res = await fetch(apiPath);
     if (!res.ok) throw new Error(String(res.status));
     return res.json();

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

@@ -1,6 +1,15 @@
+import fs from 'node:fs/promises';
+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 {
@@ -118,14 +127,12 @@ export function invalidate() {
   cachedNavMap = 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.index) {
-      const fromMeta = folderOrderMap.get(node.index.url);
-      if (fromMeta !== undefined) return fromMeta;
-      return pageOrderMap.get(node.index.url);
-    }
+  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);
   }
   return undefined;
 }
@@ -259,6 +266,35 @@ export function getOriginalPath(page: { data: unknown }): string {
   return ((page.data as Record<string, unknown>)._originalPath as string) ?? '';
 }
 
+export async function getPageSearchContent(page: { data: unknown }): Promise<{ headings: string; body: string }> {
+  const originalPath = getOriginalPath(page);
+  if (!originalPath) return { headings: '', body: '' };
+  try {
+    const contentDir = typeof __CHRONICLE_CONTENT_DIR__ !== 'undefined' ? __CHRONICLE_CONTENT_DIR__ : process.cwd();
+    const filePath = path.resolve(contentDir, originalPath);
+    const raw = await fs.readFile(filePath, 'utf-8');
+    const withoutFrontmatter = raw.replace(/^---[\s\S]*?---/m, '');
+    const headings: string[] = [];
+    const lines: string[] = [];
+    for (const line of withoutFrontmatter.split('\n')) {
+      const headingMatch = line.match(/^#{1,6}\s+(.+)/);
+      if (headingMatch) {
+        headings.push(headingMatch[1]);
+      } else if (!line.startsWith('import ') && !line.startsWith('export ') && !line.startsWith('```')) {
+        const cleaned = line
+          .replace(/<[^>]+>/g, '')
+          .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+          .replace(/[*_~`]+/g, '')
+          .trim();
+        if (cleaned) lines.push(cleaned);
+      }
+    }
+    return { headings: headings.join('\n'), body: lines.join(' ') };
+  } catch {
+    return { headings: '', body: '' };
+  }
+}
+
 interface ReadingTime {
   text: string;
   minutes: number;

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/api/ready.ts

@@ -0,0 +1,15 @@
+import { defineHandler } from 'nitro';
+import { isSearchReady } from './search';
+
+export default defineHandler(() => {
+  const searchReady = isSearchReady();
+
+  if (!searchReady) {
+    return Response.json(
+      { status: 'not_ready', search: false },
+      { status: 503 },
+    );
+  }
+
+  return Response.json({ status: 'ready', search: true });
+});

package/src/server/api/search.ts

@@ -1,79 +1,129 @@
-import MiniSearch from 'minisearch';
 import { defineHandler, HTTPError } from 'nitro';
+import { useDatabase } from 'nitro/database';
 import type { OpenAPIV3 } from 'openapi-types';
 import { getSpecSlug } from '@/lib/api-routes';
 import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
-import { extractFrontmatter, getPagesForVersion } from '@/lib/source';
+import { extractFrontmatter, getPageSearchContent, getPagesForVersion } from '@/lib/source';
 import { LATEST_CONTEXT, type VersionContext } from '@/lib/version-source';
 
 interface SearchDocument {
   id: string;
   url: string;
   title: string;
-  content: string;
+  headings: string;
+  body: string;
   type: 'page' | 'api';
 }
 
-const indexCache = new Map<string, MiniSearch<SearchDocument>>();
-const docsCache = new Map<string, SearchDocument[]>();
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 
-function keyFor(ctx: VersionContext): string {
+const LOCK_FILE = path.join(os.tmpdir(), 'chronicle-search-ready');
+
+export const indexedVersions = new Set<string>();
+let indexPromise: Promise<void> | null = null;
+
+function versionKey(ctx: VersionContext): string {
   return ctx.dir ?? '__latest__';
 }
 
-function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
-  const index = new MiniSearch<SearchDocument>({
-    fields: ['title', 'content'],
-    storeFields: ['url', 'title', 'type'],
-    searchOptions: {
-      boost: { title: 2 },
-      fuzzy: 0.2,
-      prefix: true
-    }
-  });
-  index.addAll(docs);
-  return index;
+// biome-ignore lint/suspicious/noEmptyBlockStatements: intentional no-op catch
+fs.unlink(LOCK_FILE).catch(() => {});
+
+export function isSearchReady(): boolean {
+  return existsSync(LOCK_FILE);
+}
+
+export async function ensureIndex(ctx: VersionContext) {
+  const key = versionKey(ctx);
+  if (indexedVersions.has(key)) return;
+  if (indexPromise) return indexPromise;
+  indexPromise = buildIndex(ctx, key);
+  await indexPromise;
+  indexPromise = null;
+  await fs.writeFile(LOCK_FILE, new Date().toISOString());
+}
+
+async function buildIndex(ctx: VersionContext, key: string) {
+  // biome-ignore lint/correctness/useHookAtTopLevel: useDatabase is a Nitro DI accessor, not a React hook
+  const db = useDatabase();
+
+  await db.exec('DROP TABLE IF EXISTS search_fts');
+  await db.exec('DROP TABLE IF EXISTS search_docs');
+
+  await db.exec(`CREATE TABLE IF NOT EXISTS search_docs (
+    id TEXT PRIMARY KEY,
+    url TEXT NOT NULL,
+    title TEXT NOT NULL,
+    headings TEXT NOT NULL,
+    body TEXT NOT NULL,
+    type TEXT NOT NULL,
+    version TEXT NOT NULL
+  )`);
+
+  await db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
+    title,
+    headings,
+    body,
+    content=search_docs,
+    content_rowid=rowid
+  )`);
+
+  const docs = await buildDocs(ctx);
+  for (const doc of docs) {
+    await db.sql`INSERT INTO search_docs (id, url, title, headings, body, type, version)
+      VALUES (${doc.id}, ${doc.url}, ${doc.title}, ${doc.headings}, ${doc.body}, ${doc.type}, ${key})`;
+  }
+
+  await db.sql`INSERT INTO search_fts (rowid, title, headings, body)
+    SELECT rowid, title, headings, body FROM search_docs WHERE version = ${key}`;
+
+  indexedVersions.add(key);
 }
 
-async function scanContent(ctx: VersionContext): Promise<SearchDocument[]> {
+async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
+  const docs: SearchDocument[] = [];
+
   const pages = await getPagesForVersion(ctx);
-  return pages.map(p => {
+  for (const p of pages) {
     const fm = extractFrontmatter(p);
-    return {
+    const { headings, body } = await getPageSearchContent(p);
+    docs.push({
       id: p.url,
       url: p.url,
       title: fm.title,
-      content: fm.description ?? '',
-      type: 'page' as const
-    };
-  });
-}
+      headings,
+      body: [fm.description ?? '', body].join(' '),
+      type: 'page',
+    });
+  }
 
-async function buildApiDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   const config = loadConfig();
   const apiConfigs = getApiConfigsForVersion(config, ctx.dir);
-  if (!apiConfigs.length) return [];
-
-  const docs: SearchDocument[] = [];
-  const specs = await loadApiSpecs(apiConfigs);
-
-  for (const spec of specs) {
-    const specSlug = getSpecSlug(spec);
-    const paths = spec.document.paths ?? {};
-    for (const [, pathItem] of Object.entries(paths)) {
-      if (!pathItem) continue;
-      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 = `${ctx.urlPrefix}/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
-        docs.push({
-          id: url,
-          url,
-          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
-          content: op.description ?? '',
-          type: 'api'
-        });
+  if (apiConfigs.length) {
+    const specs = await loadApiSpecs(apiConfigs);
+    for (const spec of specs) {
+      const specSlug = getSpecSlug(spec);
+      const paths = spec.document.paths ?? {};
+      for (const [pathStr, pathItem] of Object.entries(paths)) {
+        if (!pathItem) continue;
+        for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+          const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+          if (!op) continue;
+          const opId = op.operationId ?? `${method}_${pathStr.replace(/[/{}\-]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+          const url = `${ctx.urlPrefix}/apis/${specSlug}/${encodeURIComponent(opId)}`;
+          docs.push({
+            id: url,
+            url,
+            title: `${method.toUpperCase()} ${op.summary ?? opId}`,
+            headings: op.summary ?? opId,
+            body: [op.description ?? '', pathStr, method.toUpperCase()].join(' '),
+            type: 'api',
+          });
+        }
       }
     }
   }
@@ -81,27 +131,32 @@ async function buildApiDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   return docs;
 }
 
-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(ctx),
-    buildApiDocs(ctx)
-  ]);
-  const docs = [...contentDocs, ...apiDocs];
-  docsCache.set(key, docs);
-  return docs;
-}
+function findMatch(
+  query: string,
+  title: string,
+  headings: string,
+  body: string,
+): { match: 'title' | 'heading' | 'body'; snippet: string } {
+  if (title.toLowerCase().includes(query)) {
+    return { match: 'title', snippet: title };
+  }
 
-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;
+  const headingList = headings.split('\n').filter(Boolean);
+  for (const h of headingList) {
+    if (h.toLowerCase().includes(query)) {
+      return { match: 'heading', snippet: h };
+    }
+  }
+
+  const idx = body.toLowerCase().indexOf(query);
+  if (idx >= 0) {
+    const start = Math.max(0, idx - 40);
+    const end = Math.min(body.length, idx + query.length + 80);
+    const snippet = (start > 0 ? '...' : '') + body.slice(start, end).trim() + (end < body.length ? '...' : '');
+    return { match: 'body', snippet };
+  }
+
+  return { match: 'title', snippet: title };
 }
 
 function resolveCtx(tag: string | null): VersionContext {
@@ -121,25 +176,44 @@ export default defineHandler(async event => {
   const query = event.url.searchParams.get('query') ?? '';
   const tag = event.url.searchParams.get('tag');
   const ctx = resolveCtx(tag);
-  const index = await getIndex(ctx);
+
+  await ensureIndex(ctx);
+  // biome-ignore lint/correctness/useHookAtTopLevel: useDatabase is a Nitro DI accessor, not a React hook
+  const db = useDatabase();
+  const key = versionKey(ctx);
 
   if (!query) {
-    const docs = await getDocs(ctx);
-    return Response.json(docs
-      .filter(d => d.type === 'page')
-      .slice(0, 8)
-      .map(d => ({
-        id: d.id,
-        url: d.url,
-        type: d.type,
-        content: d.title
-      })));
+    const result = await db.sql`SELECT id, url, title, type FROM search_docs
+      WHERE version = ${key} AND type = 'page'
+      LIMIT 8`;
+    return Response.json((result.rows ?? []).map(r => ({
+      id: r.id,
+      url: r.url,
+      type: r.type,
+      content: r.title,
+    })));
   }
 
-  return Response.json(index.search(query).map(r => ({
-    id: r.id,
-    url: r.url,
-    type: r.type,
-    content: r.title
-  })));
+  const searchTerm = query.split(/\s+/).map(t => `"${t}"*`).join(' ');
+  const result = await db.sql`SELECT s.id, s.url, s.title, s.headings, s.body, s.type,
+      bm25(search_fts, 10.0, 5.0, 1.0) AS score
+    FROM search_fts f
+    JOIN search_docs s ON s.rowid = f.rowid
+    WHERE search_fts MATCH ${searchTerm}
+      AND s.version = ${key}
+    ORDER BY score
+    LIMIT 20`;
+
+  const queryLower = query.toLowerCase();
+  return Response.json((result.rows ?? []).map(r => {
+    const { match, snippet } = findMatch(queryLower, r.title as string, r.headings as string, r.body as string);
+    return {
+      id: r.id,
+      url: r.url,
+      type: r.type,
+      content: r.title,
+      match,
+      snippet,
+    };
+  }));
 });

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;
@@ -120,7 +147,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/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');
@@ -136,6 +149,12 @@ export async function createViteConfig(
       output: {
         dir: resolveOutputDir(projectRoot, preset),
       },
+      experimental: {
+        database: true,
+      },
+      database: {
+        default: getDatabaseConnector(preset),
+      },
     },
   };
 }

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

@@ -11,6 +11,10 @@
   max-width: 768px;
 }
 
+.title {
+  margin: 0 0 var(--rs-space-8) 0;
+}
+
 .content {
   line-height: 1.7;
 }

package/src/themes/default/Page.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { Flex } from '@raystack/apsara';
+import { Flex, Headline } from '@raystack/apsara';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
 import { Toc } from './Toc';
@@ -9,6 +9,11 @@ export function Page({ page }: ThemePageProps) {
   return (
     <Flex className={styles.page}>
       <article className={styles.article} data-article-content>
+        {page.frontmatter.title && (
+          <Headline size="t2" render={<h1 />} className={styles.title}>
+            {page.frontmatter.title}
+          </Headline>
+        )}
         <div className={styles.content}>{page.content}</div>
       </article>
       <Toc items={page.toc} />

package/src/types/config.ts

@@ -1,4 +1,4 @@
-import uniqBy from 'lodash/uniqBy.js'
+import { uniqBy } from 'lodash-es'
 import { z } from 'zod'
 
 const logoSchema = z.object({
@@ -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>