@raystack/chronicle 0.5.2 → 0.5.4

package/README.md

@@ -0,0 +1,98 @@
+# Chronicle
+
+Config-driven documentation framework built on Vite, Nitro, and Apsara UI.
+
+## Features
+
+- **Config-driven** — Single `chronicle.yaml` for all site configuration
+- **Themeable** — Built-in themes: `default` (sidebar + TOC) and `paper` (book-style)
+- **MDX** — Write docs in MDX with callouts, tabs, mermaid diagrams, and syntax highlighting
+- **API docs** — Interactive OpenAPI documentation with "Try it out" panel
+- **LLMs** — Auto-generate `/llms.txt` and `/llms-full.txt` for AI consumption
+- **CLI** — `init`, `dev`, `build`, `start`, `serve` commands
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @raystack/chronicle
+```
+
+### Initialize
+
+```bash
+chronicle init
+```
+
+Creates a `chronicle.yaml` and sample `index.mdx`.
+
+### Develop
+
+```bash
+chronicle dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+### Build for production
+
+```bash
+chronicle build
+chronicle start
+```
+
+## Contributing
+
+We welcome contributions! Here's how to get started:
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 22
+- [Bun](https://bun.sh/) >= 1.3
+
+### Running Locally
+
+1. Fork and clone the repository
+
+```bash
+git clone https://github.com/<your-username>/chronicle.git
+cd chronicle
+```
+
+2. Install dependencies
+
+```bash
+bun install
+```
+
+3. Build the CLI
+
+```bash
+bun run build:cli
+```
+
+4. Run the docs site locally
+
+```bash
+bun run dev:docs
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see the docs site.
+
+You can also run the CLI directly:
+
+```bash
+./packages/chronicle/bin/chronicle.js dev --config docs/chronicle.yaml
+```
+
+### Making Changes
+
+1. Create a branch from `main`
+2. Make your changes
+3. Test locally from the `docs/` directory
+4. Open a pull request
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/cli/index.js

@@ -254,6 +254,11 @@ var analyticsSchema = z.object({
   enabled: z.boolean().optional(),
   googleAnalytics: googleAnalyticsSchema.optional()
 });
+var telemetrySchema = z.object({
+  enabled: z.boolean().optional(),
+  serviceName: z.string().optional(),
+  port: z.number().int().min(1).max(65535).default(9090)
+});
 var chronicleConfigSchema = z.object({
   title: z.string(),
   description: z.string().optional(),
@@ -267,7 +272,8 @@ var chronicleConfigSchema = z.object({
   footer: footerSchema.optional(),
   api: z.array(apiSchema).optional(),
   llms: llmsSchema.optional(),
-  analytics: analyticsSchema.optional()
+  analytics: analyticsSchema.optional(),
+  telemetry: telemetrySchema.optional()
 });
 // src/cli/utils/config.ts
 function resolveConfigPath(configPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,6 +36,11 @@
     "@codemirror/theme-one-dark": "^6.1.3",
     "@codemirror/view": "^6.39.14",
     "@heroicons/react": "^2.2.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-prometheus": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-metrics": "^2.6.1",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
     "@raystack/apsara": "0.55.1",
     "@shikijs/rehype": "^4.0.2",
     "@vitejs/plugin-react": "^6.0.1",
@@ -44,7 +49,7 @@
     "codemirror": "^6.0.2",
     "commander": "^14.0.2",
     "fumadocs-core": "16.6.15",
-    "fumadocs-mdx": "^14.2.6",
+    "fumadocs-mdx": "14.2.6",
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "h3": "^2.0.1-rc.16",

package/src/components/mdx/link.tsx

@@ -1,10 +1,12 @@
 import { Link as ApsaraLink } from '@raystack/apsara';
-import type { ComponentProps } from 'react';
-import { Link as RouterLink } from 'react-router';
+import type { ComponentProps, MouseEvent } from 'react';
+import { useNavigate } from 'react-router';
 
 type LinkProps = ComponentProps<'a'>;
 
-export function Link({ href, children, ...props }: LinkProps) {
+export function Link({ href, children, onClick: onClickProp, ...props }: LinkProps) {
+  const navigate = useNavigate();
+
   if (!href) {
     return <span {...props}>{children}</span>;
   }
@@ -12,14 +14,6 @@ export function Link({ href, children, ...props }: LinkProps) {
   const isExternal = href.startsWith('http://') || href.startsWith('https://');
   const isAnchor = href.startsWith('#');
 
-  if (isAnchor) {
-    return (
-      <ApsaraLink href={href} {...props}>
-        {children}
-      </ApsaraLink>
-    );
-  }
-
   if (isExternal) {
     return (
       <ApsaraLink
@@ -33,9 +27,36 @@ export function Link({ href, children, ...props }: LinkProps) {
     );
   }
 
+  if (isAnchor) {
+    return (
+      <ApsaraLink href={href} {...props}>
+        {children}
+      </ApsaraLink>
+    );
+  }
+
+  const onClick = (e: MouseEvent<HTMLAnchorElement>) => {
+    if (
+      e.defaultPrevented ||
+      e.button !== 0 ||
+      e.metaKey ||
+      e.ctrlKey ||
+      e.shiftKey ||
+      e.altKey
+    ) {
+      return;
+    }
+
+    onClickProp?.(e);
+    if (e.defaultPrevented) return;
+
+    e.preventDefault();
+    navigate(href);
+  };
+
   return (
-    <RouterLink to={href} className={props.className}>
+    <ApsaraLink href={href} {...props} onClick={onClick}>
       {children}
-    </RouterLink>
+    </ApsaraLink>
   );
 }

package/src/lib/page-context.tsx

@@ -22,6 +22,7 @@ interface PageContextValue {
   config: ChronicleConfig;
   tree: Root;
   page: PageData | null;
+  errorStatus: number | null;
   apiSpecs: ApiSpec[];
 }
 
@@ -35,6 +36,7 @@ export function usePageContext(): PageContextValue {
       config: { title: 'Documentation' },
       tree: { name: 'root', children: [] } as Root,
       page: null,
+      errorStatus: null,
       apiSpecs: []
     };
   }
@@ -50,6 +52,16 @@ interface PageProviderProps {
   children: ReactNode;
 }
 
+function isApisRoute(pathname: string): boolean {
+  return pathname === '/apis' || pathname.startsWith('/apis/');
+}
+
+function getInitialErrorStatus(page: PageData | null, pathname: string): number | null {
+  if (page) return null;
+  if (pathname === '/' || isApisRoute(pathname)) return null;
+  return 404;
+}
+
 export function PageProvider({
   initialConfig,
   initialTree,
@@ -61,6 +73,7 @@ export function PageProvider({
   const { pathname } = useLocation();
   const [tree] = useState<Root>(initialTree);
   const [page, setPage] = useState<PageData | null>(initialPage);
+  const [errorStatus, setErrorStatus] = useState<number | null>(getInitialErrorStatus(initialPage, pathname));
   const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
   const [currentPath, setCurrentPath] = useState(pathname);
 
@@ -70,7 +83,7 @@ export function PageProvider({
 
     const cancelled = { current: false };
 
-    if (pathname.startsWith('/apis')) {
+    if (isApisRoute(pathname)) {
       if (apiSpecs.length === 0) {
         fetch('/api/specs')
           .then(res => res.json())
@@ -86,24 +99,39 @@ export function PageProvider({
       ? []
       : pathname.slice(1).split('/').filter(Boolean);
 
-    const apiPath = slug.length === 0 ? '/api/page/' : `/api/page/${slug.join('/')}`;
+    const apiPath = slug.length === 0 ? '/api/page' : `/api/page?slug=${slug.join(',')}`;
 
     fetch(apiPath)
-      .then(res => res.json())
-      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string }) => {
-        if (cancelled.current) return;
+      .then(res => {
+        if (!res.ok) {
+          if (!cancelled.current) {
+            setPage(null);
+            setErrorStatus(res.status);
+          }
+          return;
+        }
+        return res.json();
+      })
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string } | undefined) => {
+        if (cancelled.current || !data) return;
         const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
         if (cancelled.current) return;
+        setErrorStatus(null);
         setPage({ slug, frontmatter: data.frontmatter, content, toc });
       })
-      .catch(() => {});
+      .catch(() => {
+        if (!cancelled.current) {
+          setPage(null);
+          setErrorStatus(500);
+        }
+      });
 
     return () => { cancelled.current = true; };
   }, [pathname]);
 
   return (
     <PageContext.Provider
-      value={{ config: initialConfig, tree, page, apiSpecs }}
+      value={{ config: initialConfig, tree, page, errorStatus, apiSpecs }}
     >
       {children}
     </PageContext.Provider>

package/src/pages/DocsPage.tsx

@@ -1,5 +1,6 @@
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
+import { NotFound } from '@/pages/NotFound';
 import { getTheme } from '@/themes/registry';
 
 interface DocsPageProps {
@@ -7,8 +8,10 @@ interface DocsPageProps {
 }
 
 export function DocsPage({ slug }: DocsPageProps) {
-  const { config, tree, page } = usePageContext();
+  const { config, tree, page, errorStatus } = usePageContext();
 
+  if (errorStatus === 404) return <NotFound />;
+  if (errorStatus) return <NotFound />;
   if (!page) return null;
 
   const { Page } = getTheme(config.theme?.name);
@@ -30,7 +33,7 @@ export function DocsPage({ slug }: DocsPageProps) {
       />
       <Page
         page={{
-          slug,
+          slug: page.slug,
           frontmatter: page.frontmatter,
           content: page.content,
           toc: page.toc

package/src/pages/NotFound.module.css

@@ -0,0 +1,3 @@
+.emptyState {
+  justify-content: center;
+}

package/src/pages/NotFound.tsx

@@ -1,17 +1,12 @@
-import { Flex, Headline, Text } from '@raystack/apsara';
+import { EmptyState } from '@raystack/apsara';
+import styles from './NotFound.module.css';
 
 export function NotFound() {
   return (
-    <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>
+    <EmptyState
+      heading="404"
+      subHeading="Page not found"
+      classNames={{ container: styles.emptyState }}
+    />
   );
 }

package/src/server/api/{page/[...slug].ts → page.ts}

@@ -2,8 +2,8 @@ import { defineHandler, HTTPError } from 'nitro';
 import { getPage, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
 
 export default defineHandler(async event => {
-  const slugParam = event.context.params?.slug ?? '';
-  const slug = slugParam ? slugParam.split('/') : [];
+  const slugParam = event.url.searchParams.get('slug') ?? '';
+  const slug = slugParam ? slugParam.split(',').filter(Boolean) : [];
   const page = await getPage(slug);
 
   if (!page) {

package/src/server/entry-server.tsx

@@ -9,6 +9,7 @@ import { loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
 import { getPageTree, getPage, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { useNitroApp } from 'nitro/app';
 import { App } from './App';
 
 import clientAssets from './entry-client?assets=client';
@@ -57,6 +58,7 @@ export default {
 
     const assets = clientAssets.merge(serverAssets);
 
+    const renderStart = performance.now();
     const stream = await renderToReadableStream(
       <html lang="en">
         <head>
@@ -91,9 +93,13 @@ export default {
       </html>,
     );
 
+    const renderDuration = performance.now() - renderStart;
+
     const isApiRoute = pathname.startsWith('/apis');
     const status = !page && !isApiRoute && slug.length > 0 ? 404 : 200;
 
+    useNitroApp().hooks.callHook('chronicle:ssr-rendered', pathname, status, renderDuration);
+
     return new Response(stream, {
       status,
       headers: { 'Content-Type': 'text/html;charset=utf-8' },

package/src/server/plugins/telemetry.ts

@@ -0,0 +1,61 @@
+import type { Counter, Histogram } from '@opentelemetry/api'
+import { MeterProvider } from '@opentelemetry/sdk-metrics'
+import { PrometheusExporter } from '@opentelemetry/exporter-prometheus'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
+import type { H3Event } from 'h3'
+import { definePlugin } from 'nitro'
+import { loadConfig } from '@/lib/config'
+
+declare module 'nitro/types' {
+  interface NitroRuntimeHooks {
+    'chronicle:ssr-rendered': (route: string, status: number, durationMs: number) => void
+  }
+}
+
+export default definePlugin((nitroApp) => {
+  const config = loadConfig()
+  if (!config.telemetry?.enabled) return
+
+  const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: config.telemetry?.serviceName ?? 'chronicle',
+  })
+
+  const port = config.telemetry?.port ?? 9090
+  const exporter = new PrometheusExporter({ port })
+  const provider = new MeterProvider({ resource, readers: [exporter] })
+  const meter = provider.getMeter('chronicle')
+
+  const requestCounter: Counter = meter.createCounter('http_server_request_total', {
+    description: 'Total HTTP requests',
+  })
+  const requestDuration: Histogram = meter.createHistogram('http_server_request_duration_ms', {
+    description: 'HTTP request duration in ms',
+  })
+  const ssrRenderDuration: Histogram = meter.createHistogram('http_server_ssr_render_duration_ms', {
+    description: 'SSR render duration in ms',
+  })
+
+  nitroApp.hooks.hook('close', async () => {
+    await provider.shutdown()
+    await exporter.shutdown()
+  })
+
+  nitroApp.hooks.hook('chronicle:ssr-rendered', (route, status, durationMs) => {
+    ssrRenderDuration.record(durationMs, { route, status })
+  })
+
+  nitroApp.hooks.hook('request', (event) => {
+    (event as H3Event).context._requestStart = performance.now()
+  })
+
+  nitroApp.hooks.hook('response', (res, event) => {
+    const start = (event as H3Event).context._requestStart as number | undefined
+    if (start === undefined) return
+    const duration = performance.now() - start
+    const method = event.req.method
+    const route = new URL(event.req.url).pathname
+    requestCounter.add(1, { method, route, status: res.status })
+    requestDuration.record(duration, { method, route, status: res.status })
+  })
+})

package/src/server/routes/[...slug].md.ts

@@ -0,0 +1,45 @@
+import fs from 'node:fs/promises';
+import matter from 'gray-matter';
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { getPage, getOriginalPath } from '@/lib/source';
+import { safePath } from '@/server/utils/safe-path';
+
+export default defineHandler(async event => {
+  const pathname = event.path || event.req.url?.split('?')[0] || '';
+  if (!pathname.endsWith('.md')) return;
+
+  const config = loadConfig();
+  if (!config.llms?.enabled) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  const stripped = pathname.replace(/\.md$/, '');
+  const parts = stripped === '/index' || stripped === '/'
+    ? []
+    : stripped.slice(1).split('/').filter(Boolean);
+  const page = await getPage(parts);
+
+  if (!page) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  const originalPath = getOriginalPath(page);
+  if (!originalPath) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  const contentDir = __CHRONICLE_CONTENT_DIR__;
+  const filePath = safePath(contentDir, '/' + originalPath);
+  if (!filePath) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  const raw = await fs.readFile(filePath, 'utf-8').catch(() => null);
+  if (!raw) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  event.res.headers.set('Content-Type', 'text/markdown; charset=utf-8');
+  return matter(raw).content;
+});

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

@@ -12,7 +12,8 @@ export default defineHandler(async event => {
   const pages = await getPages();
   const index = pages.map(p => {
     const fm = extractFrontmatter(p);
-    return `- [${fm.title}](${p.url})`;
+    const mdUrl = p.url === '/' ? '/index.md' : `${p.url}.md`;
+    return `- [${fm.title}](${mdUrl})`;
   }).join('\n');
   const body = `# ${config.title}\n\n${config.description ?? ''}\n\n${index}`;
 

package/src/types/config.ts

@@ -67,6 +67,12 @@ const analyticsSchema = z.object({
   googleAnalytics: googleAnalyticsSchema.optional(),
 })
 
+const telemetrySchema = z.object({
+  enabled: z.boolean().optional(),
+  serviceName: z.string().optional(),
+  port: z.number().int().min(1).max(65535).default(9090),
+})
+
 export const chronicleConfigSchema = z.object({
   title: z.string(),
   description: z.string().optional(),
@@ -81,6 +87,7 @@ export const chronicleConfigSchema = z.object({
   api: z.array(apiSchema).optional(),
   llms: llmsSchema.optional(),
   analytics: analyticsSchema.optional(),
+  telemetry: telemetrySchema.optional(),
 })
 
 export type ChronicleConfig = z.infer<typeof chronicleConfigSchema>
@@ -97,3 +104,4 @@ export type FooterConfig = z.infer<typeof footerSchema>
 export type LlmsConfig = z.infer<typeof llmsSchema>
 export type AnalyticsConfig = z.infer<typeof analyticsSchema>
 export type GoogleAnalyticsConfig = z.infer<typeof googleAnalyticsSchema>
+export type TelemetryConfig = z.infer<typeof telemetrySchema>