@raystack/chronicle 0.5.1 → 0.5.3

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,10 @@ var analyticsSchema = z.object({
   enabled: z.boolean().optional(),
   googleAnalytics: googleAnalyticsSchema.optional()
 });
+var telemetrySchema = z.object({
+  enabled: z.boolean().optional(),
+  serviceName: z.string().optional()
+});
 var chronicleConfigSchema = z.object({
   title: z.string(),
   description: z.string().optional(),
@@ -267,7 +271,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) {
@@ -365,7 +370,7 @@ var buildCommand = new Command("build").description("Build for production").opti
 // src/cli/commands/dev.ts
 import chalk3 from "chalk";
 import { Command as Command2 } from "commander";
-var devCommand = new Command2("dev").description("Start development server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").option("--config <path>", "Path to chronicle.yaml").action(async (options) => {
+var devCommand = new Command2("dev").description("Start development server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").option("--config <path>", "Path to chronicle.yaml").option("--host <host>", "Host address", "localhost").action(async (options) => {
   const { contentDir, configPath } = await loadCLIConfig(options.config, { content: options.content });
   const port = parseInt(options.port, 10);
   await linkContent(contentDir);
@@ -375,7 +380,7 @@ var devCommand = new Command2("dev").description("Start development server").opt
   const config2 = await createViteConfig2({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
   const server = await createServer({
     ...config2,
-    server: { ...config2.server, port }
+    server: { ...config2.server, port, host: options.host }
   });
   await server.listen();
   server.printUrls();
@@ -450,7 +455,7 @@ Run`, chalk4.cyan("chronicle dev"), "to start development server");
 // src/cli/commands/serve.ts
 import chalk5 from "chalk";
 import { Command as Command4 } from "commander";
-var serveCommand = new Command4("serve").description("Build and start production server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").option("--config <path>", "Path to chronicle.yaml").option("--preset <preset>", "Deploy preset (vercel, cloudflare, node-server)").action(async (options) => {
+var serveCommand = new Command4("serve").description("Build and start production server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").option("--config <path>", "Path to chronicle.yaml").option("--host <host>", "Host address", "localhost").option("--preset <preset>", "Deploy preset (vercel, cloudflare, node-server)").action(async (options) => {
   const { contentDir, configPath, preset } = await loadCLIConfig(options.config, {
     content: options.content,
     preset: options.preset
@@ -471,7 +476,7 @@ var serveCommand = new Command4("serve").description("Build and start production
   console.log(chalk5.cyan("Starting production server..."));
   const server = await preview({
     ...config2,
-    preview: { port }
+    preview: { port, host: options.host }
   });
   server.printUrls();
 });
@@ -479,7 +484,7 @@ var serveCommand = new Command4("serve").description("Build and start production
 // src/cli/commands/start.ts
 import chalk6 from "chalk";
 import { Command as Command5 } from "commander";
-var startCommand = new Command5("start").description("Start production server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").action(async (options) => {
+var startCommand = new Command5("start").description("Start production server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").option("--host <host>", "Host address", "localhost").action(async (options) => {
   const { contentDir, configPath } = await loadCLIConfig(undefined, { content: options.content });
   const port = parseInt(options.port, 10);
   await linkContent(contentDir);
@@ -489,7 +494,7 @@ var startCommand = new Command5("start").description("Start production server").
   const config2 = await createViteConfig2({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
   const server = await preview({
     ...config2,
-    preview: { port }
+    preview: { port, host: options.host }
   });
   server.printUrls();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",

package/src/cli/commands/dev.ts

@@ -9,6 +9,7 @@ export const devCommand = new Command('dev')
   .option('-p, --port <port>', 'Port number', '3000')
   .option('--content <path>', 'Content directory')
   .option('--config <path>', 'Path to chronicle.yaml')
+  .option('--host <host>', 'Host address', 'localhost')
   .action(async options => {
     const { contentDir, configPath } = await loadCLIConfig(options.config, { content: options.content });
     const port = parseInt(options.port, 10);
@@ -23,7 +24,7 @@ export const devCommand = new Command('dev')
     const config = await createViteConfig({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
     const server = await createServer({
       ...config,
-      server: { ...config.server, port }
+      server: { ...config.server, port, host: options.host }
     });
 
     await server.listen();

package/src/cli/commands/serve.ts

@@ -9,6 +9,7 @@ export const serveCommand = new Command('serve')
   .option('-p, --port <port>', 'Port number', '3000')
   .option('--content <path>', 'Content directory')
   .option('--config <path>', 'Path to chronicle.yaml')
+  .option('--host <host>', 'Host address', 'localhost')
   .option(
     '--preset <preset>',
     'Deploy preset (vercel, cloudflare, node-server)'
@@ -38,7 +39,7 @@ export const serveCommand = new Command('serve')
     console.log(chalk.cyan('Starting production server...'));
     const server = await preview({
       ...config,
-      preview: { port }
+      preview: { port, host: options.host }
     });
 
     server.printUrls();

package/src/cli/commands/start.ts

@@ -8,6 +8,7 @@ export const startCommand = new Command('start')
   .description('Start production server')
   .option('-p, --port <port>', 'Port number', '3000')
   .option('--content <path>', 'Content directory')
+  .option('--host <host>', 'Host address', 'localhost')
   .action(async options => {
     const { contentDir, configPath } = await loadCLIConfig(undefined, { content: options.content });
     const port = parseInt(options.port, 10);
@@ -21,7 +22,7 @@ export const startCommand = new Command('start')
     const config = await createViteConfig({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
     const server = await preview({
       ...config,
-      preview: { port }
+      preview: { port, host: options.host }
     });
 
     server.printUrls();

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/pages/DocsPage.tsx

@@ -30,7 +30,7 @@ export function DocsPage({ slug }: DocsPageProps) {
       />
       <Page
         page={{
-          slug,
+          slug: page.slug,
           frontmatter: page.frontmatter,
           content: page.content,
           toc: page.toc

package/src/server/api/metrics.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { defineHandler } from 'nitro'
+import { getExporter } from '../telemetry'
+
+export default defineHandler(async () => {
+  const exporter = getExporter()
+  if (!exporter) {
+    return new Response('Telemetry not enabled', { status: 404 })
+  }
+
+  const metricsString = await new Promise<string>((resolve) => {
+    const mockRes = {
+      setHeader: () => mockRes,
+      end: (data: string) => resolve(data),
+    } as unknown as ServerResponse
+
+    exporter.getMetricsRequestHandler({} as unknown as IncomingMessage, mockRes)
+  })
+
+  return new Response(metricsString, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  })
+})

package/src/server/api/page/index.ts

@@ -0,0 +1 @@
+export { default } from './[...slug]';

package/src/server/entry-server.tsx

@@ -10,6 +10,7 @@ import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
 import { getPageTree, getPage, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
 import { App } from './App';
+import { recordSSRRender } from './telemetry';
 
 import clientAssets from './entry-client?assets=client';
 import serverAssets from './entry-server?assets=ssr';
@@ -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;
 
+    recordSSRRender(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,21 @@
+import { definePlugin } from 'nitro'
+import { loadConfig } from '@/lib/config'
+import { initTelemetry, recordRequest } from '../telemetry'
+
+export default definePlugin((nitroApp) => {
+  const config = loadConfig()
+  if (!config.telemetry?.enabled) return
+
+  initTelemetry(config)
+
+  nitroApp.hooks.hook('request', (event) => {
+    if (event.path === '/api/metrics') return
+    event.context._requestStart = performance.now()
+  })
+
+  nitroApp.hooks.hook('response', (res, event) => {
+    if (!event.context._requestStart) return
+    const duration = performance.now() - event.context._requestStart
+    recordRequest(event.method, event.path, res.status, duration)
+  })
+})

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/server/telemetry.ts

@@ -0,0 +1,49 @@
+import type { Counter, Histogram } from '@opentelemetry/api'
+import sdkMetrics from '@opentelemetry/sdk-metrics'
+import prometheusExporter from '@opentelemetry/exporter-prometheus'
+import resources from '@opentelemetry/resources'
+import semconv from '@opentelemetry/semantic-conventions'
+import type { ChronicleConfig } from '@/types/config'
+
+const { MeterProvider } = sdkMetrics
+const { PrometheusExporter } = prometheusExporter
+const { resourceFromAttributes } = resources
+const { ATTR_SERVICE_NAME } = semconv
+
+let exporter: PrometheusExporter
+let requestCounter: Counter
+let requestDuration: Histogram
+let ssrRenderDuration: Histogram
+
+export function initTelemetry(config: ChronicleConfig) {
+  const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: config.telemetry?.serviceName ?? 'chronicle',
+  })
+
+  exporter = new PrometheusExporter({ preventServerStart: true })
+  const provider = new MeterProvider({ resource, readers: [exporter] })
+  const meter = provider.getMeter('chronicle')
+
+  requestCounter = meter.createCounter('http_server_request_total', {
+    description: 'Total HTTP requests',
+  })
+  requestDuration = meter.createHistogram('http_server_request_duration_ms', {
+    description: 'HTTP request duration in ms',
+  })
+  ssrRenderDuration = meter.createHistogram('http_server_ssr_render_duration_ms', {
+    description: 'SSR render duration in ms',
+  })
+}
+
+export function getExporter() {
+  return exporter
+}
+
+export function recordRequest(method: string, route: string, status: number, durationMs: number) {
+  requestCounter?.add(1, { method, route, status })
+  requestDuration?.record(durationMs, { method, route, status })
+}
+
+export function recordSSRRender(route: string, status: number, durationMs: number) {
+  ssrRenderDuration?.record(durationMs, { route, status })
+}

package/src/types/config.ts

@@ -67,6 +67,11 @@ const analyticsSchema = z.object({
   googleAnalytics: googleAnalyticsSchema.optional(),
 })
 
+const telemetrySchema = z.object({
+  enabled: z.boolean().optional(),
+  serviceName: z.string().optional(),
+})
+
 export const chronicleConfigSchema = z.object({
   title: z.string(),
   description: z.string().optional(),
@@ -81,6 +86,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 +103,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>