@raystack/chronicle 0.10.4 → 0.11.1

package/dist/cli/index.js

@@ -55,6 +55,19 @@ var init_mdx_utils = __esm(() => {
   };
 });
 
+// src/lib/image-utils.ts
+function isLocalImage(url) {
+  return url.startsWith("/_content/");
+}
+function isSvg(url) {
+  return url.split("?")[0].endsWith(".svg");
+}
+function buildOptimizedUrl(url, width, quality = DEFAULT_QUALITY) {
+  return `/api/image?url=${encodeURIComponent(url)}&w=${width}&q=${quality}`;
+}
+var DEFAULT_WIDTH = 1024, DEFAULT_QUALITY = 75;
+var init_image_utils = () => {};
+
 // src/lib/remark-resolve-images.ts
 import path4 from "node:path";
 import { visit } from "unist-util-visit";
@@ -71,7 +84,13 @@ function resolveUrl(src, dir) {
     return `/_content${src}`;
   return `/_content/${path4.posix.normalize(path4.posix.join(dir, src))}`;
 }
-var remarkResolveImages = () => {
+function optimizeUrl(url, optimize) {
+  if (optimize && isLocalImage(url) && !isSvg(url))
+    return buildOptimizedUrl(url, DEFAULT_WIDTH);
+  return url;
+}
+var remarkResolveImages = (options) => {
+  const optimize = options?.optimize ?? true;
   return (tree, file) => {
     const filePath = file.path;
     if (!filePath)
@@ -94,12 +113,13 @@ var remarkResolveImages = () => {
         return;
       node.url = resolveUrl(node.url, dir);
       collect(node.url);
+      node.url = optimizeUrl(node.url, optimize);
     });
     visit(tree, "html", (node) => {
       node.value = node.value.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (_, before, src, after) => {
         const resolved = resolveUrl(src, dir);
         collect(resolved);
-        return `${before}${resolved}${after}`;
+        return `${before}${optimizeUrl(resolved, optimize)}${after}`;
       });
     });
     visit(tree, (node) => {
@@ -113,6 +133,7 @@ var remarkResolveImages = () => {
         return;
       srcAttr.value = resolveUrl(srcAttr.value, dir);
       collect(srcAttr.value);
+      srcAttr.value = optimizeUrl(srcAttr.value, optimize);
     });
     visit(tree, "element", (node) => {
       if (node.tagName !== "img")
@@ -122,12 +143,14 @@ var remarkResolveImages = () => {
         return;
       node.properties.src = resolveUrl(src, dir);
       collect(node.properties.src);
+      node.properties.src = optimizeUrl(node.properties.src, optimize);
     });
     file.data.images = images;
   };
 }, remark_resolve_images_default;
 var init_remark_resolve_images = __esm(() => {
   init_mdx_utils();
+  init_image_utils();
   remark_resolve_images_default = remarkResolveImages;
 });
 
@@ -350,6 +373,9 @@ function getDatabaseConnector(preset) {
       return { connector: "sqlite", options: { name: "chronicle-search" } };
   }
 }
+function isStaticPreset(preset) {
+  return !!preset && STATIC_PRESETS.has(preset);
+}
 function resolveOutputDir(projectRoot, preset) {
   if (preset === "vercel" || preset === "vercel-static")
     return path6.resolve(projectRoot, ".vercel/output");
@@ -380,7 +406,8 @@ async function createViteConfig(options) {
     plugins: [
       nitro({
         serverDir: path6.resolve(packageRoot, "src/server"),
-        ...preset && { preset }
+        ...preset && { preset },
+        ignore: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"]
       }),
       mdx({
         default: defineFumadocsConfig({
@@ -408,7 +435,7 @@ async function createViteConfig(options) {
               }],
               remark_unused_directives_default,
               remark_resolve_links_default,
-              remark_resolve_images_default,
+              [remark_resolve_images_default, { optimize: !isStaticPreset(preset) }],
               remarkMdxMermaid,
               readingTime
             ]
@@ -446,7 +473,8 @@ async function createViteConfig(options) {
       }
     },
     ssr: {
-      noExternal: ["@raystack/apsara", "dayjs", "fumadocs-core"]
+      noExternal: ["@raystack/apsara", "dayjs", "fumadocs-core"],
+      external: ["analytics", "use-analytics", "@analytics/google-analytics"]
     },
     environments: {
       client: {
@@ -464,6 +492,13 @@ async function createViteConfig(options) {
       output: {
         dir: resolveOutputDir(projectRoot, preset)
       },
+      externals: ["sharp"],
+      storage: {
+        "image-cache": {
+          driver: "fs",
+          base: path6.resolve(projectRoot, ".cache/images")
+        }
+      },
       experimental: {
         database: true
       },
@@ -473,11 +508,13 @@ async function createViteConfig(options) {
     }
   };
 }
+var STATIC_PRESETS;
 var init_vite_config = __esm(() => {
   init_remark_resolve_images();
   init_remark_resolve_links();
   init_remark_reading_time();
   init_remark_unused_directives();
+  STATIC_PRESETS = new Set(["static", "vercel-static", "cloudflare-pages", "github-pages"]);
 });
 
 // src/cli/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,6 +36,7 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
+    "@analytics/google-analytics": "^1.1.0",
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/state": "^6.5.4",
     "@codemirror/theme-one-dark": "^6.1.3",
@@ -51,12 +52,14 @@
     "@shikijs/rehype": "^4.0.2",
     "@tanstack/react-query": "5.100.10",
     "@vitejs/plugin-react": "^6.0.1",
+    "analytics": "^0.8.19",
     "chalk": "^5.6.2",
     "class-variance-authority": "^0.7.1",
     "codemirror": "^6.0.2",
     "commander": "^14.0.2",
     "fumadocs-core": "16.8.1",
     "fumadocs-mdx": "14.3.1",
+    "github-slugger": "^2.0.0",
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "h3": "^2.0.1-rc.16",
@@ -74,10 +77,12 @@
     "remark-mdx-frontmatter": "^5.2.0",
     "remark-parse": "^11.0.0",
     "satori": "^0.25.0",
+    "sharp": "^0.34.5",
     "slugify": "^1.6.6",
     "std-env": "^4.1.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
+    "use-analytics": "^1.1.0",
     "vite": "8.0.3",
     "yaml": "^2.8.2",
     "zod": "^4.3.6"

package/src/components/analytics/AnalyticsProvider.tsx

@@ -0,0 +1,64 @@
+import { useEffect, useState } from 'react'
+import { useLocation } from 'react-router'
+import type { ReactNode } from 'react'
+import type { AnalyticsConfig } from '@/types'
+import type { AnalyticsInstance } from 'analytics'
+
+function PageViewTracker({ analytics }: { analytics: AnalyticsInstance }) {
+  const { pathname } = useLocation()
+
+  useEffect(() => {
+    try { analytics.page() } catch { /* noop */ }
+  }, [pathname, analytics])
+
+  return null
+}
+
+export function AnalyticsProvider({
+  config,
+  appName,
+  children,
+}: {
+  config: AnalyticsConfig
+  appName: string
+  children: ReactNode
+}) {
+  const [analytics, setAnalytics] = useState<AnalyticsInstance | null>(null)
+
+  useEffect(() => {
+    if (!config.enabled) {
+      setAnalytics(null)
+      return
+    }
+
+    let cancelled = false
+
+    const init = async () => {
+      try {
+        const plugins: unknown[] = []
+        if (config.googleAnalytics?.measurementId) {
+          const { default: googleAnalytics } = await import('@analytics/google-analytics')
+          plugins.push(
+            googleAnalytics({
+              measurementIds: [config.googleAnalytics.measurementId],
+            })
+          )
+        }
+        const { default: Analytics } = await import('analytics')
+        if (!cancelled) setAnalytics(Analytics({ app: appName, plugins }))
+      } catch {
+        if (!cancelled) setAnalytics(null)
+      }
+    }
+
+    void init()
+    return () => { cancelled = true }
+  }, [config.enabled, config.googleAnalytics?.measurementId, appName])
+
+  return (
+    <>
+      {analytics && <PageViewTracker analytics={analytics} />}
+      {children}
+    </>
+  )
+}

package/src/components/mdx/image.tsx

@@ -1,9 +1,13 @@
 import type { ComponentProps } from 'react';
+import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from '@/lib/image-utils';
 
-type ImageProps = ComponentProps<'img'>;
+type MDXImageProps = ComponentProps<'img'>;
 
-export function Image({ src, alt, ...props }: ImageProps) {
+export function MDXImage({ src, alt, ...props }: MDXImageProps) {
   if (!src) return null;
 
-  return <img src={src} alt={alt ?? ''} loading='lazy' {...props} />;
+  const optimize = isLocalImage(src) && !isSvg(src);
+  const imgSrc = optimize ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
+
+  return <img src={imgSrc} alt={alt ?? ''} loading='lazy' decoding='async' {...props} />;
 }

package/src/components/mdx/index.tsx

@@ -1,5 +1,5 @@
 import type { MDXComponents } from 'mdx/types'
-import { Image } from './image'
+import { MDXImage } from './image'
 import { Link } from './link'
 import { MdxTable, MdxThead, MdxTbody, MdxTr, MdxTh, MdxTd } from './table'
 import { MdxPre, MdxCode } from './code'
@@ -25,7 +25,7 @@ MdxTabs.Content = Tabs.Content
 
 export const mdxComponents: MDXComponents = {
   p: MdxParagraph,
-  img: Image,
+  img: MDXImage,
   a: Link,
   table: MdxTable,
   thead: MdxThead,
@@ -45,5 +45,5 @@ export const mdxComponents: MDXComponents = {
   Mermaid,
 }
 
-export { Image } from './image'
+export { MDXImage } from './image'
 export { Link } from './link'

package/src/components/ui/search.tsx

@@ -4,8 +4,9 @@ import {
   MagnifyingGlassIcon
 } from '@heroicons/react/24/outline';
 import { Badge, Command, IconButton, Text } from '@raystack/apsara';
+import { keepPreviousData, useQuery } from '@tanstack/react-query';
 import { debounce } from 'lodash-es';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState, type ChangeEvent } from 'react';
 import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
 import { usePageContext } from '@/lib/page-context';
@@ -36,57 +37,40 @@ function buildSearchUrl(query: string, tag?: string): string {
 export function Search({ classNames }: SearchProps) {
   const [open, setOpen] = useState(false);
   const [search, setSearch] = useState('');
-  const [results, setResults] = useState<SearchResult[]>([]);
-  const [suggestions, setSuggestions] = useState<SearchResult[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
+  const [debouncedSearch, setDebouncedSearch] = useState('');
   const navigate = useNavigate();
   const { version } = usePageContext();
   const tag = version.dir ?? undefined;
-  const abortRef = useRef<AbortController | null>(null);
 
-  const fetchResults = useCallback(async (query: string, signal?: AbortSignal) => {
-    setIsLoading(true);
-    try {
-      const res = await fetch(buildSearchUrl(query, tag), { signal });
-      if (!res.ok || signal?.aborted) return;
-      const data: SearchResult[] = await res.json();
-      if (signal?.aborted) return;
-      if (query) {
-        setResults(data);
-      } else {
-        setSuggestions(data);
-      }
-    } catch (err) {
-      if (err instanceof DOMException && err.name === 'AbortError') return;
-      console.error('Search fetch failed:', err);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [tag]);
-
-  const debouncedSearch = useMemo(
-    () => debounce((query: string) => {
-      abortRef.current?.abort();
-      const controller = new AbortController();
-      abortRef.current = controller;
-      fetchResults(query, controller.signal);
-    }, 150),
-    [fetchResults]
+  const updateDebouncedSearch = useMemo(
+    () => debounce((value: string) => setDebouncedSearch(value), 150),
+    []
   );
 
+  const onSearchChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
+    const value = e.target.value;
+    setSearch(value);
+    updateDebouncedSearch(value);
+  }, [updateDebouncedSearch]);
+
   useEffect(() => {
     if (!open) {
       setSearch('');
-      setResults([]);
-      return;
+      setDebouncedSearch('');
+      updateDebouncedSearch.cancel();
     }
-    if (!search) {
-      fetchResults('');
-      return;
-    }
-    debouncedSearch(search);
-    return () => debouncedSearch.cancel();
-  }, [open, search, fetchResults, debouncedSearch]);
+  }, [open, updateDebouncedSearch]);
+
+  const { data = [], isLoading } = useQuery<SearchResult[]>({
+    queryKey: ['search', debouncedSearch, tag],
+    queryFn: async ({ signal }) => {
+      const res = await fetch(buildSearchUrl(debouncedSearch, tag), { signal });
+      if (!res.ok) throw new Error(String(res.status));
+      return res.json();
+    },
+    enabled: open,
+    placeholderData: keepPreviousData,
+  });
 
   const onSelect = useCallback(
     (url: string) => {
@@ -108,7 +92,7 @@ export function Search({ classNames }: SearchProps) {
     return () => document.removeEventListener('keydown', down);
   }, []);
 
-  const displayResults = deduplicateByUrl(search ? results : suggestions);
+  const displayResults = deduplicateByUrl(data);
 
   return (
     <>
@@ -129,7 +113,7 @@ export function Search({ classNames }: SearchProps) {
               placeholder='Search'
               leadingIcon={<MagnifyingGlassIcon width={16} height={16} />}
               value={search}
-              onChange={(e) => setSearch(e.target.value)}
+              onChange={onSearchChange}
               className={styles.input}
             />
 

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

@@ -0,0 +1,71 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  isLocalImage,
+  isSvg,
+  buildOptimizedUrl,
+  ALLOWED_WIDTHS,
+  DEFAULT_WIDTH,
+  DEFAULT_QUALITY,
+} from './image-utils';
+
+describe('isLocalImage', () => {
+  test('returns true for /_content/ URLs', () => {
+    expect(isLocalImage('/_content/docs/photo.png')).toBe(true);
+  });
+
+  test('returns false for external URLs', () => {
+    expect(isLocalImage('https://example.com/img.png')).toBe(false);
+  });
+
+  test('returns false for relative URLs', () => {
+    expect(isLocalImage('/images/logo.png')).toBe(false);
+  });
+});
+
+describe('isSvg', () => {
+  test('returns true for .svg files', () => {
+    expect(isSvg('/_content/logo.svg')).toBe(true);
+  });
+
+  test('returns true for .svg with query string', () => {
+    expect(isSvg('/_content/logo.svg?v=1')).toBe(true);
+  });
+
+  test('returns false for .png files', () => {
+    expect(isSvg('/_content/photo.png')).toBe(false);
+  });
+});
+
+describe('buildOptimizedUrl', () => {
+  test('builds URL with width and default quality', () => {
+    const url = buildOptimizedUrl('/_content/img.png', 640);
+    expect(url).toBe(`/api/image?url=%2F_content%2Fimg.png&w=640&q=${DEFAULT_QUALITY}`);
+  });
+
+  test('builds URL with custom quality', () => {
+    const url = buildOptimizedUrl('/_content/img.png', 320, 50);
+    expect(url).toBe('/api/image?url=%2F_content%2Fimg.png&w=320&q=50');
+  });
+
+  test('encodes special characters in URL', () => {
+    const url = buildOptimizedUrl('/_content/my image (1).png', 640);
+    expect(url).toContain('my%20image%20(1).png');
+  });
+});
+
+describe('constants', () => {
+  test('ALLOWED_WIDTHS is sorted ascending', () => {
+    for (let i = 1; i < ALLOWED_WIDTHS.length; i++) {
+      expect(ALLOWED_WIDTHS[i]).toBeGreaterThan(ALLOWED_WIDTHS[i - 1]);
+    }
+  });
+
+  test('DEFAULT_WIDTH is in ALLOWED_WIDTHS', () => {
+    expect(ALLOWED_WIDTHS).toContain(DEFAULT_WIDTH);
+  });
+
+  test('DEFAULT_QUALITY is between 1 and 100', () => {
+    expect(DEFAULT_QUALITY).toBeGreaterThanOrEqual(1);
+    expect(DEFAULT_QUALITY).toBeLessThanOrEqual(100);
+  });
+});

package/src/lib/image-utils.ts

@@ -0,0 +1,18 @@
+const ALLOWED_WIDTHS = [320, 640, 768, 1024, 1280, 1536, 1920];
+const ALLOWED_QUALITIES = [60, 75, 90, 100];
+const DEFAULT_WIDTH = 1024;
+const DEFAULT_QUALITY = 75;
+
+export function isLocalImage(url: string): boolean {
+  return url.startsWith('/_content/');
+}
+
+export function isSvg(url: string): boolean {
+  return url.split('?')[0].endsWith('.svg');
+}
+
+export function buildOptimizedUrl(url: string, width: number, quality = DEFAULT_QUALITY): string {
+  return `/api/image?url=${encodeURIComponent(url)}&w=${width}&q=${quality}`;
+}
+
+export { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_WIDTH, DEFAULT_QUALITY };

package/src/lib/page-context.tsx

@@ -14,6 +14,7 @@ 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';
+import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from '@/lib/image-utils';
 
 export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
@@ -136,7 +137,7 @@ export function PageProvider({
       if (data.images?.length) {
         for (const src of data.images) {
           const img = new Image();
-          img.src = src;
+          img.src = isLocalImage(src) && !isSvg(src) ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
         }
       }
       const { content, toc } = await loadMdx(data.originalPath || data.relativePath);

package/src/lib/preload.ts

@@ -40,3 +40,14 @@ export function prefetchPageData(pathname: string) {
     queryFn: () => fetchPageDataByPathname(pathname),
   });
 }
+
+export function prefetchSearchSuggestions() {
+  queryClient.prefetchQuery({
+    queryKey: ['search', '', undefined],
+    queryFn: async () => {
+      const res = await fetch('/api/search');
+      if (!res.ok) throw new Error(String(res.status));
+      return res.json();
+    },
+  });
+}

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

@@ -5,6 +5,7 @@ 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'
+import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from './image-utils'
 
 function resolveUrl(src: string, dir: string): string {
   if (/^[a-z][a-z0-9+\-.]*:/i.test(src)) return src
@@ -16,7 +17,17 @@ function resolveUrl(src: string, dir: string): string {
   return `/_content/${path.posix.normalize(path.posix.join(dir, src))}`
 }
 
-const remarkResolveImages: Plugin = () => {
+interface RemarkResolveImagesOptions {
+  optimize?: boolean
+}
+
+function optimizeUrl(url: string, optimize: boolean): string {
+  if (optimize && isLocalImage(url) && !isSvg(url)) return buildOptimizedUrl(url, DEFAULT_WIDTH)
+  return url
+}
+
+const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) => {
+  const optimize = options?.optimize ?? true
   return (tree, file) => {
     const filePath = file.path
     if (!filePath) return
@@ -40,6 +51,7 @@ const remarkResolveImages: Plugin = () => {
       if (!node.url) return
       node.url = resolveUrl(node.url, dir)
       collect(node.url)
+      node.url = optimizeUrl(node.url, optimize)
     })
 
     visit(tree, 'html', (node: Html) => {
@@ -48,7 +60,7 @@ const remarkResolveImages: Plugin = () => {
         (_, before, src, after) => {
           const resolved = resolveUrl(src, dir)
           collect(resolved)
-          return `${before}${resolved}${after}`
+          return `${before}${optimizeUrl(resolved, optimize)}${after}`
         }
       )
     })
@@ -61,6 +73,7 @@ const remarkResolveImages: Plugin = () => {
       if (!srcAttr?.value || typeof srcAttr.value !== 'string') return
       srcAttr.value = resolveUrl(srcAttr.value, dir)
       collect(srcAttr.value)
+      srcAttr.value = optimizeUrl(srcAttr.value, optimize)
     })
 
     visit(tree, 'element', (node: Element) => {
@@ -69,6 +82,7 @@ const remarkResolveImages: Plugin = () => {
       if (typeof src !== 'string') return
       node.properties.src = resolveUrl(src, dir)
       collect(node.properties.src as string)
+      node.properties.src = optimizeUrl(node.properties.src as string, optimize)
     })
 
     file.data.images = images

package/src/server/App.tsx

@@ -3,6 +3,7 @@ import '@raystack/apsara/style.css';
 import { ThemeProvider, Skeleton, Flex } from '@raystack/apsara';
 import { lazy, Suspense } from 'react';
 import { Navigate, useLocation } from 'react-router';
+import { AnalyticsProvider } from '@/components/analytics/AnalyticsProvider';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
@@ -37,18 +38,20 @@ export function App() {
       enableSystem={themeConfig.enableSystem}
       forcedTheme={themeConfig.forcedTheme}
     >
-      <RootHead config={config} />
-      <Suspense fallback={<PageFallback />}>
-        {isApi ? (
-          <ApiLayout>
-            <ApiPage slug={apiSlug} />
-          </ApiLayout>
-        ) : (
-          <DocsLayout hideSidebar={isLanding}>
-            {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
-          </DocsLayout>
-        )}
-      </Suspense>
+      <AnalyticsProvider config={config.analytics ?? { enabled: false }} appName={config.site.title}>
+        <RootHead config={config} />
+        <Suspense fallback={<PageFallback />}>
+          {isApi ? (
+            <ApiLayout>
+              <ApiPage slug={apiSlug} />
+            </ApiLayout>
+          ) : (
+            <DocsLayout hideSidebar={isLanding}>
+              {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
+            </DocsLayout>
+          )}
+        </Suspense>
+      </AnalyticsProvider>
     </ThemeProvider>
   );
 }

package/src/server/api/image.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'bun:test';
+import { negotiateFormat, cacheKey, MIME } from './image';
+
+describe('negotiateFormat', () => {
+  test('returns avif when Accept includes image/avif', () => {
+    expect(negotiateFormat('image/avif,image/webp,*/*')).toBe('avif');
+  });
+
+  test('returns webp when Accept includes image/webp but not avif', () => {
+    expect(negotiateFormat('image/webp,image/png,*/*')).toBe('webp');
+  });
+
+  test('returns original when Accept has neither avif nor webp', () => {
+    expect(negotiateFormat('image/png,*/*')).toBe('original');
+  });
+
+  test('returns original for null Accept header', () => {
+    expect(negotiateFormat(null)).toBe('original');
+  });
+
+  test('prefers avif over webp when both present', () => {
+    expect(negotiateFormat('image/webp,image/avif')).toBe('avif');
+  });
+});
+
+describe('cacheKey', () => {
+  test('returns deterministic key for same inputs', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 640, 75, 'webp');
+    expect(a).toBe(b);
+  });
+
+  test('returns different keys for different widths', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 1024, 75, 'webp');
+    expect(a).not.toBe(b);
+  });
+
+  test('returns different keys for different formats', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 640, 75, 'avif');
+    expect(a).not.toBe(b);
+  });
+
+  test('returns different keys for different quality', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp');
+    const b = cacheKey('/_content/img.png', 640, 50, 'webp');
+    expect(a).not.toBe(b);
+  });
+
+  test('key ends with format extension', () => {
+    expect(cacheKey('/_content/img.png', 640, 75, 'webp')).toMatch(/\.webp$/);
+    expect(cacheKey('/_content/img.png', 640, 75, 'avif')).toMatch(/\.avif$/);
+    expect(cacheKey('/_content/img.png', 640, 75, 'original')).toMatch(/\.original$/);
+  });
+});
+
+describe('MIME', () => {
+  test('maps common image extensions', () => {
+    expect(MIME['.png']).toBe('image/png');
+    expect(MIME['.jpg']).toBe('image/jpeg');
+    expect(MIME['.jpeg']).toBe('image/jpeg');
+    expect(MIME['.gif']).toBe('image/gif');
+    expect(MIME['.webp']).toBe('image/webp');
+  });
+
+  test('does not include svg (handled separately)', () => {
+    expect(MIME['.svg']).toBeUndefined();
+  });
+});

package/src/server/api/image.ts

@@ -0,0 +1,154 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { defineHandler, HTTPError } from 'nitro'
+import { useStorage } from 'nitro/storage'
+import sharp from 'sharp'
+import { StatusCodes } from 'http-status-codes'
+import { safePath } from '@/server/utils/safe-path'
+import { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_QUALITY } from '@/lib/image-utils'
+
+const STORAGE_KEY = 'image-cache'
+const MAX_CACHE_ENTRIES = 500
+
+const inflight = new Map<string, Promise<Buffer>>()
+
+export type OutputFormat = 'avif' | 'webp' | 'original'
+
+export function negotiateFormat(accept: string | null): OutputFormat {
+  if (accept?.includes('image/avif')) return 'avif'
+  if (accept?.includes('image/webp')) return 'webp'
+  return 'original'
+}
+
+export const MIME: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+}
+
+export function cacheKey(url: string, w: number, q: number, format: OutputFormat): string {
+  const hash = crypto.createHash('sha256').update(`${url}:${w}:${q}:${format}`).digest('hex').slice(0, 16)
+  return `${hash}.${format}`
+}
+
+function snapQuality(q: number): number {
+  let closest = ALLOWED_QUALITIES[0];
+  for (const aq of ALLOWED_QUALITIES) {
+    if (Math.abs(aq - q) < Math.abs(closest - q)) closest = aq;
+  }
+  return closest;
+}
+
+async function evictIfNeeded(storage: ReturnType<typeof useStorage>) {
+  const keys = await storage.getKeys()
+  if (keys.length <= MAX_CACHE_ENTRIES) return
+  const toRemove = keys.slice(0, keys.length - MAX_CACHE_ENTRIES)
+  await Promise.all(toRemove.map(k => storage.removeItem(k)))
+}
+
+export default defineHandler(async event => {
+  const storage = useStorage(STORAGE_KEY)
+
+  const url = event.url.searchParams.get('url')
+  const wParam = event.url.searchParams.get('w')
+  const qParam = event.url.searchParams.get('q')
+
+  if (!url || !wParam) {
+    throw new HTTPError({ status: StatusCodes.BAD_REQUEST, message: 'Missing url or w parameter' })
+  }
+
+  if (!url.startsWith('/_content/')) {
+    throw new HTTPError({ status: StatusCodes.BAD_REQUEST, message: 'Only local content images allowed' })
+  }
+
+  const w = Number.parseInt(wParam, 10)
+  if (!ALLOWED_WIDTHS.includes(w)) {
+    throw new HTTPError({ status: StatusCodes.BAD_REQUEST, message: `Width must be one of: ${ALLOWED_WIDTHS.join(', ')}` })
+  }
+
+  const q = snapQuality(qParam ? Number.parseInt(qParam, 10) : DEFAULT_QUALITY)
+
+  if (url.split('?')[0].endsWith('.svg')) {
+    return Response.redirect(url, StatusCodes.TEMPORARY_REDIRECT)
+  }
+
+  const contentDir = __CHRONICLE_CONTENT_DIR__
+  const relativePath = url.replace(/^\/_content\//, '')
+  const filePath = safePath(contentDir, `/${relativePath}`)
+  if (!filePath) {
+    throw new HTTPError({ status: StatusCodes.NOT_FOUND, message: 'Not Found' })
+  }
+
+  const accept = event.headers.get('accept')
+  const format = negotiateFormat(accept)
+  const ext = path.extname(filePath).toLowerCase()
+  const originalMime = MIME[ext] ?? 'application/octet-stream'
+  const contentType = format === 'original' ? originalMime : `image/${format}`
+
+  const key = cacheKey(url, w, q, format)
+
+  const cached = await storage.getItemRaw<Buffer>(key)
+  if (cached) {
+    return new Response(cached, {
+      headers: {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+        'Vary': 'Accept',
+      },
+    })
+  }
+
+  const existing = inflight.get(key)
+  if (existing) {
+    const optimized = await existing
+    return new Response(optimized, {
+      headers: {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+        'Vary': 'Accept',
+      },
+    })
+  }
+
+  const work = (async () => {
+    const source = await fs.readFile(filePath)
+    const pipeline = sharp(source).resize({ width: w, withoutEnlargement: true })
+    const optimized = format === 'avif'
+      ? await pipeline.avif({ quality: q }).toBuffer()
+      : format === 'webp'
+        ? await pipeline.webp({ quality: q }).toBuffer()
+        : await pipeline.toBuffer()
+
+    await storage.setItemRaw(key, optimized)
+    await evictIfNeeded(storage)
+    return optimized
+  })()
+
+  inflight.set(key, work)
+  try {
+    const optimized = await work
+    return new Response(optimized, {
+      headers: {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+        'Vary': 'Accept',
+      },
+    })
+  } catch {
+    const source = await fs.readFile(filePath).catch(() => null)
+    if (!source) {
+      throw new HTTPError({ status: StatusCodes.NOT_FOUND, message: 'Not Found' })
+    }
+    return new Response(source, {
+      headers: {
+        'Content-Type': 'application/octet-stream',
+        'Cache-Control': 'public, max-age=86400',
+      },
+    })
+  } finally {
+    inflight.delete(key)
+  }
+})

package/src/server/api/search.ts

@@ -1,3 +1,4 @@
+import GithubSlugger from 'github-slugger';
 import { defineHandler, HTTPError } from 'nitro';
 import { useDatabase } from 'nitro/database';
 import type { OpenAPIV3 } from 'openapi-types';
@@ -143,15 +144,17 @@ function findMatch(
   title: string,
   headings: string,
   body: string,
-): { match: 'title' | 'heading' | 'body'; snippet: string } {
+): { match: 'title' | 'heading' | 'body'; snippet: string; slug?: string } {
   if (title.toLowerCase().includes(query)) {
     return { match: 'title', snippet: title };
   }
 
+  const slugger = new GithubSlugger();
   const headingList = headings.split('\n').filter(Boolean);
   for (const h of headingList) {
+    const slug = slugger.slug(h);
     if (h.toLowerCase().includes(query)) {
-      return { match: 'heading', snippet: h };
+      return { match: 'heading', snippet: h, slug };
     }
   }
 
@@ -214,10 +217,12 @@ export default defineHandler(async event => {
 
   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);
+    const { match, snippet, slug } = findMatch(queryLower, r.title as string, r.headings as string, r.body as string);
+    const id = match === 'heading' && slug ? `${r.id}#${slug}` : r.id as string;
+    const url = match === 'heading' && slug ? `${r.url}#${slug}` : r.url as string;
     return {
-      id: r.id,
-      url: r.url,
+      id,
+      url,
       type: r.type,
       content: r.title,
       match,

package/src/server/entry-client.tsx

@@ -7,7 +7,7 @@ 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 { prefetchSearchSuggestions, 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';
@@ -56,6 +56,7 @@ async function hydrate() {
       window as unknown as { __PAGE_DATA__?: EmbeddedData }
     ).__PAGE_DATA__;
 
+    prefetchSearchSuggestions();
     const config: ChronicleConfig = embedded?.config ?? defaultConfig;
     const tree: Root = embedded?.tree ?? { name: 'root', children: [] };
 

package/src/server/entry-server.tsx

@@ -13,6 +13,7 @@ import { getPageTree, getPage, getPageNav, loadPageModule, extractFrontmatter, g
 import { getFirstApiUrl } from '@/lib/api-routes';
 import { StatusCodes } from 'http-status-codes';
 import { resolveDocsRedirect } from '@/lib/tree-utils';
+import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from '@/lib/image-utils';
 import { useNitroApp } from 'nitro/app';
 import { App } from './App';
 
@@ -126,9 +127,10 @@ 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} />
-          ))}
+          {[...new Set(pageImages)].map((src: string) => {
+            const href = isLocalImage(src) && !isSvg(src) ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
+            return <link key={src} rel="preload" as="image" href={href} />;
+          })}
           <script type="module" src={assets.entry} />
           <script dangerouslySetInnerHTML={{ __html: `window.__PAGE_DATA__ = ${safeJson}` }} />
         </head>

package/src/server/vite-config.ts

@@ -25,6 +25,12 @@ function getDatabaseConnector(preset?: string): { connector: string; options?: R
   }
 }
 
+const STATIC_PRESETS = new Set(['static', 'vercel-static', 'cloudflare-pages', 'github-pages']);
+
+function isStaticPreset(preset?: string): boolean {
+  return !!preset && STATIC_PRESETS.has(preset);
+}
+
 function resolveOutputDir(projectRoot: string, preset?: string): string {
   if (preset === 'vercel' || preset === 'vercel-static') return path.resolve(projectRoot, '.vercel/output');
   return path.resolve(projectRoot, '.output');
@@ -67,6 +73,7 @@ export async function createViteConfig(
       nitro({
         serverDir: path.resolve(packageRoot, 'src/server'),
         ...(preset && { preset }),
+        ignore: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx'],
       }),
       mdx({
         default: defineFumadocsConfig({
@@ -94,7 +101,7 @@ export async function createViteConfig(
               }],
               remarkUnusedDirectives,
               remarkResolveLinks,
-              remarkResolveImages,
+              [remarkResolveImages, { optimize: !isStaticPreset(preset) }],
               remarkMdxMermaid,
               remarkReadingTime,
             ],
@@ -132,7 +139,8 @@ export async function createViteConfig(
       }
     },
     ssr: {
-      noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core']
+      noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core'],
+      external: ['analytics', 'use-analytics', '@analytics/google-analytics'],
     },
     environments: {
       client: {
@@ -150,6 +158,13 @@ export async function createViteConfig(
       output: {
         dir: resolveOutputDir(projectRoot, preset),
       },
+      externals: ['sharp'],
+      storage: {
+        'image-cache': {
+          driver: 'fs',
+          base: path.resolve(projectRoot, '.cache/images'),
+        },
+      },
       experimental: {
         database: true,
       },

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

@@ -27,7 +27,9 @@
 .content h6 {
   margin-top: var(--rs-space-8);
   margin-bottom: var(--rs-space-5);
-  line-height: 1.4;
+  font-family: var(--rs-font-title);
+  font-weight: var(--rs-font-weight-medium);
+  color: var(--rs-color-foreground-base-primary);
 }
 
 .content > :is(h1, h2, h3, h4, h5, h6):first-child {
@@ -35,10 +37,39 @@
 }
 
 .content h1 {
+  font-size: var(--rs-font-size-t4);
+  line-height: var(--rs-line-height-t4);
   margin-top: 0;
   margin-bottom: var(--rs-space-10);
 }
 
+.content h2 {
+  font-size: var(--rs-font-size-t3);
+  line-height: var(--rs-line-height-t3);
+  margin-top: var(--rs-space-8);
+  margin-bottom: var(--rs-space-8);
+}
+
+.content h3 {
+  font-size: var(--rs-font-size-t2);
+  line-height: var(--rs-line-height-t2);
+}
+
+.content h4 {
+  font-size: var(--rs-font-size-t1);
+  line-height: var(--rs-line-height-t1);
+}
+
+.content h5 {
+  font-size: var(--rs-font-size-large);
+  line-height: var(--rs-line-height-large);
+}
+
+.content h6 {
+  font-size: var(--rs-font-size-regular);
+  line-height: var(--rs-line-height-regular);
+}
+
 .content p {
   color: var(--rs-color-foreground-base-primary);
   font-family: var(--rs-font-body);
@@ -48,18 +79,6 @@
   line-height: 171.429%;
 }
 
-.content h2 {
-  margin-top: var(--rs-space-8);
-  margin-bottom: var(--rs-space-8);
-  color: var(--rs-color-foreground-base-primary);
-  font-family: var(--rs-font-title);
-  font-size: var(--rs-font-size-t3);
-  font-style: normal;
-  font-weight: var(--rs-font-weight-medium);
-  line-height: var(--rs-line-height-t3);
-  letter-spacing: var(--rs-letter-spacing-t3);
-}
-
 .content ul,
 .content ol {
   padding-left: var(--rs-space-5);
@@ -71,6 +90,10 @@
   margin: var(--rs-space-2) 0;
 }
 
+.content a {
+  font-size: inherit;
+}
+
 .content [role="tablist"] {
   margin-bottom: var(--rs-space-3);
 }
@@ -81,12 +104,21 @@
 }
 
 .content table {
-  display: block;
-  max-width: 100%;
-  overflow-x: auto;
+  display: table;
+  table-layout: fixed;
+  width: 100%;
   margin-bottom: var(--rs-space-5);
 }
 
+.content table td,
+.content table th {
+  overflow: visible;
+  white-space: normal;
+  text-overflow: unset;
+  word-wrap: break-word;
+  vertical-align: top;
+}
+
 .content details {
   border: 1px solid var(--rs-color-border-base-primary);
   border-radius: var(--rs-radius-2);

package/src/themes/paper/Layout.module.css

@@ -77,9 +77,14 @@
 
 .content {
   flex: 1;
+  margin-left: calc(-1 * var(--paper-sidebar-width));
   background: var(--rs-color-background-neutral-primary);
 }
 
+.contentFull {
+  margin-left: 0;
+}
+
 .hiddenTrigger {
   display: none;
 }

package/src/themes/paper/Layout.tsx

@@ -82,7 +82,7 @@ function LayoutInner({
             ) : null}
           </aside>
         ) : null}
-        <div className={cx(styles.content, classNames?.content)}>
+        <div className={cx(styles.content, classNames?.content, { [styles.contentFull]: !showSidebar })}>
           {config.search?.enabled && <Search classNames={{ trigger: styles.hiddenTrigger }} />}
           {children}
         </div>

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

@@ -1,15 +1,9 @@
 .main {
   flex: 1;
   width: 100%;
-  max-width: calc(1024px + var(--rs-space-17));
+  max-width: 1024px;
   margin: 0 auto;
   padding-top: var(--rs-space-12);
-  padding-right: var(--rs-space-17);
-}
-
-.readerMode {
-  padding-right: 0;
-  margin: 0 auto;
 }
 
 .navbar {
@@ -147,37 +141,45 @@
 .content h4,
 .content h5,
 .content h6 {
-  line-height: 1.4;
+  font-family: var(--rs-font-title);
+  font-weight: var(--rs-font-weight-medium);
+  color: var(--rs-color-foreground-base-primary);
 }
 
 .content h1 {
+  font-size: var(--rs-font-size-t4);
+  line-height: var(--rs-line-height-t4);
   margin: 2rem 0 1rem;
-  font-size: 2rem;
 }
 
 .content h2 {
+  font-size: var(--rs-font-size-t3);
+  line-height: var(--rs-line-height-t3);
   margin: 1.75rem 0 0.75rem;
-  font-size: 1.5rem;
 }
 
 .content h3 {
+  font-size: var(--rs-font-size-t2);
+  line-height: var(--rs-line-height-t2);
   margin: 1.5rem 0 0.5rem;
-  font-size: 1.25rem;
 }
 
 .content h4 {
+  font-size: var(--rs-font-size-t1);
+  line-height: var(--rs-line-height-t1);
   margin: 1.25rem 0 0.5rem;
-  font-size: 1.1rem;
 }
 
 .content h5 {
+  font-size: var(--rs-font-size-large);
+  line-height: var(--rs-line-height-large);
   margin: 1rem 0 0.5rem;
-  font-size: 1rem;
 }
 
 .content h6 {
+  font-size: var(--rs-font-size-regular);
+  line-height: var(--rs-line-height-regular);
   margin: 1rem 0 0.5rem;
-  font-size: 0.875rem;
 }
 
 .content p {
@@ -198,12 +200,25 @@
 }
 
 .content table {
-  display: block;
+  display: table;
+  table-layout: fixed;
   width: 100%;
-  overflow-x: auto;
   margin-bottom: var(--rs-space-5);
 }
 
+.content table td,
+.content table th {
+  overflow: visible;
+  white-space: normal;
+  text-overflow: unset;
+  word-wrap: break-word;
+  vertical-align: top;
+}
+
+.content a {
+  font-size: inherit;
+}
+
 .content [role="tablist"] {
   margin-bottom: var(--rs-space-3);
 }

package/src/themes/paper/Page.tsx

@@ -41,7 +41,7 @@ export function Page({ page, tree }: ThemePageProps) {
 
   return (
     <>
-      <main className={`${styles.main} ${readerMode ? styles.readerMode : ''}`}>
+      <main className={styles.main}>
         <div className={styles.navbar}>
           <div className={styles.navLeft}>
             <div className={styles.arrows}>