@raystack/chronicle 0.1.0-canary.5a730d4 → 0.1.0-canary.67113f8

package/src/lib/source.ts

@@ -1,138 +1,160 @@
-import type { MDXContent } from 'mdx/types'
-import type { Frontmatter, PageTree, PageTreeItem } from '@/types'
-
-const meta: Record<string, Frontmatter> = import.meta.glob(
-  '@content/**/*.{mdx,md}',
-  { eager: true, import: 'frontmatter' }
-)
-
-const loaders: Record<string, () => Promise<{ default: MDXContent }>> = import.meta.glob(
-  '@content/**/*.{mdx,md}'
-)
-
-export interface SourcePage {
-  url: string
-  slugs: string[]
-  filePath: string
-  frontmatter: Frontmatter
+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 { TableOfContents } from 'fumadocs-core/toc';
+import type { Frontmatter } from '@/types';
+
+function getContentDir(): string {
+  return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
 }
 
-// Compute common directory prefix of all glob keys once
-function computePrefix(keys: string[]): string {
-  if (keys.length === 0) return ''
-  const dirs = keys.map((k) => k.split('/').slice(0, -1)) // drop filename
-  const first = dirs[0]
-  let depth = 0
-  for (let i = 0; i < first.length; i++) {
-    if (dirs.every((d) => d[i] === first[i])) {
-      depth = i + 1
-    } else {
-      break
+async function scanFiles(contentDir: string) {
+  const files: {
+    type: 'page' | 'meta';
+    path: string;
+    data: Record<string, unknown>;
+  }[] = [];
+
+  async function scan(dir: string, prefix: string[] = []) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules')
+          continue;
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = [...prefix, entry.name].join('/');
+
+        if (entry.isDirectory()) {
+          await scan(fullPath, [...prefix, entry.name]);
+          continue;
+        }
+
+        if (entry.name.endsWith('.mdx') || entry.name.endsWith('.md')) {
+          const raw = await fs.readFile(fullPath, 'utf-8');
+          const { data } = matter(raw);
+          files.push({
+            type: 'page',
+            path: relativePath,
+            data: { ...data, _relativePath: relativePath }
+          });
+        } else if (entry.name === 'meta.json' || entry.name === 'meta.yaml') {
+          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 {
+      /* directory not readable */
     }
   }
-  return first.slice(0, depth).join('/') + '/'
-}
 
-const prefix = computePrefix(Object.keys(meta))
-
-function filePathToSlugs(filePath: string): string[] {
-  const relative = filePath.slice(prefix.length)
-  const withoutExt = relative.replace(/\.(mdx|md)$/, '')
-  const parts = withoutExt.split('/').filter(Boolean)
-  if (parts[parts.length - 1] === 'index') parts.pop()
-  return parts
+  await scan(contentDir);
+  return files;
 }
 
-function slugsToUrl(slugs: string[]): string {
-  return slugs.length === 0 ? '/' : '/' + slugs.join('/')
+let cachedSource: ReturnType<typeof loader> | null = null;
+
+async function getSource() {
+  if (cachedSource) return cachedSource;
+  const contentDir = getContentDir();
+  const files = await scanFiles(contentDir);
+  cachedSource = loader({
+    source: { files },
+    baseUrl: '/'
+  });
+  return cachedSource;
 }
 
-let cachedPages: SourcePage[] | null = null
-
-export async function getPages(): Promise<SourcePage[]> {
-  if (cachedPages) return cachedPages
-
-  cachedPages = Object.entries(meta).map(([filePath, fm]) => {
-    const slugs = filePathToSlugs(filePath)
-    const baseName = slugs[slugs.length - 1] ?? 'index'
-    return {
-      url: slugsToUrl(slugs),
-      slugs,
-      filePath,
-      frontmatter: {
-        title: fm?.title ?? baseName,
-        description: fm?.description,
-        order: fm?.order,
-        icon: fm?.icon,
-        lastModified: fm?.lastModified,
-      },
-    }
-  })
+export { getSource as source };
 
-  return cachedPages
+export function invalidate() {
+  cachedSource = null;
 }
 
-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 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 loadPageComponent(page: SourcePage): Promise<MDXContent | null> {
-  const loader = loaders[page.filePath]
-  if (!loader) return null
-  const mod = await loader()
-  return mod.default
+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 function invalidate() {
-  cachedPages = 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);
+  }
+  return { ...tree, children: sortNodes(tree.children, orderMap) };
 }
 
-export async function buildPageTree(): Promise<PageTree> {
-  const pages = await getPages()
-  const folders = new Map<string, PageTreeItem[]>()
-  const rootPages: PageTreeItem[] = []
-
-  pages.forEach((page) => {
-    const isIndex = page.url === '/'
-    const item: PageTreeItem = {
-      type: 'page',
-      name: page.frontmatter.title,
-      url: page.url,
-      order: page.frontmatter.order ?? (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 getPageTree(): Promise<Root> {
+  const s = await getSource();
+  return sortTreeByOrder(s.pageTree as Root, s.getPages());
+}
 
-  const sortByOrder = (items: PageTreeItem[]) =>
-    items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
+export async function getPages() {
+  const s = await getSource();
+  return s.getPages();
+}
 
-  const children: PageTreeItem[] = sortByOrder(rootPages)
+export async function getPage(slugs?: string[]) {
+  const s = await getSource();
+  return s.getPage(slugs);
+}
 
-  const folderItems: PageTreeItem[] = []
-  folders.forEach((items, folder) => {
-    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 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,
+  };
+}
 
-  children.push(...sortByOrder(folderItems))
+export function getRelativePath(page: { data: unknown }): string {
+  return ((page.data as Record<string, unknown>)._relativePath as string) ?? '';
+}
 
-  return { name: 'root', children }
+const ssrModules = import.meta.glob<{ default?: MDXContent; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
+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/ApiLayout.tsx

@@ -1,29 +1,33 @@
-import type { ReactNode } from 'react'
-import { cx } from 'class-variance-authority'
-import { usePageContext } from '@/lib/page-context'
-import { buildApiPageTree } from '@/lib/api-routes'
-import { getTheme } from '@/themes/registry'
-import { Search } from '@/components/ui/search'
-import styles from './ApiLayout.module.css'
+import { cx } from 'class-variance-authority';
+import type { ReactNode } from 'react';
+import { Search } from '@/components/ui/search';
+import { buildApiPageTree } from '@/lib/api-routes';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+import styles from './ApiLayout.module.css';
 
 interface ApiLayoutProps {
-  children: ReactNode
+  children: ReactNode;
 }
 
 export function ApiLayout({ children }: ApiLayoutProps) {
-  const { config, apiSpecs } = usePageContext()
-  const { Layout, className } = getTheme(config.theme?.name)
-  const tree = buildApiPageTree(apiSpecs)
+  const { config, apiSpecs } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
+  const tree = buildApiPageTree(apiSpecs);
 
   return (
-    <Layout config={config} tree={tree} classNames={{
-      layout: cx(styles.layout, className),
-      body: styles.body,
-      sidebar: styles.sidebar,
-      content: styles.content,
-    }}>
+    <Layout
+      config={config}
+      tree={tree}
+      classNames={{
+        layout: cx(styles.layout, className),
+        body: styles.body,
+        sidebar: styles.sidebar,
+        content: styles.content
+      }}
+    >
       <Search className={styles.hiddenSearch} />
       {children}
     </Layout>
-  )
+  );
 }

package/src/pages/ApiPage.tsx

@@ -1,44 +1,41 @@
-import type { OpenAPIV3 } from 'openapi-types'
-import { Flex, Headline, Text } from '@raystack/apsara'
-import { usePageContext } from '@/lib/page-context'
-import { findApiOperation } from '@/lib/api-routes'
-import { EndpointPage } from '@/components/api'
-import { Head } from '@/lib/head'
-import type { ApiSpec } from '@/lib/openapi'
+import { Flex, Headline, Text } from '@raystack/apsara';
+import type { OpenAPIV3 } from 'openapi-types';
+import { EndpointPage } from '@/components/api';
+import { findApiOperation } from '@/lib/api-routes';
+import { Head } from '@/lib/head';
+import type { ApiSpec } from '@/lib/openapi';
+import { usePageContext } from '@/lib/page-context';
 
 interface ApiPageProps {
-  slug: string[]
+  slug: string[];
 }
 
 export function ApiPage({ slug }: ApiPageProps) {
-  const { config, apiSpecs } = usePageContext()
+  const { config, apiSpecs } = usePageContext();
 
   if (slug.length === 0) {
     return (
       <>
         <Head
-          title="API Reference"
+          title='API Reference'
           description={`API documentation for ${config.title}`}
           config={config}
         />
         <ApiLanding specs={apiSpecs} />
       </>
-    )
+    );
   }
 
-  const match = findApiOperation(apiSpecs, slug)
-  if (!match) return null
+  const match = findApiOperation(apiSpecs, slug);
+  if (!match) return null;
 
-  const operation = match.operation as OpenAPIV3.OperationObject
-  const title = operation.summary ?? `${match.method.toUpperCase()} ${match.path}`
+  const operation = match.operation as OpenAPIV3.OperationObject;
+  const title =
+    operation.summary ?? `${match.method.toUpperCase()} ${match.path}`;
 
   return (
     <>
-      <Head
-        title={title}
-        description={operation.description}
-        config={config}
-      />
+      <Head title={title} description={operation.description} config={config} />
       <EndpointPage
         method={match.method}
         path={match.path}
@@ -48,21 +45,29 @@ export function ApiPage({ slug }: ApiPageProps) {
         auth={match.spec.auth}
       />
     </>
-  )
+  );
 }
 
 function ApiLanding({ specs }: { specs: ApiSpec[] }) {
   return (
-    <Flex direction="column" gap="large" style={{ padding: 'var(--rs-space-7)' }}>
-      <Headline size="medium" as="h1">API Reference</Headline>
-      {specs.map((spec) => (
-        <Flex key={spec.name} direction="column" gap="small">
-          <Headline size="small" as="h2">{spec.name}</Headline>
+    <Flex
+      direction='column'
+      gap='large'
+      style={{ padding: 'var(--rs-space-7)' }}
+    >
+      <Headline size='medium' as='h1'>
+        API Reference
+      </Headline>
+      {specs.map(spec => (
+        <Flex key={spec.name} direction='column' gap='small'>
+          <Headline size='small' as='h2'>
+            {spec.name}
+          </Headline>
           {spec.document.info.description && (
             <Text size={3}>{spec.document.info.description}</Text>
           )}
         </Flex>
       ))}
     </Flex>
-  )
+  );
 }

package/src/pages/DocsLayout.tsx

@@ -1,18 +1,18 @@
-import type { ReactNode } from 'react'
-import { usePageContext } from '@/lib/page-context'
-import { getTheme } from '@/themes/registry'
+import type { ReactNode } from 'react';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
 
 interface DocsLayoutProps {
-  children: ReactNode
+  children: ReactNode;
 }
 
 export function DocsLayout({ children }: DocsLayoutProps) {
-  const { config, tree } = usePageContext()
-  const { Layout, className } = getTheme(config.theme?.name)
+  const { config, tree } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
 
   return (
     <Layout config={config} tree={tree} classNames={{ layout: className }}>
       {children}
     </Layout>
-  )
+  );
 }

package/src/pages/DocsPage.tsx

@@ -1,18 +1,18 @@
-import { usePageContext } from '@/lib/page-context'
-import { getTheme } from '@/themes/registry'
-import { Head } from '@/lib/head'
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
 
 interface DocsPageProps {
-  slug: string[]
+  slug: string[];
 }
 
 export function DocsPage({ slug }: DocsPageProps) {
-  const { config, tree, page } = usePageContext()
+  const { config, tree, page } = usePageContext();
 
-  if (!page) return null
+  if (!page) return null;
 
-  const { Page } = getTheme(config.theme?.name)
-  const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined
+  const { Page } = getTheme(config.theme?.name);
+  const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined;
 
   return (
     <>
@@ -25,7 +25,7 @@ export function DocsPage({ slug }: DocsPageProps) {
           '@type': 'Article',
           headline: page.frontmatter.title,
           description: page.frontmatter.description,
-          ...(pageUrl && { url: pageUrl }),
+          ...(pageUrl && { url: pageUrl })
         }}
       />
       <Page
@@ -33,11 +33,11 @@ export function DocsPage({ slug }: DocsPageProps) {
           slug,
           frontmatter: page.frontmatter,
           content: page.content,
-          toc: [],
+          toc: page.toc
         }}
         config={config}
         tree={tree}
       />
     </>
-  )
+  );
 }

package/src/pages/NotFound.tsx

@@ -1,10 +1,17 @@
-import { Flex, Headline, Text } from '@raystack/apsara'
+import { Flex, Headline, Text } from '@raystack/apsara';
 
 export function NotFound() {
   return (
-    <Flex direction="column" align="center" justify="center" style={{ minHeight: '60vh' }}>
-      <Headline size="large" as="h1">404</Headline>
+    <Flex
+      direction='column'
+      align='center'
+      justify='center'
+      style={{ minHeight: '60vh' }}
+    >
+      <Headline size='large' as='h1'>
+        404
+      </Headline>
       <Text size={3}>Page not found</Text>
     </Flex>
-  )
+  );
 }

package/src/server/App.tsx

@@ -1,29 +1,33 @@
-import '@raystack/apsara/normalize.css'
-import '@raystack/apsara/style.css'
-import { ThemeProvider } from '@raystack/apsara'
-import { useLocation } from 'react-router-dom'
-import { usePageContext } from '@/lib/page-context'
-import { Head } from '@/lib/head'
-import { DocsLayout } from '@/pages/DocsLayout'
-import { DocsPage } from '@/pages/DocsPage'
-import { ApiLayout } from '@/pages/ApiLayout'
-import { ApiPage } from '@/pages/ApiPage'
-import type { ChronicleConfig } from '@/types'
+import '@raystack/apsara/normalize.css';
+import '@raystack/apsara/style.css';
+import { ThemeProvider } from '@raystack/apsara';
+import { useLocation } from 'react-router';
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { ApiLayout } from '@/pages/ApiLayout';
+import { ApiPage } from '@/pages/ApiPage';
+import { DocsLayout } from '@/pages/DocsLayout';
+import { DocsPage } from '@/pages/DocsPage';
+import type { ChronicleConfig } from '@/types';
 
 function resolveRoute(pathname: string) {
   if (pathname.startsWith('/apis')) {
-    const slug = pathname.replace(/^\/apis\/?/, '').split('/').filter(Boolean)
-    return { type: 'api' as const, slug }
+    const slug = pathname
+      .replace(/^\/apis\/?/, '')
+      .split('/')
+      .filter(Boolean);
+    return { type: 'api' as const, slug };
   }
 
-  const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
-  return { type: 'docs' as const, slug }
+  const slug =
+    pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean);
+  return { type: 'docs' as const, slug };
 }
 
 export function App() {
-  const { pathname } = useLocation()
-  const { config } = usePageContext()
-  const route = resolveRoute(pathname)
+  const { pathname } = useLocation();
+  const { config } = usePageContext();
+  const route = resolveRoute(pathname);
 
   return (
     <ThemeProvider enableSystem>
@@ -38,7 +42,7 @@ export function App() {
         </DocsLayout>
       )}
     </ThemeProvider>
-  )
+  );
 }
 
 function RootHead({ config }: { config: ChronicleConfig }) {
@@ -47,13 +51,17 @@ function RootHead({ config }: { config: ChronicleConfig }) {
       title={config.title}
       description={config.description}
       config={config}
-      jsonLd={config.url ? {
-        '@context': 'https://schema.org',
-        '@type': 'WebSite',
-        name: config.title,
-        description: config.description,
-        url: config.url,
-      } : undefined}
+      jsonLd={
+        config.url
+          ? {
+              '@context': 'https://schema.org',
+              '@type': 'WebSite',
+              name: config.title,
+              description: config.description,
+              url: config.url
+            }
+          : undefined
+      }
     />
-  )
+  );
 }