@raystack/chronicle 0.1.0-canary.49fe67c → 0.1.0-canary.4a4a3f8

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,26 @@ 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}
+          >
+            <App />
+          </PageProvider>
+        </ReactRouterProvider>
       </BrowserRouter>
     );
   } catch (err) {
@@ -57,14 +62,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,14 +72,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,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,28 +32,42 @@ 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'],
-      preserveSymlinks: true,
       dedupe: [
         'react',
         'react-dom',
@@ -60,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: {
@@ -79,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);
+}

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;