@raystack/chronicle 0.1.0-canary.6511afe → 0.1.0-canary.67113f8

package/src/lib/source.ts

@@ -1,16 +1,11 @@
 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;
-}
+import type { TableOfContents } from 'fumadocs-core/toc';
+import type { Frontmatter } from '@/types';
 
 function getContentDir(): string {
   return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
@@ -43,14 +38,18 @@ 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');
-          const data = entry.name.endsWith('.json')
-            ? JSON.parse(raw)
-            : matter(raw).data;
-          files.push({ type: 'meta', path: relativePath, data });
+          try {
+            const raw = await fs.readFile(fullPath, 'utf-8');
+            const data = entry.name.endsWith('.json')
+              ? JSON.parse(raw)
+              : matter(raw).data;
+            files.push({ type: 'meta', path: relativePath, data });
+          } catch {
+            /* malformed meta file */
+          }
         }
       }
     } catch {
@@ -63,7 +62,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 +74,87 @@ 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;
-
-  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 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;
 }
 
-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;
+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)
+    );
 }
 
-export async function loadPageComponent(
-  page: SourcePage
-): Promise<MDXContent | null> {
-  if (!page.filePath) return null;
-  try {
-    await fs.access(page.filePath);
-  } catch {
-    return null;
+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);
   }
-  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`);
-  return mod.default;
+  return { ...tree, children: sortNodes(tree.children, orderMap) };
+}
+
+export async function getPageTree(): Promise<Root> {
+  const s = await getSource();
+  return sortTreeByOrder(s.pageTree as Root, s.getPages());
 }
 
-export async function buildPageTree(): Promise<PageTree> {
+export async function getPages() {
   const s = await getSource();
-  const pages = s.getPages();
-  const folders = new Map<string, PageTreeItem[]>();
-  const rootPages: PageTreeItem[] = [];
+  return s.getPages();
+}
 
-  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);
-    }
-  }
+export async function getPage(slugs?: string[]) {
+  const s = await getSource();
+  return s.getPage(slugs);
+}
 
-  const sortByOrder = (items: PageTreeItem[]) =>
-    items.sort(
-      (a, b) =>
-        (a.order ?? Number.MAX_SAFE_INTEGER) -
-        (b.order ?? Number.MAX_SAFE_INTEGER)
-    );
+export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {
+  const d = page.data as Record<string, unknown>;
+  return {
+    title: (d.title as string) ?? fallbackTitle ?? 'Untitled',
+    description: d.description as string | undefined,
+    order: d.order as number | undefined,
+    icon: d.icon as string | undefined,
+    lastModified: d.lastModified as string | undefined,
+  };
+}
 
-  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
-    });
-  }
+export function getRelativePath(page: { data: unknown }): string {
+  return ((page.data as Record<string, unknown>)._relativePath as string) ?? '';
+}
 
-  children.push(...sortByOrder(folderItems));
+const ssrModules = import.meta.glob<{ default?: MDXContent; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
 
-  return { name: 'root', children };
+export async function loadPageModule(
+  relativePath: string
+): Promise<{ default: MDXContent | null; toc: TableOfContents }> {
+  if (!relativePath || relativePath.includes('..')) return { default: null, toc: [] };
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = ssrModules[key];
+  if (!loader) return { default: null, toc: [] };
+  const mod = await loader();
+  return { default: mod.default ?? null, toc: mod.toc ?? [] };
 }

package/src/pages/DocsPage.tsx

@@ -33,7 +33,7 @@ export function DocsPage({ slug }: DocsPageProps) {
           slug,
           frontmatter: page.frontmatter,
           content: page.content,
-          toc: []
+          toc: page.toc
         }}
         config={config}
         tree={tree}

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

@@ -1,6 +1,5 @@
-import path from 'node:path';
 import { defineHandler, HTTPError } from 'nitro';
-import { getPage } from '@/lib/source';
+import { getPage, extractFrontmatter, getRelativePath } from '@/lib/source';
 
 export default defineHandler(async event => {
   const slugParam = event.context.params?.slug ?? '';
@@ -11,8 +10,8 @@ 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);
-
-  return { frontmatter: page.frontmatter, relativePath };
+  return {
+    frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+    relativePath: getRelativePath(page),
+  };
 });

package/src/server/entry-client.tsx

@@ -1,17 +1,16 @@
 import '@vitejs/plugin-react/preamble';
-import React from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router';
-import { mdxComponents } from '@/components/mdx';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { loadMdxModule } from '@/lib/mdx-loader';
 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 +25,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
@@ -36,20 +35,27 @@ async function hydrate() {
       : [];
 
     const page = embedded?.relativePath
-      ? await loadPage(embedded)
+      ? {
+          slug: embedded.slug,
+          frontmatter: embedded.frontmatter,
+          ...(await loadMdxModule(embedded.relativePath)),
+        }
       : null;
 
     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}
+            loadMdx={loadMdxModule}
+          >
+            <App />
+          </PageProvider>
+        </ReactRouterProvider>
       </BrowserRouter>
     );
   } catch (err) {
@@ -57,14 +63,4 @@ async function hydrate() {
   }
 }
 
-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
-    ? React.createElement(mod.default, { components: mdxComponents })
-    : null;
-  return { slug: embedded.slug, frontmatter: embedded.frontmatter, content };
-}
-
 hydrate();

package/src/server/entry-server.tsx

@@ -1,19 +1,17 @@
 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, loadPageModule, extractFrontmatter, getRelativePath } from '@/lib/source';
 import { App } from './App';
 
-// @ts-expect-error virtual import from Nitro
 import clientAssets from './entry-client?assets=client';
-// @ts-expect-error virtual import from Nitro
 import serverAssets from './entry-server?assets=ssr';
 
 export default {
@@ -27,25 +25,25 @@ 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 relativePath = page ? getRelativePath(page) : null;
+    const mdxModule = relativePath ? await loadPageModule(relativePath) : null;
+
+    const pageData = page
       ? {
           slug,
-          frontmatter: sourcePage.frontmatter,
-          content: await loadPageComponent(sourcePage).then(component =>
-            component ? React.createElement(component, { components: mdxComponents }) : null
-          ),
+          frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+          content: mdxModule?.default
+            ? React.createElement(mdxModule.default, { components: mdxComponents })
+            : null,
+          toc: mdxModule?.toc ?? [],
         }
       : null;
 
-    const relativePath = sourcePage
-      ? path.relative(__CHRONICLE_CONTENT_DIR__, sourcePage.filePath)
-      : null;
-
     const embeddedData = {
       config,
       tree,
@@ -74,21 +72,28 @@ 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}
+                  loadMdx={async () => ({ content: null, toc: [] })}
+                >
+                  <App />
+                </PageProvider>
+              </ReactRouterProvider>
             </StaticRouter>
           </div>
         </body>
       </html>,
     );
 
+    const isApiRoute = pathname.startsWith('/apis');
+    const status = !page && !isApiRoute && slug.length > 0 ? 404 : 200;
+
     return new Response(stream, {
+      status,
       headers: { 'Content-Type': 'text/html;charset=utf-8' },
     });
   },

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,17 @@
 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';
+
+function resolveOutputDir(projectRoot: string, preset?: string): string {
+  if (preset === 'vercel' || preset === 'vercel-static') return path.resolve(projectRoot, '.vercel/output');
+  return path.resolve(projectRoot, '.output');
+}
 
 export interface ViteConfigOptions {
   packageRoot: string;
@@ -23,25 +32,40 @@ export async function createViteConfig(
       nitro({
         serverDir: path.resolve(packageRoot, 'src/server'),
         ...(preset && { preset }),
-        alias: {
-          '@content': path.resolve(packageRoot, '.content'),
-        },
       }),
-      mdx({}, { index: false }),
-      react(),
-      {
-        name: 'chronicle:content-alias',
-        resolveId(id) {
-          if (id.startsWith('@content/')) {
-            return path.resolve(packageRoot, '.content', id.slice('@content/'.length));
-          }
-        },
-      }
+      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: [
@@ -59,8 +83,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: {
@@ -78,6 +101,11 @@ export async function createViteConfig(
           }
         }
       }
-    }
+    },
+    nitro: {
+      output: {
+        dir: resolveOutputDir(projectRoot, preset),
+      },
+    },
   };
 }

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);
+}