@raystack/chronicle 0.1.0-canary.111b55a → 0.1.0-canary.1e5fdae

package/src/server/build-search-index.ts

@@ -1,107 +1,117 @@
-import fs from 'fs/promises'
-import path from 'path'
-import matter from 'gray-matter'
-import { loadConfig } from '@/lib/config'
-import { loadApiSpecs } from '@/lib/openapi'
-import { getSpecSlug } from '@/lib/api-routes'
-import type { OpenAPIV3 } from 'openapi-types'
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import type { OpenAPIV3 } from 'openapi-types';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+import type { Heading, Text } from 'mdast';
+import { getSpecSlug } from '@/lib/api-routes';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
 
 interface SearchDocument {
-  id: string
-  url: string
-  title: string
-  content: string
-  type: 'page' | 'api'
+  id: string;
+  url: string;
+  title: string;
+  content: string;
+  type: 'page' | 'api';
 }
 
 function extractHeadings(markdown: string): string {
-  const headingRegex = /^#{1,6}\s+(.+)$/gm
-  const headings: string[] = []
-  let match
-  while ((match = headingRegex.exec(markdown)) !== null) {
-    headings.push(match[1].trim())
-  }
-  return headings.join(' ')
+  const tree = unified().use(remarkParse).parse(markdown);
+  const headings: string[] = [];
+  visit(tree, 'heading', (node: Heading) => {
+    const text = node.children
+      .filter((child): child is Text => child.type === 'text')
+      .map(child => child.value)
+      .join('');
+    if (text) headings.push(text);
+  });
+  return headings.join(' ');
 }
 
 async function scanContent(contentDir: string): Promise<SearchDocument[]> {
-  const docs: SearchDocument[] = []
+  const docs: SearchDocument[] = [];
 
   async function scan(dir: string, prefix: string[] = []) {
-    let entries
-    try { entries = await fs.readdir(dir, { withFileTypes: true }) }
-    catch { return }
-
-    for (const entry of entries) {
-      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
-      const fullPath = path.join(dir, entry.name)
+    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);
+
+        if (entry.isDirectory()) {
+          await scan(fullPath, [...prefix, entry.name]);
+          continue;
+        }
+
+        if (!entry.name.endsWith('.mdx') && !entry.name.endsWith('.md'))
+          continue;
+
+        const raw = await fs.readFile(fullPath, 'utf-8');
+        const { data: fm, content } = matter(raw);
+        const baseName = entry.name.replace(/\.(mdx|md)$/, '');
+        const slugs = baseName === 'index' ? prefix : [...prefix, baseName];
+        const url = slugs.length === 0 ? '/' : `/${slugs.join('/')}`;
 
-      if (entry.isDirectory()) {
-        await scan(fullPath, [...prefix, entry.name])
-        continue
+        docs.push({
+          id: url,
+          url,
+          title: fm.title ?? baseName,
+          content: extractHeadings(content),
+          type: 'page'
+        });
       }
-
-      if (!entry.name.endsWith('.mdx') && !entry.name.endsWith('.md')) continue
-
-      const raw = await fs.readFile(fullPath, 'utf-8')
-      const { data: fm, content } = matter(raw)
-      const baseName = entry.name.replace(/\.(mdx|md)$/, '')
-      const slugs = baseName === 'index' ? prefix : [...prefix, baseName]
-      const url = slugs.length === 0 ? '/' : '/' + slugs.join('/')
-
-      docs.push({
-        id: url,
-        url,
-        title: fm.title ?? baseName,
-        content: extractHeadings(content),
-        type: 'page',
-      })
+    } catch {
+      /* directory not readable */
     }
   }
 
-  await scan(contentDir)
-  return docs
+  await scan(contentDir);
+  return docs;
 }
 
-function buildApiDocs(): SearchDocument[] {
-  const config = loadConfig()
-  if (!config.api?.length) return []
+async function buildApiDocs(): Promise<SearchDocument[]> {
+  const config = loadConfig();
+  if (!config.api?.length) return [];
 
-  const docs: SearchDocument[] = []
-  const specs = loadApiSpecs(config.api)
+  const docs: SearchDocument[] = [];
+  const specs = await loadApiSpecs(config.api);
 
   for (const spec of specs) {
-    const specSlug = getSpecSlug(spec)
-    const paths = spec.document.paths ?? {}
+    const specSlug = getSpecSlug(spec);
+    const paths = spec.document.paths ?? {};
     for (const [, pathItem] of Object.entries(paths)) {
-      if (!pathItem) continue
+      if (!pathItem) continue;
       for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
-        const op = pathItem[method] as OpenAPIV3.OperationObject | undefined
-        if (!op?.operationId) continue
-        const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`
+        const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+        if (!op?.operationId) continue;
+        const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
         docs.push({
           id: url,
           url,
           title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
           content: op.description ?? '',
-          type: 'api',
-        })
+          type: 'api'
+        });
       }
     }
   }
 
-  return docs
+  return docs;
 }
 
 export async function generateSearchIndex(contentDir: string, outDir: string) {
   const [contentDocs, apiDocs] = await Promise.all([
     scanContent(contentDir),
-    Promise.resolve(buildApiDocs()),
-  ])
+    buildApiDocs()
+  ]);
 
-  const documents = [...contentDocs, ...apiDocs]
-  const outPath = path.join(outDir, 'search-index.json')
-  await fs.writeFile(outPath, JSON.stringify(documents))
+  const documents = [...contentDocs, ...apiDocs];
+  const outPath = path.join(outDir, 'search-index.json');
+  await fs.writeFile(outPath, JSON.stringify(documents));
 
-  return documents.length
+  return documents.length;
 }

package/src/server/entry-client.tsx

@@ -1,74 +1,86 @@
-import { hydrateRoot } from 'react-dom/client'
-import { BrowserRouter } from 'react-router-dom'
-import { PageProvider } from '@/lib/page-context'
-import { App } from './App'
-import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
-import { mdxComponents } from '@/components/mdx'
-import type { ChronicleConfig, PageTree } from '@/types'
-import type { ApiSpec } from '@/lib/openapi'
-import type { ReactNode } from 'react'
-import React from 'react'
+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, Root, TableOfContents } from '@/types';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ReactNode } from 'react';
+import { App } from './App';
 
 interface EmbeddedData {
-  config: ChronicleConfig
-  tree: PageTree
-  slug: string[]
-  frontmatter: { title: string; description?: string; order?: number }
-  filePath: string
+  config: ChronicleConfig;
+  tree: Root;
+  slug: string[];
+  frontmatter: Frontmatter;
+  relativePath: string;
 }
 
-async function hydrate() {
-  try {
-    const embedded: EmbeddedData | undefined = (window as any).__PAGE_DATA__
+const contentModules = import.meta.glob<{ default?: React.ComponentType<any>; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
 
-    let config: ChronicleConfig = { title: 'Documentation' }
-    let tree: PageTree = { name: 'root', children: [] }
-    let page: { slug: string[]; frontmatter: any; content: ReactNode } | null = null
-    let apiSpecs: ApiSpec[] = []
+async function loadMdxModule(relativePath: string): Promise<{ content: ReactNode; toc: TableOfContents }> {
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = contentModules[key];
+  if (!loader) return { content: null, toc: [] };
+  const mod = await loader();
+  const content = mod.default
+    ? React.createElement(mod.default, { components: mdxComponents })
+    : null;
+  return { content, toc: mod.toc ?? [] };
+}
 
-    if (embedded) {
-      config = embedded.config
-      tree = embedded.tree
+async function hydrate() {
+  try {
+    const embedded = (
+      window as unknown as { __PAGE_DATA__?: EmbeddedData }
+    ).__PAGE_DATA__;
 
-      // Fetch API specs if on /apis route
-      const isApiRoute = window.location.pathname.startsWith('/apis')
-      if (isApiRoute && config.api?.length) {
-        try {
-          const res = await fetch('/api/specs')
-          apiSpecs = await res.json()
-        } catch { /* will load on demand */ }
-      }
+    const config: ChronicleConfig = embedded?.config ?? {
+      title: 'Documentation'
+    };
+    const tree: Root = embedded?.tree ?? { name: 'root', children: [] };
+    const isApiPage =
+      window.location.pathname.startsWith('/apis') && !!config.api?.length;
+    const apiSpecs: ApiSpec[] = isApiPage
+      ? await fetch('/api/specs')
+          .then(r => r.json())
+          .catch(() => [])
+      : [];
 
-      const sourcePage = await getPage(embedded.slug)
-      if (sourcePage) {
-        const component = await loadPageComponent(sourcePage)
-        page = {
-          slug: embedded.slug,
-          frontmatter: embedded.frontmatter,
-          content: component ? React.createElement(component, { components: mdxComponents }) : null,
-        }
-      } else {
-        page = {
+    const page = embedded?.relativePath
+      ? {
           slug: embedded.slug,
           frontmatter: embedded.frontmatter,
-          content: null,
+          ...(await loadMdxModule(embedded.relativePath)),
         }
-      }
-    } else {
-      tree = await buildPageTree()
-    }
+      : null;
 
     hydrateRoot(
       document.getElementById('root') as HTMLElement,
       <BrowserRouter>
-        <PageProvider initialConfig={config} initialTree={tree} initialPage={page} initialApiSpecs={apiSpecs}>
-          <App />
-        </PageProvider>
-      </BrowserRouter>,
-    )
+        <ReactRouterProvider>
+          <PageProvider
+            initialConfig={config}
+            initialTree={tree}
+            initialPage={page}
+            initialApiSpecs={apiSpecs}
+            loadMdx={loadMdxModule}
+          >
+            <App />
+          </PageProvider>
+        </ReactRouterProvider>
+      </BrowserRouter>
+    );
   } catch (err) {
-    console.error('Hydration failed:', err)
+    console.error('Hydration failed:', err);
   }
 }
 
-hydrate()
+hydrate();

package/src/server/entry-server.tsx

@@ -1,35 +1,100 @@
-import { renderToString } from 'react-dom/server'
-import { StaticRouter } from 'react-router-dom'
-import { PageProvider } from '@/lib/page-context'
-import { App } from './App'
-import type { ReactNode } from 'react'
-import type { ChronicleConfig, Frontmatter, PageTree } from '@/types'
-import type { ApiSpec } from '@/lib/openapi'
-
-export interface SSRData {
-  config: ChronicleConfig
-  tree: PageTree
-  page: {
-    slug: string[]
-    frontmatter: Frontmatter
-    content: ReactNode
-  } | null
-  apiSpecs: ApiSpec[]
-}
-
-export function render(url: string, data: SSRData): string {
-  const pathname = new URL(url, 'http://localhost').pathname
-
-  return renderToString(
-    <StaticRouter location={pathname}>
-      <PageProvider
-        initialConfig={data.config}
-        initialTree={data.tree}
-        initialPage={data.page}
-        initialApiSpecs={data.apiSpecs}
-      >
-        <App />
-      </PageProvider>
-    </StaticRouter>,
-  )
-}
+import '@raystack/apsara/normalize.css';
+import '@raystack/apsara/style.css';
+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 { getPageTree, getPage, loadPageModule, extractFrontmatter, getRelativePath } from '@/lib/source';
+import { App } from './App';
+
+import clientAssets from './entry-client?assets=client';
+import serverAssets from './entry-server?assets=ssr';
+
+export default {
+  async fetch(req: Request) {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+    const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean);
+
+    const config = loadConfig();
+    const apiSpecs = config.api?.length
+      ? await loadApiSpecs(config.api).catch(() => [])
+      : [];
+
+    const [tree, page] = await Promise.all([
+      getPageTree(),
+      getPage(slug),
+    ]);
+
+    const relativePath = page ? getRelativePath(page) : null;
+    const mdxModule = relativePath ? await loadPageModule(relativePath) : null;
+
+    const pageData = page
+      ? {
+          slug,
+          frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+          content: mdxModule?.default
+            ? React.createElement(mdxModule.default, { components: mdxComponents })
+            : null,
+          toc: mdxModule?.toc ?? [],
+        }
+      : null;
+
+    const embeddedData = {
+      config,
+      tree,
+      slug,
+      frontmatter: pageData?.frontmatter ?? null,
+      relativePath,
+    };
+    const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c');
+
+    const assets = clientAssets.merge(serverAssets);
+
+    const stream = await renderToReadableStream(
+      <html lang="en">
+        <head>
+          <meta charSet="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          {assets.css.map((attr: { href: string }) => (
+            <link key={attr.href} rel="stylesheet" {...attr} />
+          ))}
+          {assets.js.map((attr: { href: string }) => (
+            <link key={attr.href} rel="modulepreload" {...attr} />
+          ))}
+          <script type="module" src={assets.entry} />
+          <script dangerouslySetInnerHTML={{ __html: `window.__PAGE_DATA__ = ${safeJson}` }} />
+        </head>
+        <body>
+          <div id="root">
+            <StaticRouter location={pathname}>
+              <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/llms.txt.ts

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+
+function getContentDir(): string {
+  return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
+}
+
+async function scanPages(): Promise<{ title: string; url: string }[]> {
+  const contentDir = getContentDir();
+  const pages: { title: string; url: string }[] = [];
+
+  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);
+
+        if (entry.isDirectory()) {
+          await scan(fullPath, [...prefix, entry.name]);
+          continue;
+        }
+
+        if (!entry.name.endsWith('.mdx') && !entry.name.endsWith('.md'))
+          continue;
+
+        const raw = await fs.readFile(fullPath, 'utf-8');
+        const { data: fm } = matter(raw);
+        const baseName = entry.name.replace(/\.(mdx|md)$/, '');
+        const slugs = baseName === 'index' ? prefix : [...prefix, baseName];
+        const url = slugs.length === 0 ? '/' : `/${slugs.join('/')}`;
+
+        pages.push({ title: fm.title ?? baseName, url });
+      }
+    } catch {
+      /* directory not readable */
+    }
+  }
+
+  await scan(contentDir);
+  return pages;
+}
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+
+  if (!config.llms?.enabled) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  const pages = await scanPages();
+  const index = pages.map(p => `- [${p.title}](${p.url})`).join('\n');
+  const body = `# ${config.title}\n\n${config.description ?? ''}\n\n${index}`;
+
+  event.res.headers.set('Content-Type', 'text/plain');
+  return body;
+});

package/src/server/routes/og.tsx

@@ -0,0 +1,75 @@
+import { defineHandler } from 'nitro';
+import React from 'react';
+import satori from 'satori';
+import { loadConfig } from '@/lib/config';
+
+let fontData: ArrayBuffer | null = null;
+
+async function loadFont(): Promise<ArrayBuffer> {
+  if (fontData) return fontData;
+
+  try {
+    const response = await fetch(
+      'https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hiA.woff2'
+    );
+    fontData = await response.arrayBuffer();
+  } catch {
+    fontData = new ArrayBuffer(0);
+  }
+
+  return fontData;
+}
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+  const title = event.url.searchParams.get('title') ?? config.title;
+  const description = event.url.searchParams.get('description') ?? '';
+  const siteName = config.title;
+
+  const font = await loadFont();
+
+  const svg = await satori(
+    <div
+      style={{
+        height: '100%',
+        width: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'center',
+        padding: '60px 80px',
+        backgroundColor: '#0a0a0a',
+        color: '#fafafa',
+      }}
+    >
+      <div style={{ fontSize: 24, color: '#888', marginBottom: 16 }}>
+        {siteName}
+      </div>
+      <div
+        style={{
+          fontSize: 56,
+          fontWeight: 700,
+          lineHeight: 1.2,
+          marginBottom: 24,
+        }}
+      >
+        {title}
+      </div>
+      {description && (
+        <div style={{ fontSize: 24, color: '#999', lineHeight: 1.4 }}>
+          {description}
+        </div>
+      )}
+    </div>,
+    {
+      width: 1200,
+      height: 630,
+      fonts: [
+        { name: 'Inter', data: font, weight: 400, style: 'normal' as const },
+      ],
+    },
+  );
+
+  event.res.headers.set('Content-Type', 'image/svg+xml');
+  event.res.headers.set('Cache-Control', 'public, max-age=86400');
+  return svg;
+});

package/src/server/routes/robots.txt.ts

@@ -0,0 +1,11 @@
+import { defineHandler } from 'nitro';
+import { loadConfig } from '@/lib/config';
+
+export default defineHandler(event => {
+  const config = loadConfig();
+  const sitemap = config.url ? `\nSitemap: ${config.url}/sitemap.xml` : '';
+  const body = `User-agent: *\nAllow: /${sitemap}`;
+
+  event.res.headers.set('Content-Type', 'text/plain');
+  return body;
+});

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

@@ -0,0 +1,40 @@
+import { defineHandler } from 'nitro';
+import { buildApiRoutes } from '@/lib/api-routes';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+import { getPages } from '@/lib/source';
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+
+  if (!config.url) {
+    event.res.headers.set('Content-Type', 'application/xml');
+    return '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"/>';
+  }
+
+  const baseUrl = config.url.replace(/\/$/, '');
+
+  const pages = await getPages();
+  const docPages = pages.map(page => {
+    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>`;
+  });
+
+  const apiPages = config.api?.length
+    ? buildApiRoutes(await loadApiSpecs(config.api)).map(
+        route => `<url><loc>${baseUrl}/apis/${route.slug.join('/')}</loc></url>`
+      )
+    : [];
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<url><loc>${baseUrl}</loc></url>
+${[...docPages, ...apiPages].join('\n')}
+</urlset>`;
+
+  event.res.headers.set('Content-Type', 'application/xml');
+  return xml;
+});