@raystack/chronicle 0.1.0-canary.0efaef0 → 0.1.0-canary.1e5fdae

package/dist/cli/index.js

@@ -16,15 +16,48 @@ 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";
+function resolveOutputDir(projectRoot, preset) {
+  if (preset === "vercel" || preset === "vercel-static")
+    return path4.resolve(projectRoot, ".vercel/output");
+  return path4.resolve(projectRoot, ".output");
+}
 async function createViteConfig(options) {
   const { packageRoot, projectRoot, contentDir, preset } = options;
   return {
@@ -35,7 +68,34 @@ 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: {
@@ -58,8 +118,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: {
@@ -77,10 +136,17 @@ async function createViteConfig(options) {
           }
         }
       }
+    },
+    nitro: {
+      output: {
+        dir: resolveOutputDir(projectRoot, preset)
+      }
     }
   };
 }
-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.0efaef0",
+  "version": "0.1.0-canary.1e5fdae",
   "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/mdx/index.tsx

@@ -8,6 +8,20 @@ import { Mermaid } from './mermaid'
 import { MdxParagraph } from './paragraph'
 import { CalloutContainer, CalloutTitle, CalloutDescription, MdxBlockquote } from '@/components/common/callout'
 import { Tabs } from '@raystack/apsara'
+import { type ComponentProps, useEffect, useState } from 'react'
+
+function ClientOnly({ children }: { children: React.ReactNode }) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  return mounted ? <>{children}</> : null
+}
+
+function MdxTabs(props: ComponentProps<typeof Tabs>) {
+  return <ClientOnly><Tabs {...props} /></ClientOnly>
+}
+MdxTabs.List = Tabs.List
+MdxTabs.Trigger = Tabs.Trigger
+MdxTabs.Content = Tabs.Content
 
 export const mdxComponents: MDXComponents = {
   p: MdxParagraph,
@@ -27,7 +41,7 @@ export const mdxComponents: MDXComponents = {
   Callout: CalloutContainer,
   CalloutTitle,
   CalloutDescription,
-  Tabs,
+  Tabs: MdxTabs,
   Mermaid,
 }
 

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

@@ -1,4 +1,4 @@
-import React, {
+import {
   createContext,
   type ReactNode,
   useContext,
@@ -6,19 +6,21 @@ import React, {
   useState
 } from '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, TableOfContents } from '@/types';
+
+export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
 interface PageData {
   slug: string[];
   frontmatter: Frontmatter;
   content: ReactNode;
+  toc: TableOfContents;
 }
 
 interface PageContextValue {
   config: ChronicleConfig;
-  tree: PageTree;
+  tree: Root;
   page: PageData | null;
   apiSpecs: ApiSpec[];
 }
@@ -31,7 +33,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,31 +43,23 @@ export function usePageContext(): PageContextValue {
 
 interface PageProviderProps {
   initialConfig: ChronicleConfig;
-  initialTree: PageTree;
+  initialTree: Root;
   initialPage: PageData | null;
   initialApiSpecs: ApiSpec[];
+  loadMdx: MdxLoader;
   children: ReactNode;
 }
 
-async function loadMdxComponent(relativePath: string): Promise<ReactNode> {
-  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
-  const mod = relativePath.endsWith('.md')
-    ? await import(`../../.content/${withoutExt}.md`)
-    : await import(`../../.content/${withoutExt}.mdx`);
-  return mod.default
-    ? React.createElement(mod.default, { components: mdxComponents })
-    : null;
-}
-
 export function PageProvider({
   initialConfig,
   initialTree,
   initialPage,
   initialApiSpecs,
+  loadMdx,
   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);
@@ -98,9 +92,9 @@ export function PageProvider({
       .then(res => res.json())
       .then(async (data: { frontmatter: Frontmatter; relativePath: string }) => {
         if (cancelled.current) return;
-        const content = await loadMdxComponent(data.relativePath);
+        const { content, toc } = await loadMdx(data.relativePath);
         if (cancelled.current) return;
-        setPage({ slug, frontmatter: data.frontmatter, content });
+        setPage({ slug, frontmatter: data.frontmatter, content, toc });
       })
       .catch(() => {});
 

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 ?? [] };
 }