@raystack/chronicle 0.10.1 → 0.10.3

package/dist/cli/index.js

@@ -46,6 +46,15 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/lib/mdx-utils.ts
+var MdxNodeType;
+var init_mdx_utils = __esm(() => {
+  MdxNodeType = {
+    JsxFlow: "mdxJsxFlowElement",
+    JsxText: "mdxJsxTextElement"
+  };
+});
+
 // src/lib/remark-resolve-images.ts
 import path4 from "node:path";
 import { visit } from "unist-util-visit";
@@ -72,16 +81,29 @@ var remarkResolveImages = () => {
       return;
     const relative = filePath.slice(contentIdx + "/content/".length);
     const dir = path4.posix.dirname(relative);
+    const seen = new Set;
+    const images = [];
+    function collect(src) {
+      if (!src || seen.has(src) || /^data:/i.test(src))
+        return;
+      seen.add(src);
+      images.push(src);
+    }
     visit(tree, "image", (node) => {
       if (!node.url)
         return;
       node.url = resolveUrl(node.url, dir);
+      collect(node.url);
     });
     visit(tree, "html", (node) => {
-      node.value = node.value.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (_, before, src, after) => `${before}${resolveUrl(src, dir)}${after}`);
+      node.value = node.value.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (_, before, src, after) => {
+        const resolved = resolveUrl(src, dir);
+        collect(resolved);
+        return `${before}${resolved}${after}`;
+      });
     });
     visit(tree, (node) => {
-      if (node.type !== "mdxJsxFlowElement" && node.type !== "mdxJsxTextElement")
+      if (node.type !== MdxNodeType.JsxFlow && node.type !== MdxNodeType.JsxText)
         return;
       const jsx = node;
       if (jsx.name !== "img")
@@ -90,6 +112,7 @@ var remarkResolveImages = () => {
       if (!srcAttr?.value || typeof srcAttr.value !== "string")
         return;
       srcAttr.value = resolveUrl(srcAttr.value, dir);
+      collect(srcAttr.value);
     });
     visit(tree, "element", (node) => {
       if (node.tagName !== "img")
@@ -98,10 +121,13 @@ var remarkResolveImages = () => {
       if (typeof src !== "string")
         return;
       node.properties.src = resolveUrl(src, dir);
+      collect(node.properties.src);
     });
+    file.data.images = images;
   };
 }, remark_resolve_images_default;
 var init_remark_resolve_images = __esm(() => {
+  init_mdx_utils();
   remark_resolve_images_default = remarkResolveImages;
 });
 
@@ -360,7 +386,7 @@ async function createViteConfig(options) {
         default: defineFumadocsConfig({
           mdxOptions: {
             remarkImageOptions: false,
-            valueToExport: ["readingTime"],
+            valueToExport: ["readingTime", "images"],
             remarkPlugins: [
               remarkDirective,
               [remarkDirectiveAdmonition, {
@@ -433,6 +459,7 @@ async function createViteConfig(options) {
     },
     nitro: {
       logLevel: 2,
+      errorHandler: path6.resolve(packageRoot, "src/server/error.ts"),
       publicAssets: [{ dir: path6.resolve(projectRoot, "public") }],
       output: {
         dir: resolveOutputDir(projectRoot, preset)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,6 +49,7 @@
     "@radix-ui/react-icons": "^1.3.2",
     "@raystack/apsara": "1.0.0-rc.7",
     "@shikijs/rehype": "^4.0.2",
+    "@tanstack/react-query": "5.100.10",
     "@vitejs/plugin-react": "^6.0.1",
     "chalk": "^5.6.2",
     "class-variance-authority": "^0.7.1",

package/src/components/api/api-overview.tsx

@@ -21,7 +21,7 @@ interface ApiOverviewProps {
   auth?: { type: string; header: string; placeholder?: string }
 }
 
-export function ApiOverview({ method, path, operation, auth }: ApiOverviewProps) {
+export function ApiOverview({ method, path, operation, serverUrl, auth }: ApiOverviewProps) {
   const params = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[]
   const body = getRequestBody(operation.requestBody as OpenAPIV3.RequestBodyObject | undefined)
 
@@ -36,7 +36,7 @@ export function ApiOverview({ method, path, operation, auth }: ApiOverviewProps)
       ? headerFields
       : []
 
-  const fullUrl = '{domain}' + path
+  const fullUrl = serverUrl + path
   const snippetHeaders: Record<string, string> = {}
   if (auth) snippetHeaders[auth.header] = auth.placeholder ?? 'YOUR_API_KEY'
   if (body) snippetHeaders['Content-Type'] = body.contentType ?? 'application/json'

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

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, useCallback, useMemo } from 'react'
+import { useState, useCallback, useMemo, useEffect } from 'react'
 import type { OpenAPIV3 } from 'openapi-types'
 import { Dialog, Button, Badge, IconButton, Input, CopyButton, Select, Menu } from '@raystack/apsara'
 import { Cross2Icon, ChevronDownIcon, ChevronUpIcon, PlayIcon, PlusIcon } from '@radix-ui/react-icons'
@@ -68,11 +68,21 @@ export function PlaygroundDialog({
 
   const authSchemes = useMemo(() => getAuthSchemes(document, auth), [document, auth])
   const defaultScheme = authSchemes.find((s) => s.type !== 'none') ?? authSchemes[0]
-
-  const [selectedScheme, setSelectedScheme] = useState(defaultScheme.name)
-  const [authToken, setAuthToken] = useState('')
-  const [basicUser, setBasicUser] = useState('')
-  const [basicPass, setBasicPass] = useState('')
+  const storageKey = `chronicle:auth:${specName}`
+  const savedAuth = useMemo(() => {
+    try {
+      const raw = sessionStorage.getItem(storageKey)
+      return raw ? JSON.parse(raw) : null
+    } catch { return null }
+  }, [storageKey])
+
+  const [selectedScheme, setSelectedScheme] = useState(() => {
+    if (savedAuth?.scheme && authSchemes.some((s) => s.name === savedAuth.scheme)) return savedAuth.scheme
+    return defaultScheme.name
+  })
+  const [authToken, setAuthToken] = useState(savedAuth?.token ?? '')
+  const [basicUser, setBasicUser] = useState(savedAuth?.basicUser ?? '')
+  const [basicPass, setBasicPass] = useState(savedAuth?.basicPass ?? '')
   const [headerValues, setHeaderValues] = useState<Record<string, string>>({})
   const [pathValues, setPathValues] = useState<Record<string, string>>({})
   const [queryValues, setQueryValues] = useState<Record<string, string>>({})
@@ -89,6 +99,17 @@ export function PlaygroundDialog({
   })
   const [bodyJsonStr, setBodyJsonStr] = useState(() => body ? body.jsonExample : '{}')
 
+  useEffect(() => {
+    try {
+      sessionStorage.setItem(storageKey, JSON.stringify({
+        scheme: selectedScheme,
+        token: authToken,
+        basicUser,
+        basicPass,
+      }))
+    } catch { /* ignore */ }
+  }, [storageKey, selectedScheme, authToken, basicUser, basicPass])
+
   const [responseData, setResponseData] = useState<{
     status: number; statusText: string; body: unknown; headers?: Record<string, string>; time: number
   } | null>(null)
@@ -119,6 +140,7 @@ export function PlaygroundDialog({
     setAuthToken('')
     setBasicUser('')
     setBasicPass('')
+    try { sessionStorage.removeItem(storageKey) } catch { /* ignore */ }
     setHeaderValues({})
     setPathValues({})
     setQueryValues({})

package/src/components/mdx/paragraph.tsx

@@ -1,7 +1,7 @@
 import { Children, isValidElement, type ComponentProps } from 'react'
 import styles from './paragraph.module.css'
 
-const BLOCK_ELEMENTS = new Set(['summary', 'details', 'div', 'table', 'ul', 'ol'])
+const BLOCK_ELEMENTS = new Set(['summary', 'details', 'div', 'table', 'ul', 'ol', 'p'])
 
 function hasBlockChild(children: React.ReactNode): boolean {
   return Children.toArray(children).some(

package/src/components/ui/PrefetchProvider.tsx

@@ -0,0 +1,72 @@
+import { useEffect } from 'react';
+import { prefetchPageData } from '@/lib/preload';
+
+const NO_PREFETCH_ATTR = 'data-no-prefetch';
+
+function resolvePathname(href: string | null): string | null {
+  if (!href) return null;
+  try {
+    const url = new URL(href, location.href);
+    if (url.origin !== location.origin) return null;
+    return url.pathname;
+  } catch {
+    return null;
+  }
+}
+
+export function PrefetchProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    const handleMouseOver = (e: MouseEvent) => {
+      const anchor = (e.target as HTMLElement).closest?.('a[href]');
+      if (!anchor || anchor.hasAttribute(NO_PREFETCH_ATTR)) return;
+      const pathname = resolvePathname(anchor.getAttribute('href'));
+      if (pathname) prefetchPageData(pathname);
+    };
+
+    const handleFocusIn = (e: FocusEvent) => {
+      const anchor = (e.target as HTMLElement).closest?.('a[href]');
+      if (!anchor || anchor.hasAttribute(NO_PREFETCH_ATTR)) return;
+      const pathname = resolvePathname(anchor.getAttribute('href'));
+      if (pathname) prefetchPageData(pathname);
+    };
+
+    document.addEventListener('mouseover', handleMouseOver);
+    document.addEventListener('focusin', handleFocusIn);
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            const pathname = resolvePathname((entry.target as HTMLAnchorElement).getAttribute('href'));
+            if (pathname) prefetchPageData(pathname);
+            observer.unobserve(entry.target);
+          }
+        }
+      },
+      { rootMargin: '200px' },
+    );
+
+    const observeLinks = () => {
+      document.querySelectorAll(`a[href]:not([data-prefetch-observed]):not([${NO_PREFETCH_ATTR}])`).forEach((link) => {
+        const pathname = resolvePathname(link.getAttribute('href'));
+        if (pathname) {
+          link.setAttribute('data-prefetch-observed', '');
+          observer.observe(link);
+        }
+      });
+    };
+
+    const mutationObserver = new MutationObserver(observeLinks);
+    mutationObserver.observe(document.body, { childList: true, subtree: true });
+    observeLinks();
+
+    return () => {
+      document.removeEventListener('mouseover', handleMouseOver);
+      document.removeEventListener('focusin', handleFocusIn);
+      observer.disconnect();
+      mutationObserver.disconnect();
+    };
+  }, []);
+
+  return children;
+}

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

@@ -41,6 +41,12 @@
   display: flex;
   align-items: center;
   gap: 12px;
+  flex: 1;
+}
+
+.sectionBadge {
+  margin-left: auto;
+  flex-shrink: 0;
 }
 
 .resultText {

package/src/components/ui/search.tsx

@@ -3,7 +3,7 @@ import {
   HashtagIcon,
   MagnifyingGlassIcon
 } from '@heroicons/react/24/outline';
-import { Command, IconButton, Text } from '@raystack/apsara';
+import { Badge, Command, IconButton, Text } from '@raystack/apsara';
 import { debounce } from 'lodash-es';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
@@ -18,6 +18,7 @@ interface SearchResult {
   content: string;
   match?: 'title' | 'heading' | 'body';
   snippet?: string;
+  section?: string;
 }
 
 interface SearchProps {
@@ -157,6 +158,7 @@ export function Search({ classNames }: SearchProps) {
                               html={stripMethod(result.content)}
                             />
                           </Text>
+                          {result.section && <Badge size="small" className={styles.sectionBadge}>{result.section}</Badge>}
                         </div>
                       </Command.Item>
                     ))}
@@ -187,6 +189,7 @@ export function Search({ classNames }: SearchProps) {
                           </Text>
                         )}
                       </div>
+                      {result.section && <Badge size="small" className={styles.sectionBadge}>{result.section}</Badge>}
                     </div>
                   </Command.Item>
                 ))}

package/src/lib/env.ts

@@ -0,0 +1,9 @@
+export function substituteEnvVars(value: string): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, name) => {
+    const val = process.env[name];
+    if (val === undefined) {
+      throw new Error(`Environment variable '${name}' is not set`);
+    }
+    return val;
+  });
+}

package/src/lib/mdx-utils.ts

@@ -0,0 +1,4 @@
+export const MdxNodeType = {
+  JsxFlow: 'mdxJsxFlowElement',
+  JsxText: 'mdxJsxTextElement',
+} as const

package/src/lib/openapi.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import type { OpenAPIV2, OpenAPIV3 } from 'openapi-types'
 import type { ApiConfig, ApiServerConfig, ApiAuthConfig } from '@/types/config'
+import { substituteEnvVars } from '@/lib/env'
 
 type JsonObject = Record<string, unknown>
 
@@ -41,7 +42,7 @@ export async function loadApiSpec(config: ApiConfig, projectRoot: string): Promi
   return {
     name: config.name,
     basePath: config.basePath,
-    server: config.server,
+    server: { ...config.server, url: substituteEnvVars(config.server.url) },
     auth: config.auth,
     document: v3Doc,
   }

package/src/lib/page-context.tsx

@@ -13,6 +13,7 @@ import { resolveRoute, RouteType } from '@/lib/route-resolver';
 import type { VersionContext } from '@/lib/version-source';
 import { LATEST_CONTEXT } from '@/lib/version-source';
 import type { ChronicleConfig, Frontmatter, Page, PageNavLink, Root, TableOfContents } from '@/types';
+import { queryClient } from '@/lib/preload';
 
 export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
@@ -109,17 +110,22 @@ export function PageProvider({
     frontmatter: Frontmatter;
     relativePath: string;
     originalPath?: string;
+    images?: string[];
     prev?: PageNavLink | null;
     next?: PageNavLink | null;
   }
 
   const fetchPageData = useCallback(async (slug: string[]): Promise<PageData> => {
-    const apiPath = slug.length === 0
-      ? '/api/page'
-      : `/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();
+    const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
+    const apiPath = key ? `/api/page?slug=${key}` : '/api/page';
+    return queryClient.fetchQuery({
+      queryKey: ['pageData', key],
+      queryFn: async () => {
+        const res = await fetch(apiPath);
+        if (!res.ok) throw new Error(String(res.status));
+        return res.json();
+      },
+    });
   }, []);
 
   const loadDocsPage = useCallback(async (slug: string[], cancelled: { current: boolean }) => {
@@ -127,6 +133,12 @@ export function PageProvider({
     try {
       const data = await fetchPageData(slug);
       if (cancelled.current) return;
+      if (data.images?.length) {
+        for (const src of data.images) {
+          const img = new Image();
+          img.src = src;
+        }
+      }
       const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
       if (cancelled.current) return;
       setErrorStatus(null);

package/src/lib/preload.ts

@@ -0,0 +1,42 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: Infinity,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+export function pageDataQueryKey(pathname: string) {
+  const slug = pathname.split('/').filter(Boolean);
+  const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
+  return ['pageData', key] as const;
+}
+
+async function fetchPageDataByPathname(pathname: string) {
+  const slug = pathname.split('/').filter(Boolean);
+  const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
+  const apiPath = key ? `/api/page?slug=${key}` : '/api/page';
+  const res = await fetch(apiPath);
+  if (!res.ok) throw new Error(String(res.status));
+  return res.json();
+}
+
+function isApisRoute(pathname: string): boolean {
+  return pathname === '/apis' || pathname.startsWith('/apis/');
+}
+
+function hasFileExtension(pathname: string): boolean {
+  const lastSegment = pathname.split('/').pop() ?? '';
+  return lastSegment.includes('.');
+}
+
+export function prefetchPageData(pathname: string) {
+  if (isApisRoute(pathname) || hasFileExtension(pathname)) return;
+  queryClient.prefetchQuery({
+    queryKey: pageDataQueryKey(pathname),
+    queryFn: () => fetchPageDataByPathname(pathname),
+  });
+}

package/src/lib/remark-resolve-images.ts

@@ -4,6 +4,7 @@ import type { Plugin } from 'unified'
 import type { Image, Html } from 'mdast'
 import type { Element } from 'hast'
 import type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute } from 'mdast-util-mdx-jsx'
+import { MdxNodeType } from './mdx-utils'
 
 function resolveUrl(src: string, dir: string): string {
   if (/^[a-z][a-z0-9+\-.]*:/i.test(src)) return src
@@ -26,25 +27,40 @@ const remarkResolveImages: Plugin = () => {
     const relative = filePath.slice(contentIdx + '/content/'.length)
     const dir = path.posix.dirname(relative)
 
+    const seen = new Set<string>()
+    const images: string[] = []
+
+    function collect(src: string) {
+      if (!src || seen.has(src) || /^data:/i.test(src)) return
+      seen.add(src)
+      images.push(src)
+    }
+
     visit(tree, 'image', (node: Image) => {
       if (!node.url) return
       node.url = resolveUrl(node.url, dir)
+      collect(node.url)
     })
 
     visit(tree, 'html', (node: Html) => {
       node.value = node.value.replace(
         /(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi,
-        (_, before, src, after) => `${before}${resolveUrl(src, dir)}${after}`
+        (_, before, src, after) => {
+          const resolved = resolveUrl(src, dir)
+          collect(resolved)
+          return `${before}${resolved}${after}`
+        }
       )
     })
 
     visit(tree, (node) => {
-      if (node.type !== 'mdxJsxFlowElement' && node.type !== 'mdxJsxTextElement') return
+      if (node.type !== MdxNodeType.JsxFlow && node.type !== MdxNodeType.JsxText) return
       const jsx = node as MdxJsxFlowElement | MdxJsxTextElement
       if (jsx.name !== 'img') return
       const srcAttr = jsx.attributes.find((a): a is MdxJsxAttribute => a.type === 'mdxJsxAttribute' && a.name === 'src')
       if (!srcAttr?.value || typeof srcAttr.value !== 'string') return
       srcAttr.value = resolveUrl(srcAttr.value, dir)
+      collect(srcAttr.value)
     })
 
     visit(tree, 'element', (node: Element) => {
@@ -52,7 +68,10 @@ const remarkResolveImages: Plugin = () => {
       const src = node.properties?.src
       if (typeof src !== 'string') return
       node.properties.src = resolveUrl(src, dir)
+      collect(node.properties.src as string)
     })
+
+    file.data.images = images
   }
 }
 

package/src/lib/source.ts

@@ -37,6 +37,11 @@ const readingTimeGlob: Record<string, { text: string; minutes: number; words: nu
   { eager: true, import: 'readingTime' }
 );
 
+const imagesGlob: Record<string, string[] | undefined> = import.meta.glob(
+  '../../.content/**/*.{mdx,md}',
+  { eager: true, import: 'images' }
+);
+
 const metaGlob: Record<string, Record<string, unknown>> = import.meta.glob(
   '../../.content/**/meta.json',
   { eager: true }
@@ -54,10 +59,11 @@ function buildFiles() {
     const relativePath = originalPath.replace(/readme\.(mdx?)$/i, 'index.$1');
     const rt = readingTimeGlob[key];
     const _readingTime = rt?.minutes != null ? Math.max(1, Math.round(rt.minutes)) : undefined;
+    const _images = imagesGlob[key] ?? [];
     files.push({
       type: 'page',
       path: relativePath,
-      data: { ...data, _readingTime, _relativePath: relativePath, _originalPath: originalPath }
+      data: { ...data, _readingTime, _images, _relativePath: relativePath, _originalPath: originalPath }
     });
   }
 
@@ -174,17 +180,31 @@ function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[], me
   return { ...tree, children: sortNodes(tree.children, pageOrderMap, folderOrderMap) };
 }
 
+function filterDraftsFromTree(tree: Root, draftUrls: Set<string>): Root {
+  function filterNodes(nodes: Node[]): Node[] {
+    return nodes
+      .filter(n => n.type !== NodeType.Page || !draftUrls.has(n.url))
+      .map(n => n.type === NodeType.Folder
+        ? { ...n, children: filterNodes(n.children) } as Folder
+        : n
+      );
+  }
+  return { ...tree, children: filterNodes(tree.children) };
+}
+
 export async function getPageTree(): Promise<Root> {
   if (cachedTree) return cachedTree;
   const s = await getSource();
   const metaFiles = buildFiles().filter(f => f.type === 'meta') as { path: string; data: Record<string, unknown> }[];
-  cachedTree = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
+  const sorted = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
+  const draftUrls = new Set(s.getPages().filter(p => isDraft(p)).map(p => p.url));
+  cachedTree = draftUrls.size > 0 ? filterDraftsFromTree(sorted, draftUrls) : sorted;
   return cachedTree;
 }
 
 export async function getPages() {
   const s = await getSource();
-  return s.getPages();
+  return s.getPages().filter(p => !isDraft(p));
 }
 
 export async function getPage(slugs?: string[]) {
@@ -254,10 +274,15 @@ export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: stri
     order: d.order as number | undefined,
     icon: d.icon as string | undefined,
     lastModified: d.lastModified as string | undefined,
+    draft: d.draft as boolean | undefined,
     _readingTime: d._readingTime as number | undefined,
   };
 }
 
+export function isDraft(page: { data: unknown }): boolean {
+  return (page.data as Record<string, unknown>).draft === true;
+}
+
 export function getRelativePath(page: { data: unknown }): string {
   return ((page.data as Record<string, unknown>)._relativePath as string) ?? '';
 }
@@ -266,6 +291,10 @@ export function getOriginalPath(page: { data: unknown }): string {
   return ((page.data as Record<string, unknown>)._originalPath as string) ?? '';
 }
 
+export function getPageImages(page: { data: unknown }): string[] {
+  return ((page.data as Record<string, unknown>)._images as string[]) ?? [];
+}
+
 export async function getPageSearchContent(page: { data: unknown }): Promise<{ headings: string; body: string }> {
   const originalPath = getOriginalPath(page);
   if (!originalPath) return { headings: '', body: '' };

package/src/pages/DocsLayout.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { useLocation } from 'react-router';
+import { PrefetchProvider } from '@/components/ui/PrefetchProvider';
 import { usePageContext } from '@/lib/page-context';
 import { getActiveContentDir } from '@/lib/navigation';
 import {
@@ -27,13 +28,15 @@ export function DocsLayout({ children, hideSidebar }: DocsLayoutProps) {
   );
 
   return (
-    <Layout
-      config={config}
-      tree={scopedTree}
-      hideSidebar={hideSidebar}
-      classNames={{ layout: className }}
-    >
-      {children}
-    </Layout>
+    <PrefetchProvider>
+      <Layout
+        config={config}
+        tree={scopedTree}
+        hideSidebar={hideSidebar}
+        classNames={{ layout: className }}
+      >
+        {children}
+      </Layout>
+    </PrefetchProvider>
   );
 }

package/src/server/App.module.css

@@ -0,0 +1,4 @@
+.fallback {
+  padding: var(--rs-space-8);
+  width: 80%;
+}

package/src/server/App.tsx

@@ -1,17 +1,20 @@
 import '@raystack/apsara/normalize.css';
 import '@raystack/apsara/style.css';
-import { ThemeProvider } from '@raystack/apsara';
+import { ThemeProvider, Skeleton, Flex } from '@raystack/apsara';
+import { lazy, Suspense } from 'react';
 import { Navigate, useLocation } from 'react-router';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
-import { ApiLayout } from '@/pages/ApiLayout';
-import { ApiPage } from '@/pages/ApiPage';
-import { DocsLayout } from '@/pages/DocsLayout';
-import { DocsPage } from '@/pages/DocsPage';
-import { LandingPage } from '@/pages/LandingPage';
 import type { ChronicleConfig } from '@/types';
 import { getThemeConfig } from '@/themes/registry';
+import styles from './App.module.css';
+
+const ApiLayout = lazy(() => import('@/pages/ApiLayout').then(m => ({ default: m.ApiLayout })));
+const ApiPage = lazy(() => import('@/pages/ApiPage').then(m => ({ default: m.ApiPage })));
+const DocsLayout = lazy(() => import('@/pages/DocsLayout').then(m => ({ default: m.DocsLayout })));
+const DocsPage = lazy(() => import('@/pages/DocsPage').then(m => ({ default: m.DocsPage })));
+const LandingPage = lazy(() => import('@/pages/LandingPage').then(m => ({ default: m.LandingPage })));
 
 export function App() {
   const { pathname } = useLocation();
@@ -35,19 +38,33 @@ export function App() {
       forcedTheme={themeConfig.forcedTheme}
     >
       <RootHead config={config} />
-      {isApi ? (
-        <ApiLayout>
-          <ApiPage slug={apiSlug} />
-        </ApiLayout>
-      ) : (
-        <DocsLayout hideSidebar={isLanding}>
-          {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
-        </DocsLayout>
-      )}
+      <Suspense fallback={<PageFallback />}>
+        {isApi ? (
+          <ApiLayout>
+            <ApiPage slug={apiSlug} />
+          </ApiLayout>
+        ) : (
+          <DocsLayout hideSidebar={isLanding}>
+            {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
+          </DocsLayout>
+        )}
+      </Suspense>
     </ThemeProvider>
   );
 }
 
+function PageFallback() {
+  return (
+    <Flex direction="column" gap={4} className={styles.fallback}>
+      <Skeleton width="40%" height="var(--rs-line-height-t2)" />
+      <Skeleton width="60%" height="var(--rs-line-height-regular)" />
+      {[...new Array(12)].map((_, i) => (
+        <Skeleton key={i} width="100%" height="var(--rs-line-height-regular)" />
+      ))}
+    </Flex>
+  );
+}
+
 function RootHead({ config }: { config: ChronicleConfig }) {
   return (
     <Head

package/src/server/api/page.ts

@@ -1,12 +1,12 @@
 import { defineHandler, HTTPError } from 'nitro';
-import { getPage, getPageNav, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { getPage, getPageNav, extractFrontmatter, getRelativePath, getOriginalPath, getPageImages, isDraft } from '@/lib/source';
 
 export default defineHandler(async event => {
   const slugParam = event.url.searchParams.get('slug') ?? '';
   const slug = slugParam ? slugParam.split(',').filter(Boolean) : [];
   const page = await getPage(slug);
 
-  if (!page) {
+  if (!page || isDraft(page)) {
     throw new HTTPError({ status: 404, message: 'Page not found' });
   }
 
@@ -16,6 +16,7 @@ export default defineHandler(async event => {
     frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
     relativePath: getRelativePath(page),
     originalPath: getOriginalPath(page),
+    images: getPageImages(page),
     prev: nav.prev,
     next: nav.next,
   });

package/src/server/api/search.ts

@@ -14,6 +14,7 @@ interface SearchDocument {
   headings: string;
   body: string;
   type: 'page' | 'api';
+  section: string;
 }
 
 import fs from 'node:fs/promises';
@@ -61,7 +62,8 @@ async function buildIndex(ctx: VersionContext, key: string) {
     headings TEXT NOT NULL,
     body TEXT NOT NULL,
     type TEXT NOT NULL,
-    version TEXT NOT NULL
+    version TEXT NOT NULL,
+    section TEXT NOT NULL DEFAULT ''
   )`);
 
   await db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
@@ -74,8 +76,8 @@ async function buildIndex(ctx: VersionContext, key: string) {
 
   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_docs (id, url, title, headings, body, type, version, section)
+      VALUES (${doc.id}, ${doc.url}, ${doc.title}, ${doc.headings}, ${doc.body}, ${doc.type}, ${key}, ${doc.section})`;
   }
 
   await db.sql`INSERT INTO search_fts (rowid, title, headings, body)
@@ -86,11 +88,15 @@ async function buildIndex(ctx: VersionContext, key: string) {
 
 async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   const docs: SearchDocument[] = [];
+  const config = loadConfig();
+  const contentEntries = config.content ?? [];
 
   const pages = await getPagesForVersion(ctx);
   for (const p of pages) {
     const fm = extractFrontmatter(p);
     const { headings, body } = await getPageSearchContent(p);
+    const dir = p.url.replace(/^\//, '').split('/')[0];
+    const entry = contentEntries.find(c => c.dir === dir);
     docs.push({
       id: p.url,
       url: p.url,
@@ -98,10 +104,10 @@ async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
       headings,
       body: [fm.description ?? '', body].join(' '),
       type: 'page',
+      section: entry?.label ?? dir ?? '',
     });
   }
 
-  const config = loadConfig();
   const apiConfigs = getApiConfigsForVersion(config, ctx.dir);
   if (apiConfigs.length) {
     const specs = await loadApiSpecs(apiConfigs);
@@ -122,6 +128,7 @@ async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
             headings: op.summary ?? opId,
             body: [op.description ?? '', pathStr, method.toUpperCase()].join(' '),
             type: 'api',
+            section: spec.name,
           });
         }
       }
@@ -183,7 +190,7 @@ export default defineHandler(async event => {
   const key = versionKey(ctx);
 
   if (!query) {
-    const result = await db.sql`SELECT id, url, title, type FROM search_docs
+    const result = await db.sql`SELECT id, url, title, type, section FROM search_docs
       WHERE version = ${key} AND type = 'page'
       LIMIT 8`;
     return Response.json((result.rows ?? []).map(r => ({
@@ -191,11 +198,12 @@ export default defineHandler(async event => {
       url: r.url,
       type: r.type,
       content: r.title,
+      section: r.section || null,
     })));
   }
 
   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,
+  const result = await db.sql`SELECT s.id, s.url, s.title, s.headings, s.body, s.type, s.section,
       bm25(search_fts, 10.0, 5.0, 1.0) AS score
     FROM search_fts f
     JOIN search_docs s ON s.rowid = f.rowid
@@ -214,6 +222,8 @@ export default defineHandler(async event => {
       content: r.title,
       match,
       snippet,
+      section: r.section || null,
     };
   }));
 });
+

package/src/server/entry-client.tsx

@@ -3,9 +3,11 @@ import React from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router';
 import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { QueryClientProvider } from '@tanstack/react-query';
 import { mdxComponents } from '@/components/mdx';
 import { getApiConfigsForVersion } from '@/lib/config';
 import { PageProvider } from '@/lib/page-context';
+import { queryClient } from '@/lib/preload';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
 import { resolveVersionFromUrl, type VersionContext } from '@/lib/version-source';
 import type { ChronicleConfig, Frontmatter, PageNavLink, Root, TableOfContents } from '@/types';
@@ -93,20 +95,22 @@ async function hydrate() {
 
     hydrateRoot(
       document.getElementById('root') as HTMLElement,
-      <BrowserRouter>
-        <ReactRouterProvider>
-          <PageProvider
-            initialConfig={config}
-            initialTree={tree}
-            initialPage={page}
-            initialApiSpecs={apiSpecs}
-            initialVersion={version}
-            loadMdx={loadMdxModule}
-          >
-            <App />
-          </PageProvider>
-        </ReactRouterProvider>
-      </BrowserRouter>
+      <QueryClientProvider client={queryClient}>
+        <BrowserRouter>
+          <ReactRouterProvider>
+            <PageProvider
+              initialConfig={config}
+              initialTree={tree}
+              initialPage={page}
+              initialApiSpecs={apiSpecs}
+              initialVersion={version}
+              loadMdx={loadMdxModule}
+            >
+              <App />
+            </PageProvider>
+          </ReactRouterProvider>
+        </BrowserRouter>
+      </QueryClientProvider>
     );
   } catch (err) {
     console.error('Hydration failed:', err);

package/src/server/entry-server.tsx

@@ -9,7 +9,7 @@ import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 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 { getPageTree, getPage, getPageNav, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath, getPageImages, isDraft } from '@/lib/source';
 import { getFirstApiUrl } from '@/lib/api-routes';
 import { StatusCodes } from 'http-status-codes';
 import { resolveDocsRedirect } from '@/lib/tree-utils';
@@ -44,10 +44,12 @@ export default {
       : [];
     const apiSpecs = apiConfigs.length ? await loadApiSpecs(apiConfigs) : [];
 
-    const [tree, page] = await Promise.all([
+    const [tree, rawPage] = await Promise.all([
       getPageTree(),
       route.type === RouteType.DocsPage ? getPage(route.slug) : Promise.resolve(null),
     ]);
+    const page = rawPage && isDraft(rawPage) ? null : rawPage;
+
     // SSR redirects for index pages
     if (route.type === RouteType.ApiIndex) {
       const firstUrl = getFirstApiUrl(apiSpecs);
@@ -77,6 +79,7 @@ export default {
     const relativePath = page ? getRelativePath(page) : null;
     const originalPath = page ? getOriginalPath(page) : null;
     const mdxModule = (originalPath || relativePath) ? await loadPageModule(originalPath || relativePath!) : null;
+    const pageImages = page ? getPageImages(page) : [];
 
     const pageData = page
       ? {
@@ -123,6 +126,9 @@ export default {
           {assets.js.map((attr: { href: string }) => (
             <link key={attr.href} rel="modulepreload" {...attr} />
           ))}
+          {pageImages.map((src: string) => (
+            <link key={src} rel="preload" as="image" href={src} />
+          ))}
           <script type="module" src={assets.entry} />
           <script dangerouslySetInnerHTML={{ __html: `window.__PAGE_DATA__ = ${safeJson}` }} />
         </head>

package/src/server/error.ts

@@ -0,0 +1,11 @@
+import { defineErrorHandler, HTTPError } from 'nitro';
+
+export default defineErrorHandler((error, _event) => {
+  const status = HTTPError.isError(error) ? error.status : 500;
+  const message = error.message || 'Internal Server Error';
+
+  return new Response(JSON.stringify({ error: true, status, message }), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+});

package/src/server/vite-config.ts

@@ -72,7 +72,7 @@ export async function createViteConfig(
         default: defineFumadocsConfig({
           mdxOptions: {
             remarkImageOptions: false,
-            valueToExport: ['readingTime'],
+            valueToExport: ['readingTime', 'images'],
             remarkPlugins: [
               remarkDirective,
               [remarkDirectiveAdmonition, {
@@ -145,6 +145,7 @@ export async function createViteConfig(
     },
     nitro: {
       logLevel: 2,
+      errorHandler: path.resolve(packageRoot, 'src/server/error.ts'),
       publicAssets: [{ dir: path.resolve(projectRoot, 'public') }],
       output: {
         dir: resolveOutputDir(projectRoot, preset),

package/src/themes/default/Layout.tsx

@@ -9,12 +9,13 @@ import {
 import { Flex, IconButton, Button, Sidebar } from '@raystack/apsara';
 import { PlayIcon } from '@radix-ui/react-icons';
 import { cx } from 'class-variance-authority';
-import { useState, useEffect, useMemo, useRef } from 'react';
+import { useState, useEffect, useMemo, useRef, lazy, Suspense } from 'react';
 import { Link as RouterLink, useLocation, useNavigate } from 'react-router';
 import type { OpenAPIV3 } from 'openapi-types';
 import { MethodBadge } from '@/components/api/method-badge';
 import { useApiOperation } from '@/lib/use-api-operation';
-import { PlaygroundDialog } from '@/components/api/playground-dialog';
+
+const PlaygroundDialog = lazy(() => import('@/components/api/playground-dialog').then(m => ({ default: m.PlaygroundDialog })));
 import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
 import { Search } from '@/components/ui/search';
 import { Breadcrumbs } from '@/components/ui/breadcrumbs';
@@ -137,14 +138,14 @@ export function Layout({
                         <DocumentTextIcon width={16} height={16} />
                       )}
                       classNames={{ root: styles.topLinkItem, text: styles.topLinkText }}
-                      render={<RouterLink to={entry.href} />}
+                      render={<RouterLink to={entry.href} data-no-prefetch />}
                     >
                       {entry.label}
                     </Sidebar.Item>
                   ))}
                   {apiEntries.map(api => (
                     <Sidebar.Item
-                      key={api.basePath}
+                      key={`${api.basePath}-${api.name}`}
                       href={api.basePath}
                       active={isApiBase(api.basePath)}
                       leadingIcon={renderConfigIcon(
@@ -153,7 +154,7 @@ export function Layout({
                         <CodeBracketSquareIcon width={16} height={16} />
                       )}
                       classNames={{ root: styles.topLinkItem, text: styles.topLinkText }}
-                      render={<RouterLink to={api.basePath} />}
+                      render={<RouterLink to={api.basePath} data-no-prefetch />}
                     >
                       {api.name} API
                     </Sidebar.Item>
@@ -371,18 +372,22 @@ function TestRequestButton() {
       >
         Test request
       </Button>
-      <PlaygroundDialog
-        key={`${match.spec.name}-${match.path}-${match.method}`}
-        open={open}
-        onOpenChange={setOpen}
-        method={match.method}
-        path={match.path}
-        operation={match.operation}
-        serverUrl={match.spec.server.url}
-        specName={match.spec.name}
-        auth={match.spec.auth}
-        document={match.spec.document}
-      />
+      {open && (
+        <Suspense fallback={null}>
+          <PlaygroundDialog
+            key={`${match.spec.name}-${match.path}-${match.method}`}
+            open={open}
+            onOpenChange={setOpen}
+            method={match.method}
+            path={match.path}
+            operation={match.operation}
+            serverUrl={match.spec.server.url}
+            specName={match.spec.name}
+            auth={match.spec.auth}
+            document={match.spec.document}
+          />
+        </Suspense>
+      )}
     </>
   );
 }

package/src/themes/default/Page.tsx

@@ -1,9 +1,11 @@
 'use client';
 
 import { Flex, Headline } from '@raystack/apsara';
+import { lazy, Suspense } from 'react';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
-import { Toc } from './Toc';
+
+const Toc = lazy(() => import('./Toc').then(m => ({ default: m.Toc })));
 
 export function Page({ page }: ThemePageProps) {
   return (
@@ -16,7 +18,9 @@ export function Page({ page }: ThemePageProps) {
         )}
         <div className={styles.content}>{page.content}</div>
       </article>
-      <Toc items={page.toc} />
+      <Suspense fallback={null}>
+        <Toc items={page.toc} />
+      </Suspense>
     </Flex>
   );
 }

package/src/types/content.ts

@@ -10,6 +10,7 @@ export interface Frontmatter {
   order?: number
   icon?: string
   lastModified?: string
+  draft?: boolean
   _readingTime?: number
 }