@raystack/chronicle 0.1.0-canary.ac60f9f → 0.1.0-canary.bd7f9af

package/dist/cli/index.js

@@ -16,15 +16,43 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/lib/remark-unused-directives.ts
+import { visit } from "unist-util-visit";
+var remarkUnusedDirectives = () => {
+  return (tree) => {
+    visit(tree, ["textDirective"], (node) => {
+      const directive = node;
+      if (!directive.data) {
+        const hasAttributes = directive.attributes && Object.keys(directive.attributes).length > 0;
+        const hasChildren = directive.children && directive.children.length > 0;
+        if (!hasAttributes && !hasChildren) {
+          const name = directive.name;
+          if (!name)
+            return;
+          Object.keys(directive).forEach((key) => delete directive[key]);
+          directive.type = "text";
+          directive.value = `:${name}`;
+        }
+      }
+    });
+  };
+}, remark_unused_directives_default;
+var init_remark_unused_directives = __esm(() => {
+  remark_unused_directives_default = remarkUnusedDirectives;
+});
+
 // src/server/vite-config.ts
 var exports_vite_config = {};
 __export(exports_vite_config, {
   createViteConfig: () => createViteConfig
 });
 import react from "@vitejs/plugin-react";
+import { remarkDirectiveAdmonition, remarkMdxMermaid } from "fumadocs-core/mdx-plugins";
+import { defineConfig as defineFumadocsConfig } from "fumadocs-mdx/config";
 import mdx from "fumadocs-mdx/vite";
 import { nitro } from "nitro/vite";
 import path4 from "node:path";
+import remarkDirective from "remark-directive";
 async function createViteConfig(options) {
   const { packageRoot, projectRoot, contentDir, preset } = options;
   return {
@@ -35,13 +63,39 @@ async function createViteConfig(options) {
         serverDir: path4.resolve(packageRoot, "src/server"),
         ...preset && { preset }
       }),
-      mdx({}, { index: false }),
+      mdx({
+        default: defineFumadocsConfig({
+          mdxOptions: {
+            remarkPlugins: [
+              remarkDirective,
+              [remarkDirectiveAdmonition, {
+                tags: {
+                  CalloutContainer: "Callout",
+                  CalloutTitle: "CalloutTitle",
+                  CalloutDescription: "CalloutDescription"
+                },
+                types: {
+                  note: "accent",
+                  tip: "accent",
+                  info: "accent",
+                  warn: "attention",
+                  warning: "attention",
+                  danger: "alert",
+                  caution: "alert",
+                  success: "success"
+                }
+              }],
+              remark_unused_directives_default,
+              remarkMdxMermaid
+            ]
+          }
+        })
+      }, { index: false }),
       react()
     ],
     resolve: {
       alias: {
-        "@": path4.resolve(packageRoot, "src"),
-        "@content": path4.resolve(packageRoot, ".content")
+        "@": path4.resolve(packageRoot, "src")
       },
       conditions: ["module-sync", "import", "node"],
       dedupe: [
@@ -59,8 +113,7 @@ async function createViteConfig(options) {
     },
     define: {
       __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentDir),
-      __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot),
-      __CHRONICLE_PACKAGE_ROOT__: JSON.stringify(packageRoot)
+      __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot)
     },
     css: {
       modules: {
@@ -81,7 +134,9 @@ async function createViteConfig(options) {
     }
   };
 }
-var init_vite_config = () => {};
+var init_vite_config = __esm(() => {
+  init_remark_unused_directives();
+});
 
 // src/cli/index.ts
 import { Command as Command6 } from "commander";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.1.0-canary.ac60f9f",
+  "version": "0.1.0-canary.bd7f9af",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",

package/src/components/mdx/code.tsx

@@ -1,6 +1,7 @@
 'use client'
 
-import type { ComponentProps } from 'react'
+import { type ComponentProps, isValidElement, Children } from 'react'
+import { Mermaid } from './mermaid'
 import styles from './code.module.css'
 
 type PreProps = ComponentProps<'pre'> & {
@@ -16,6 +17,14 @@ export function MdxCode({ children, className, ...props }: ComponentProps<'code'
 }
 
 export function MdxPre({ children, title, className, ...props }: PreProps) {
+  // Detect mermaid code blocks
+  if (isValidElement(children)) {
+    const childProps = children.props as { className?: string; children?: string }
+    if (childProps.className?.includes('language-mermaid') && typeof childProps.children === 'string') {
+      return <Mermaid chart={childProps.children} />
+    }
+  }
+
   return (
     <div className={styles.codeBlock}>
       {title && <div className={styles.codeHeader}>{title}</div>}

package/src/components/mdx/details.module.css

@@ -1,35 +1,10 @@
 .details {
-  border: 1px solid var(--rs-color-border-base-primary);
-  border-radius: var(--rs-radius-2);
   margin: var(--rs-space-5) 0;
 }
 
-.summary {
-  padding: var(--rs-space-4) var(--rs-space-5);
-  cursor: pointer;
+.trigger {
   font-weight: 500;
   font-size: var(--rs-font-size-small);
-  color: var(--rs-color-text-base-primary);
-  background: var(--rs-color-background-base-secondary);
-  list-style: none;
-  display: flex;
-  align-items: center;
-  gap: var(--rs-space-3);
-}
-
-.summary::-webkit-details-marker {
-  display: none;
-}
-
-.summary::before {
-  content: '▶';
-  font-size: 10px;
-  transition: transform 0.2s ease;
-  color: var(--rs-color-text-base-secondary);
-}
-
-.details[open] > .summary::before {
-  transform: rotate(90deg);
 }
 
 .content {

package/src/components/mdx/details.tsx

@@ -1,9 +1,8 @@
 import type { ComponentProps } from 'react'
-import styles from './details.module.css'
 
 export function MdxDetails({ children, className, ...props }: ComponentProps<'details'>) {
   return (
-    <details className={`${styles.details} ${className ?? ''}`} {...props}>
+    <details className={className} {...props}>
       {children}
     </details>
   )
@@ -11,7 +10,7 @@ export function MdxDetails({ children, className, ...props }: ComponentProps<'de
 
 export function MdxSummary({ children, className, ...props }: ComponentProps<'summary'>) {
   return (
-    <summary className={`${styles.summary} ${className ?? ''}`} {...props}>
+    <summary className={className} {...props}>
       {children}
     </summary>
   )

package/src/components/ui/breadcrumbs.tsx

@@ -1,53 +1,19 @@
 'use client'
 
 import { Breadcrumb } from '@raystack/apsara'
-import type { PageTree, PageTreeItem } from '@/types'
+import { getBreadcrumbItems } from 'fumadocs-core/breadcrumb'
+import type { Root } from 'fumadocs-core/page-tree'
 
 interface BreadcrumbsProps {
   slug: string[]
-  tree: PageTree
-}
-
-function findInTree(items: PageTreeItem[], targetPath: string): PageTreeItem | undefined {
-  for (const item of items) {
-    const itemUrl = item.url || `/${item.name.toLowerCase().replace(/\s+/g, '-')}`
-    if (itemUrl === targetPath || itemUrl === `/${targetPath}`) {
-      return item
-    }
-    if (item.children) {
-      const found = findInTree(item.children, targetPath)
-      if (found) return found
-    }
-  }
-  return undefined
-}
-
-function getFirstPageUrl(item: PageTreeItem): string | undefined {
-  if (item.type === 'page' && item.url) {
-    return item.url
-  }
-  if (item.children) {
-    for (const child of item.children) {
-      const url = getFirstPageUrl(child)
-      if (url) return url
-    }
-  }
-  return undefined
+  tree: Root
 }
 
 export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
-  const items: { label: string; href: string }[] = []
+  const url = slug.length === 0 ? '/' : `/${slug.join('/')}`
+  const items = getBreadcrumbItems(url, tree, { includePage: true })
 
-  for (let i = 0; i < slug.length; i++) {
-    const currentPath = `/${slug.slice(0, i + 1).join('/')}`
-    const node = findInTree(tree.children, currentPath)
-    const href = node?.url || (node && getFirstPageUrl(node)) || currentPath
-    const label = node?.name ?? slug[i]
-    items.push({
-      label: label.charAt(0).toUpperCase() + label.slice(1),
-      href,
-    })
-  }
+  if (items.length === 0) return null
 
   return (
     <Breadcrumb size="small">
@@ -55,10 +21,10 @@ export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
         const breadcrumbItem = (
           <Breadcrumb.Item
             key={`item-${index}`}
-            href={item.href}
+            href={item.url}
             current={index === items.length - 1}
           >
-            {item.label}
+            {item.name}
           </Breadcrumb.Item>
         )
         if (index === 0) return [breadcrumbItem]

package/src/lib/api-routes.ts

@@ -1,6 +1,6 @@
 import type { OpenAPIV3 } from 'openapi-types'
 import slugify from 'slugify'
-import type { PageTree, PageTreeItem } from '@/types/content'
+import type { Root, Node, Item, Folder } from 'fumadocs-core/page-tree'
 import type { ApiSpec } from './openapi'
 
 export function getSpecSlug(spec: ApiSpec): string {
@@ -56,16 +56,15 @@ export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatc
   return null
 }
 
-export function buildApiPageTree(specs: ApiSpec[]): PageTree {
-  const children: PageTreeItem[] = []
+export function buildApiPageTree(specs: ApiSpec[]): Root {
+  const children: Node[] = []
 
   for (const spec of specs) {
     const specSlug = getSpecSlug(spec)
     const paths = spec.document.paths ?? {}
     const tags = spec.document.tags ?? []
 
-    // Group operations by tag (case-insensitive to avoid duplicates)
-    const opsByTag = new Map<string, PageTreeItem[]>()
+    const opsByTag = new Map<string, Item[]>()
     const tagDisplayName = new Map<string, string>()
 
     for (const [, pathItem] of Object.entries(paths)) {
@@ -90,7 +89,6 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
       }
     }
 
-    // Use doc.tags display names where available
     for (const t of tags) {
       const key = t.name.toLowerCase()
       if (opsByTag.has(key)) {
@@ -98,7 +96,7 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
       }
     }
 
-    const tagFolders: PageTreeItem[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
+    const tagFolders: Folder[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
       type: 'folder' as const,
       name: tagDisplayName.get(key) ?? key,
       icon: 'rectangle-stack',
@@ -110,7 +108,7 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
         type: 'folder',
         name: spec.name,
         children: tagFolders,
-      })
+      } as Folder)
     } else {
       children.push(...tagFolders)
     }

package/src/lib/page-context.tsx

@@ -8,7 +8,7 @@ import React, {
 import { useLocation } from 'react-router';
 import { mdxComponents } from '@/components/mdx';
 import type { ApiSpec } from '@/lib/openapi';
-import type { ChronicleConfig, Frontmatter, PageTree } from '@/types';
+import type { ChronicleConfig, Frontmatter, Root } from '@/types';
 
 interface PageData {
   slug: string[];
@@ -18,7 +18,7 @@ interface PageData {
 
 interface PageContextValue {
   config: ChronicleConfig;
-  tree: PageTree;
+  tree: Root;
   page: PageData | null;
   apiSpecs: ApiSpec[];
 }
@@ -31,7 +31,7 @@ export function usePageContext(): PageContextValue {
     console.error('usePageContext: no context found!');
     return {
       config: { title: 'Documentation' },
-      tree: { name: 'root', children: [] },
+      tree: { name: 'root', children: [] } as Root,
       page: null,
       apiSpecs: []
     };
@@ -41,14 +41,24 @@ export function usePageContext(): PageContextValue {
 
 interface PageProviderProps {
   initialConfig: ChronicleConfig;
-  initialTree: PageTree;
+  initialTree: Root;
   initialPage: PageData | null;
   initialApiSpecs: ApiSpec[];
   children: ReactNode;
 }
 
+const contentModules = import.meta.glob<{ default?: React.ComponentType<any> }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
 async function loadMdxComponent(relativePath: string): Promise<ReactNode> {
-  const mod = await import(/* @vite-ignore */ `/.content/${relativePath}`);
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = contentModules[key];
+  if (!loader) return null;
+  const mod = await loader();
   return mod.default
     ? React.createElement(mod.default, { components: mdxComponents })
     : null;
@@ -62,7 +72,7 @@ export function PageProvider({
   children
 }: PageProviderProps) {
   const { pathname } = useLocation();
-  const [tree] = useState<PageTree>(initialTree);
+  const [tree] = useState<Root>(initialTree);
   const [page, setPage] = useState<PageData | null>(initialPage);
   const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
   const [currentPath, setCurrentPath] = useState(pathname);

package/src/lib/source.ts

@@ -1,16 +1,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { loader } from 'fumadocs-core/source';
+import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
 import matter from 'gray-matter';
 import type { MDXContent } from 'mdx/types';
-import type { Frontmatter, PageTree, PageTreeItem } from '@/types';
-
-export interface SourcePage {
-  url: string;
-  slugs: string[];
-  filePath: string;
-  frontmatter: Frontmatter;
-}
 
 function getContentDir(): string {
   return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
@@ -43,7 +36,7 @@ async function scanFiles(contentDir: string) {
           files.push({
             type: 'page',
             path: relativePath,
-            data: { ...data, _absolutePath: fullPath }
+            data: { ...data, _relativePath: relativePath }
           });
         } else if (entry.name === 'meta.json' || entry.name === 'meta.yaml') {
           const raw = await fs.readFile(fullPath, 'utf-8');
@@ -63,7 +56,6 @@ async function scanFiles(contentDir: string) {
 }
 
 let cachedSource: ReturnType<typeof loader> | null = null;
-let cachedPages: SourcePage[] | null = null;
 
 async function getSource() {
   if (cachedSource) return cachedSource;
@@ -76,111 +68,72 @@ async function getSource() {
   return cachedSource;
 }
 
+export { getSource as source };
+
 export function invalidate() {
   cachedSource = null;
-  cachedPages = null;
 }
 
-export async function getPages(): Promise<SourcePage[]> {
-  if (cachedPages) return cachedPages;
+function getOrder(node: Node, orderMap: Map<string, number>): number | undefined {
+  if (node.type === 'page') return orderMap.get(node.url);
+  if (node.type === 'folder' && node.index) return orderMap.get(node.index.url);
+  return undefined;
+}
 
+function sortNodes(nodes: Node[], orderMap: Map<string, number>): Node[] {
+  return [...nodes]
+    .map(n =>
+      n.type === 'folder'
+        ? ({ ...n, children: sortNodes(n.children, orderMap) } as Folder)
+        : n
+    )
+    .sort(
+      (a, b) =>
+        (getOrder(a, orderMap) ?? Number.MAX_SAFE_INTEGER) -
+        (getOrder(b, orderMap) ?? Number.MAX_SAFE_INTEGER)
+    );
+}
+
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
+  const orderMap = new Map<string, number>();
+  for (const page of pages) {
+    const d = page.data as Record<string, unknown>;
+    const order = d.order as number | undefined;
+    if (order !== undefined) orderMap.set(page.url, order);
+    if (page.url === '/') orderMap.set('/', order ?? 0);
+  }
+  return { ...tree, children: sortNodes(tree.children, orderMap) };
+}
+
+export async function getPageTree(): Promise<Root> {
   const s = await getSource();
-  cachedPages = s.getPages().map(page => {
-    const data = page.data as Record<string, unknown>;
-    return {
-      url: page.url,
-      slugs: page.slugs,
-      filePath: (data._absolutePath as string) ?? '',
-      frontmatter: {
-        title:
-          (data.title as string) ??
-          page.slugs[page.slugs.length - 1] ??
-          'Untitled',
-        description: data.description as string | undefined,
-        order: data.order as number | undefined,
-        icon: data.icon as string | undefined,
-        lastModified: data.lastModified as string | undefined
-      }
-    };
-  });
+  return sortTreeByOrder(s.pageTree as Root, s.getPages());
+}
 
-  return cachedPages;
+export async function getPages() {
+  const s = await getSource();
+  return s.getPages();
 }
 
-export async function getPage(slug?: string[]): Promise<SourcePage | null> {
-  const pages = await getPages();
-  const targetUrl = !slug || slug.length === 0 ? '/' : `/${slug.join('/')}`;
-  return pages.find(p => p.url === targetUrl) ?? null;
+export async function getPage(slugs?: string[]) {
+  const s = await getSource();
+  return s.getPage(slugs);
 }
 
 export async function loadPageComponent(
-  page: SourcePage
+  relativePath: string
 ): Promise<MDXContent | null> {
-  if (!page.filePath) return null;
+  if (!relativePath) return null;
+  const contentDir = getContentDir();
+  const fullPath = path.join(contentDir, relativePath);
   try {
-    await fs.access(page.filePath);
+    await fs.access(fullPath);
   } catch {
     return null;
   }
-  const contentDir = getContentDir();
-  const relativePath = path.relative(contentDir, page.filePath);
   const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
   const mod = relativePath.endsWith('.md')
-    ? await import(`@content/${withoutExt}.md`)
-    : await import(`@content/${withoutExt}.mdx`);
+    ? await import(`../../.content/${withoutExt}.md`)
+    : await import(`../../.content/${withoutExt}.mdx`);
   return mod.default;
 }
-
-export async function buildPageTree(): Promise<PageTree> {
-  const s = await getSource();
-  const pages = s.getPages();
-  const folders = new Map<string, PageTreeItem[]>();
-  const rootPages: PageTreeItem[] = [];
-
-  for (const page of pages) {
-    const data = page.data as Record<string, unknown>;
-    const isIndex = page.url === '/';
-    const item: PageTreeItem = {
-      type: 'page',
-      name: (data.title as string) ?? page.slugs.join('/') ?? 'Untitled',
-      url: page.url,
-      order: (data.order as number | undefined) ?? (isIndex ? 0 : undefined)
-    };
-
-    if (page.slugs.length > 1) {
-      const folder = page.slugs[0];
-      if (!folders.has(folder)) {
-        folders.set(folder, []);
-      }
-      folders.get(folder)?.push(item);
-    } else {
-      rootPages.push(item);
-    }
-  }
-
-  const sortByOrder = (items: PageTreeItem[]) =>
-    items.sort(
-      (a, b) =>
-        (a.order ?? Number.MAX_SAFE_INTEGER) -
-        (b.order ?? Number.MAX_SAFE_INTEGER)
-    );
-
-  const children: PageTreeItem[] = sortByOrder(rootPages);
-
-  const folderItems: PageTreeItem[] = [];
-  for (const [folder, items] of folders) {
-    const sorted = sortByOrder(items);
-    const indexPage = items.find(item => item.url === `/${folder}`);
-    const folderOrder = indexPage?.order ?? sorted[0]?.order;
-    folderItems.push({
-      type: 'folder',
-      name: `${folder.charAt(0).toUpperCase()}${folder.slice(1)}`,
-      order: folderOrder,
-      children: sorted
-    });
-  }
-
-  children.push(...sortByOrder(folderItems));
-
-  return { name: 'root', children };
-}

package/src/server/api/page/[...slug].ts

@@ -1,4 +1,3 @@
-import path from 'node:path';
 import { defineHandler, HTTPError } from 'nitro';
 import { getPage } from '@/lib/source';
 
@@ -11,8 +10,17 @@ export default defineHandler(async event => {
     throw new HTTPError({ status: 404, message: 'Page not found' });
   }
 
-  const contentDir = __CHRONICLE_CONTENT_DIR__;
-  const relativePath = path.relative(contentDir, page.filePath);
+  const data = page.data as Record<string, unknown>;
+  const relativePath = (data._relativePath as string) ?? '';
 
-  return { frontmatter: page.frontmatter, relativePath };
+  return {
+    frontmatter: {
+      title: (data.title as string) ?? slug[slug.length - 1] ?? 'Untitled',
+      description: data.description as string | undefined,
+      order: data.order as number | undefined,
+      icon: data.icon as string | undefined,
+      lastModified: data.lastModified as string | undefined,
+    },
+    relativePath,
+  };
 });

package/src/server/entry-client.tsx

@@ -2,16 +2,17 @@ import '@vitejs/plugin-react/preamble';
 import React from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
 import { mdxComponents } from '@/components/mdx';
 import { PageProvider } from '@/lib/page-context';
-import type { ChronicleConfig, Frontmatter, PageTree } from '@/types';
+import type { ChronicleConfig, Frontmatter, Root } from '@/types';
 import type { ApiSpec } from '@/lib/openapi';
 import type { ReactNode } from 'react';
 import { App } from './App';
 
 interface EmbeddedData {
   config: ChronicleConfig;
-  tree: PageTree;
+  tree: Root;
   slug: string[];
   frontmatter: Frontmatter;
   relativePath: string;
@@ -26,7 +27,7 @@ async function hydrate() {
     const config: ChronicleConfig = embedded?.config ?? {
       title: 'Documentation'
     };
-    const tree: PageTree = embedded?.tree ?? { name: 'root', children: [] };
+    const tree: Root = embedded?.tree ?? { name: 'root', children: [] };
     const isApiPage =
       window.location.pathname.startsWith('/apis') && !!config.api?.length;
     const apiSpecs: ApiSpec[] = isApiPage
@@ -42,14 +43,16 @@ async function hydrate() {
     hydrateRoot(
       document.getElementById('root') as HTMLElement,
       <BrowserRouter>
-        <PageProvider
-          initialConfig={config}
-          initialTree={tree}
-          initialPage={page}
-          initialApiSpecs={apiSpecs}
-        >
-          <App />
-        </PageProvider>
+        <ReactRouterProvider>
+          <PageProvider
+            initialConfig={config}
+            initialTree={tree}
+            initialPage={page}
+            initialApiSpecs={apiSpecs}
+          >
+            <App />
+          </PageProvider>
+        </ReactRouterProvider>
       </BrowserRouter>
     );
   } catch (err) {
@@ -57,11 +60,20 @@ async function hydrate() {
   }
 }
 
+const contentModules = import.meta.glob<{ default?: React.ComponentType<any> }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
 async function loadPage(
   embedded: EmbeddedData
 ): Promise<{ slug: string[]; frontmatter: Frontmatter; content: ReactNode }> {
-  const mod = await import(/* @vite-ignore */ `/.content/${embedded.relativePath}`);
-  const content = mod.default
+  const withoutExt = embedded.relativePath.replace(/\.(mdx|md)$/, '');
+  const key = embedded.relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = contentModules[key];
+  const mod = loader ? await loader() : null;
+  const content = mod?.default
     ? React.createElement(mod.default, { components: mdxComponents })
     : null;
   return { slug: embedded.slug, frontmatter: embedded.frontmatter, content };

package/src/server/entry-server.tsx

@@ -1,14 +1,14 @@
 import '@raystack/apsara/normalize.css';
 import '@raystack/apsara/style.css';
-import path from 'node:path';
 import React from 'react';
 import { renderToReadableStream } from 'react-dom/server.edge';
 import { StaticRouter } from 'react-router';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
 import { mdxComponents } from '@/components/mdx';
 import { loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
-import { buildPageTree, getPage, loadPageComponent } from '@/lib/source';
+import { getPageTree, getPage, loadPageComponent } from '@/lib/source';
 import { App } from './App';
 
 // @ts-expect-error virtual import from Nitro
@@ -27,25 +27,32 @@ export default {
       ? await loadApiSpecs(config.api).catch(() => [])
       : [];
 
-    const [tree, sourcePage] = await Promise.all([
-      buildPageTree(),
+    const [tree, page] = await Promise.all([
+      getPageTree(),
       getPage(slug),
     ]);
 
-    const pageData = sourcePage
+    const data = page?.data as Record<string, unknown> | undefined;
+    const relativePath = (data?._relativePath as string) ?? null;
+
+    const pageData = page
       ? {
           slug,
-          frontmatter: sourcePage.frontmatter,
-          content: await loadPageComponent(sourcePage).then(component =>
-            component ? React.createElement(component, { components: mdxComponents }) : null
-          ),
+          frontmatter: {
+            title: (data?.title as string) ?? slug[slug.length - 1] ?? 'Untitled',
+            description: data?.description as string | undefined,
+            order: data?.order as number | undefined,
+            icon: data?.icon as string | undefined,
+            lastModified: data?.lastModified as string | undefined,
+          },
+          content: relativePath
+            ? await loadPageComponent(relativePath).then(component =>
+                component ? React.createElement(component, { components: mdxComponents }) : null
+              )
+            : null,
         }
       : null;
 
-    const relativePath = sourcePage
-      ? path.relative(__CHRONICLE_CONTENT_DIR__, sourcePage.filePath)
-      : null;
-
     const embeddedData = {
       config,
       tree,
@@ -74,14 +81,16 @@ export default {
         <body>
           <div id="root">
             <StaticRouter location={pathname}>
-              <PageProvider
-                initialConfig={config}
-                initialTree={tree}
-                initialPage={pageData}
-                initialApiSpecs={apiSpecs}
-              >
-                <App />
-              </PageProvider>
+              <ReactRouterProvider>
+                <PageProvider
+                  initialConfig={config}
+                  initialTree={tree}
+                  initialPage={pageData}
+                  initialApiSpecs={apiSpecs}
+                >
+                  <App />
+                </PageProvider>
+              </ReactRouterProvider>
             </StaticRouter>
           </div>
         </body>

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

@@ -16,8 +16,9 @@ export default defineHandler(async event => {
 
   const pages = await getPages();
   const docPages = pages.map(page => {
-    const lastmod = page.frontmatter.lastModified
-      ? `<lastmod>${new Date(page.frontmatter.lastModified).toISOString()}</lastmod>`
+    const data = page.data as Record<string, unknown>;
+    const lastmod = data.lastModified
+      ? `<lastmod>${new Date(data.lastModified as string).toISOString()}</lastmod>`
       : '';
     return `<url><loc>${baseUrl}/${page.slugs.join('/')}</loc>${lastmod}</url>`;
   });

package/src/server/vite-config.ts

@@ -1,8 +1,12 @@
 import react from '@vitejs/plugin-react';
+import { remarkDirectiveAdmonition, remarkMdxMermaid } from 'fumadocs-core/mdx-plugins';
+import { defineConfig as defineFumadocsConfig } from 'fumadocs-mdx/config';
 import mdx from 'fumadocs-mdx/vite';
 import { nitro } from 'nitro/vite';
 import path from 'node:path';
+import remarkDirective from 'remark-directive';
 import { type InlineConfig } from 'vite';
+import remarkUnusedDirectives from '../lib/remark-unused-directives';
 
 export interface ViteConfigOptions {
   packageRoot: string;
@@ -24,13 +28,39 @@ export async function createViteConfig(
         serverDir: path.resolve(packageRoot, 'src/server'),
         ...(preset && { preset }),
       }),
-      mdx({}, { index: false }),
+      mdx({
+        default: defineFumadocsConfig({
+          mdxOptions: {
+            remarkPlugins: [
+              remarkDirective,
+              [remarkDirectiveAdmonition, {
+                tags: {
+                  CalloutContainer: 'Callout',
+                  CalloutTitle: 'CalloutTitle',
+                  CalloutDescription: 'CalloutDescription',
+                },
+                types: {
+                  note: 'accent',
+                  tip: 'accent',
+                  info: 'accent',
+                  warn: 'attention',
+                  warning: 'attention',
+                  danger: 'alert',
+                  caution: 'alert',
+                  success: 'success',
+                },
+              }],
+              remarkUnusedDirectives,
+              remarkMdxMermaid,
+            ],
+          },
+        }),
+      }, { index: false }),
       react()
     ],
     resolve: {
       alias: {
         '@': path.resolve(packageRoot, 'src'),
-        '@content': path.resolve(packageRoot, '.content'),
       },
       conditions: ['module-sync', 'import', 'node'],
       dedupe: [
@@ -48,8 +78,7 @@ export async function createViteConfig(
     },
     define: {
       __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentDir),
-      __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot),
-      __CHRONICLE_PACKAGE_ROOT__: JSON.stringify(packageRoot)
+      __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot)
     },
     css: {
       modules: {

package/src/themes/default/Layout.tsx

@@ -14,7 +14,8 @@ import { MethodBadge } from '@/components/api/method-badge';
 import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
 import { Footer } from '@/components/ui/footer';
 import { Search } from '@/components/ui/search';
-import type { PageTreeItem, ThemeLayoutProps } from '@/types';
+import type { Node } from 'fumadocs-core/page-tree';
+import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
 
 const iconMap: Record<string, React.ReactNode> = {
@@ -96,9 +97,9 @@ export function Layout({
           className={cx(styles.sidebar, classNames?.sidebar)}
         >
           <Sidebar.Main ref={scrollRef}>
-            {tree.children.map(item => (
+            {tree.children.map((item, i) => (
               <SidebarNode
-                key={item.url ?? item.name}
+                key={item.type === 'page' ? item.url : (item.name?.toString() ?? i)}
                 item={item}
                 pathname={pathname}
               />
@@ -118,23 +119,24 @@ function SidebarNode({
   item,
   pathname
 }: {
-  item: PageTreeItem;
+  item: Node;
   pathname: string;
 }) {
   if (item.type === 'separator') {
     return null;
   }
 
-  if (item.type === 'folder' && item.children) {
+  if (item.type === 'folder') {
+    const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
     return (
       <Sidebar.Group
-        label={item.name}
-        leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+        label={item.name?.toString() ?? ''}
+        leadingIcon={icon ?? undefined}
         classNames={{ items: styles.groupItems }}
       >
-        {item.children.map(child => (
+        {item.children.map((child, i) => (
           <SidebarNode
-            key={child.url ?? child.name}
+            key={child.type === 'page' ? child.url : (child.name?.toString() ?? i)}
             item={child}
             pathname={pathname}
           />
@@ -145,13 +147,14 @@ function SidebarNode({
 
   const isActive = pathname === item.url;
   const href = item.url ?? '#';
+  const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
   const link = useMemo(() => <RouterLink to={href} />, [href]);
 
   return (
     <Sidebar.Item
       href={href}
       active={isActive}
-      leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+      leadingIcon={icon ?? undefined}
       as={link}
     >
       {item.name}

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

@@ -38,9 +38,53 @@
   margin-bottom: var(--rs-space-3);
 }
 
+.content img {
+  max-width: 100%;
+  height: auto;
+}
+
 .content table {
   display: block;
   max-width: 100%;
   overflow-x: auto;
   margin-bottom: var(--rs-space-5);
 }
+
+.content details {
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  margin: var(--rs-space-5) 0;
+  overflow: hidden;
+}
+
+.content details summary {
+  padding: var(--rs-space-4) var(--rs-space-5);
+  cursor: pointer;
+  font-weight: 500;
+  font-size: var(--rs-font-size-small);
+  color: var(--rs-color-text-base-primary);
+  background: var(--rs-color-background-base-secondary);
+  list-style: none;
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-3);
+}
+
+.content details summary::-webkit-details-marker {
+  display: none;
+}
+
+.content details summary::before {
+  content: '▶';
+  font-size: 10px;
+  transition: transform 0.2s ease;
+  color: var(--rs-color-text-base-secondary);
+}
+
+.content details[open] > summary::before {
+  transform: rotate(90deg);
+}
+
+.content details > :not(summary) {
+  padding: var(--rs-space-4) var(--rs-space-5);
+}

package/src/themes/default/Toc.tsx

@@ -1,46 +1,30 @@
 'use client';
 
 import { Text } from '@raystack/apsara';
-import { useEffect, useState } from 'react';
-import type { TocItem } from '@/types';
+import { AnchorProvider, useActiveAnchor } from 'fumadocs-core/toc';
+import type { TableOfContents, TOCItemType } from 'fumadocs-core/toc';
 import styles from './Toc.module.css';
 
 interface TocProps {
-  items: TocItem[];
+  items: TableOfContents;
 }
 
 export function Toc({ items }: TocProps) {
-  const [activeId, setActiveId] = useState<string>('');
-
-  // Filter to only show h2 and h3 headings
   const filteredItems = items.filter(
     item => item.depth >= 2 && item.depth <= 3
   );
 
-  useEffect(() => {
-    const headingIds = filteredItems.map(item => item.url.replace('#', ''));
-
-    const observer = new IntersectionObserver(
-      entries => {
-        entries.forEach(entry => {
-          if (entry.isIntersecting) {
-            setActiveId(entry.target.id);
-          }
-        });
-      },
-      // -80px top: offset for fixed header, -80% bottom: trigger when heading is in top 20% of viewport
-      { rootMargin: '-80px 0px -80% 0px' }
-    );
-
-    headingIds.forEach(id => {
-      const element = document.getElementById(id);
-      if (element) observer.observe(element);
-    });
+  if (filteredItems.length === 0) return null;
 
-    return () => observer.disconnect();
-  }, [filteredItems]);
+  return (
+    <AnchorProvider toc={filteredItems} single>
+      <TocContent items={filteredItems} />
+    </AnchorProvider>
+  );
+}
 
-  if (filteredItems.length === 0) return null;
+function TocContent({ items }: { items: TOCItemType[] }) {
+  const activeAnchor = useActiveAnchor();
 
   return (
     <aside className={styles.toc}>
@@ -48,9 +32,9 @@ export function Toc({ items }: TocProps) {
         On this page
       </Text>
       <nav className={styles.nav}>
-        {filteredItems.map(item => {
+        {items.map(item => {
           const id = item.url.replace('#', '');
-          const isActive = activeId === id;
+          const isActive = activeAnchor === id;
           const isNested = item.depth > 2;
           return (
             <a

package/src/themes/paper/ChapterNav.tsx

@@ -1,6 +1,6 @@
 import { Link as RouterLink, useLocation } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
-import type { PageTree, PageTreeItem } from '@/types';
+import type { Root, Node } from 'fumadocs-core/page-tree';
 import styles from './ChapterNav.module.css';
 
 const iconMap: Record<string, React.ReactNode> = {
@@ -12,16 +12,16 @@ const iconMap: Record<string, React.ReactNode> = {
 };
 
 interface ChapterNavProps {
-  tree: PageTree;
+  tree: Root;
 }
 
 function buildChapterIndices(
-  children: PageTreeItem[]
-): Map<PageTreeItem, number> {
-  const indices = new Map<PageTreeItem, number>();
+  children: Node[]
+): Map<Node, number> {
+  const indices = new Map<Node, number>();
   let index = 0;
   for (const item of children) {
-    if (item.type === 'folder' && item.children) {
+    if (item.type === 'folder') {
       index++;
       indices.set(item, index);
     }
@@ -39,17 +39,17 @@ export function ChapterNav({ tree }: ChapterNavProps) {
         {tree.children.map(item => {
           if (item.type === 'separator') return null;
 
-          if (item.type === 'folder' && item.children) {
+          if (item.type === 'folder') {
             const chapterIndex = chapterIndices.get(item) ?? 0;
             return (
-              <li key={item.name} className={styles.chapter}>
+              <li key={item.name?.toString()} className={styles.chapter}>
                 <span className={styles.chapterLabel}>
                   {String(chapterIndex).padStart(2, '0')}. {item.name}
                 </span>
                 <ul className={styles.chapterItems}>
                   {item.children.map(child => (
                     <ChapterItem
-                      key={child.url ?? child.name}
+                      key={child.type === 'page' ? child.url : (child.name?.toString() ?? '')}
                       item={child}
                       pathname={pathname}
                     />
@@ -61,7 +61,7 @@ export function ChapterNav({ tree }: ChapterNavProps) {
 
           return (
             <ChapterItem
-              key={item.url ?? item.name}
+              key={item.url ?? item.name?.toString() ?? ''}
               item={item}
               pathname={pathname}
             />
@@ -76,19 +76,19 @@ function ChapterItem({
   item,
   pathname
 }: {
-  item: PageTreeItem;
+  item: Node;
   pathname: string;
 }) {
   if (item.type === 'separator') return null;
 
-  if (item.type === 'folder' && item.children) {
+  if (item.type === 'folder') {
     return (
       <li>
         <span className={styles.subLabel}>{item.name}</span>
         <ul className={styles.chapterItems}>
           {item.children.map(child => (
             <ChapterItem
-              key={child.url ?? child.name}
+              key={child.type === 'page' ? child.url : (child.name?.toString() ?? '')}
               item={child}
               pathname={pathname}
             />
@@ -99,7 +99,7 @@ function ChapterItem({
   }
 
   const isActive = pathname === item.url;
-  const icon = item.icon ? iconMap[item.icon] : null;
+  const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
 
   return (
     <li>

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

@@ -174,6 +174,11 @@
   margin-bottom: var(--rs-space-3);
 }
 
+.content img {
+  max-width: 100%;
+  height: auto;
+}
+
 .content blockquote {
   margin: 1rem 0;
   padding-left: 1rem;

package/src/themes/paper/Page.tsx

@@ -2,59 +2,33 @@ import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
 import { Flex } from '@raystack/apsara';
 import { useMemo } from 'react';
 import { Link as RouterLink, useLocation } from 'react-router';
+import { getBreadcrumbItems } from 'fumadocs-core/breadcrumb';
+import { flattenTree } from 'fumadocs-core/page-tree';
 import { Search } from '@/components/ui/search';
-import type { PageTreeItem, ThemePageProps } from '@/types';
+import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
 import { ReadingProgress } from './ReadingProgress';
 
-function flattenTree(items: PageTreeItem[]): PageTreeItem[] {
-  const result: PageTreeItem[] = [];
-  for (const item of items) {
-    if (item.type === 'page' && item.url) result.push(item);
-    if (item.children) result.push(...flattenTree(item.children));
-  }
-  return result;
-}
-
-function findBreadcrumb(
-  items: PageTreeItem[],
-  slug: string[]
-): { label: string; href: string }[] {
-  const result: { label: string; href: string }[] = [];
-  for (let i = 0; i < slug.length; i++) {
-    const path = '/' + slug.slice(0, i + 1).join('/');
-    const found = findInTree(items, path);
-    result.push({ label: found?.name ?? slug[i], href: path });
-  }
-  return result;
-}
-
-function findInTree(
-  items: PageTreeItem[],
-  path: string
-): PageTreeItem | undefined {
-  for (const item of items) {
-    if (item.url === path) return item;
-    if (item.children) {
-      const found = findInTree(item.children, path);
-      if (found) return found;
-    }
-  }
-  return undefined;
-}
-
 export function Page({ page, config, tree }: ThemePageProps) {
   const { pathname } = useLocation();
 
   const { prev, next, crumbs } = useMemo(() => {
     const pages = flattenTree(tree.children);
     const currentIndex = pages.findIndex(p => p.url === pathname);
+    const breadcrumbItems = getBreadcrumbItems(
+      pathname,
+      tree,
+      { includePage: true }
+    );
     return {
       prev: currentIndex > 0 ? pages[currentIndex - 1] : null,
       next: currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null,
-      crumbs: findBreadcrumb(tree.children, page.slug)
+      crumbs: breadcrumbItems.map(item => ({
+        label: item.name,
+        href: item.url ?? pathname,
+      })),
     };
-  }, [tree, pathname, page.slug]);
+  }, [tree, pathname]);
 
   return (
     <>
@@ -63,7 +37,7 @@ export function Page({ page, config, tree }: ThemePageProps) {
           <Flex align='center' gap='small' className={styles.navLeft}>
             {prev ? (
               <RouterLink
-                to={prev.url!}
+                to={prev.url}
                 className={styles.arrow}
                 aria-label='Previous page'
               >
@@ -80,7 +54,7 @@ export function Page({ page, config, tree }: ThemePageProps) {
             )}
             {next ? (
               <RouterLink
-                to={next.url!}
+                to={next.url}
                 className={styles.arrow}
                 aria-label='Next page'
               >

package/src/themes/paper/ReadingProgress.tsx

@@ -2,7 +2,7 @@
 
 import { cx } from 'class-variance-authority';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import type { TocItem } from '@/types';
+import type { TOCItemType } from 'fumadocs-core/toc';
 import styles from './ReadingProgress.module.css';
 
 interface Heading {
@@ -68,7 +68,7 @@ function resolveOverlaps(headings: Heading[], maxPosition: number): Heading[] {
 }
 
 interface ReadingProgressProps {
-  items: TocItem[];
+  items: TOCItemType[];
 }
 
 export function ReadingProgress({ items }: ReadingProgressProps) {

package/src/types/content.ts

@@ -1,4 +1,8 @@
 import type { ReactNode } from 'react'
+import type { TableOfContents } from 'fumadocs-core/toc'
+
+export type { Root, Node, Item, Folder, Separator } from 'fumadocs-core/page-tree'
+export type { TOCItemType, TableOfContents } from 'fumadocs-core/toc'
 
 export interface Frontmatter {
   title: string
@@ -12,25 +16,5 @@ export interface Page {
   slug: string[]
   frontmatter: Frontmatter
   content: ReactNode
-  toc: TocItem[]
-}
-
-export interface TocItem {
-  title: string
-  url: string
-  depth: number
-}
-
-export interface PageTreeItem {
-  type: 'page' | 'folder' | 'separator'
-  name: string
-  url?: string
-  order?: number
-  icon?: string
-  children?: PageTreeItem[]
-}
-
-export interface PageTree {
-  name: string
-  children: PageTreeItem[]
+  toc: TableOfContents
 }

package/src/types/globals.d.ts

@@ -1,4 +1,3 @@
 // Vite build-time constants (injected via define in vite-config.ts)
 declare const __CHRONICLE_CONTENT_DIR__: string
 declare const __CHRONICLE_PROJECT_ROOT__: string
-declare const __CHRONICLE_PACKAGE_ROOT__: string

package/src/types/theme.ts

@@ -1,18 +1,19 @@
 import type { ReactNode } from 'react'
+import type { Root } from 'fumadocs-core/page-tree'
 import type { ChronicleConfig } from './config'
-import type { Page, PageTree } from './content'
+import type { Page } from './content'
 
 export interface ThemeLayoutProps {
   children: ReactNode
   config: ChronicleConfig
-  tree: PageTree
+  tree: Root
   classNames?: { layout?: string; body?: string; sidebar?: string; content?: string }
 }
 
 export interface ThemePageProps {
   page: Page
   config: ChronicleConfig
-  tree: PageTree
+  tree: Root
 }
 
 export interface Theme {