@raystack/chronicle 0.1.0-canary.1f5227c

package/src/server/handlers/search.ts

@@ -0,0 +1,140 @@
+import fs from 'fs/promises'
+import path from 'path'
+import matter from 'gray-matter'
+import MiniSearch from 'minisearch'
+import type { OpenAPIV3 } from 'openapi-types'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs, type ApiSpec } from '@/lib/openapi'
+import { getSpecSlug } from '@/lib/api-routes'
+
+interface SearchDocument {
+  id: string
+  url: string
+  title: string
+  content: string
+  type: 'page' | 'api'
+}
+
+let searchIndex: MiniSearch<SearchDocument> | null = null
+
+function getContentDir(): string {
+  return process.env.CHRONICLE_CONTENT_DIR || path.join(process.cwd(), 'content')
+}
+
+async function scanContent(): Promise<SearchDocument[]> {
+  const contentDir = getContentDir()
+  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)
+
+      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('/')
+
+      docs.push({
+        id: url,
+        url,
+        title: fm.title ?? baseName,
+        content: content.slice(0, 5000),
+        type: 'page',
+      })
+    }
+  }
+
+  await scan(contentDir)
+  return docs
+}
+
+function buildApiDocs(): SearchDocument[] {
+  const config = loadConfig()
+  if (!config.api?.length) return []
+
+  const docs: SearchDocument[] = []
+  const specs = loadApiSpecs(config.api)
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      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)}`
+        docs.push({
+          id: url,
+          url,
+          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
+          content: op.description ?? '',
+          type: 'api',
+        })
+      }
+    }
+  }
+
+  return docs
+}
+
+async function getIndex(): Promise<MiniSearch<SearchDocument>> {
+  if (searchIndex) return searchIndex
+
+  const [contentDocs, apiDocs] = await Promise.all([
+    scanContent(),
+    Promise.resolve(buildApiDocs()),
+  ])
+
+  searchIndex = new MiniSearch<SearchDocument>({
+    fields: ['title', 'content'],
+    storeFields: ['url', 'title', 'type'],
+    searchOptions: {
+      boost: { title: 2 },
+      fuzzy: 0.2,
+      prefix: true,
+    },
+  })
+
+  searchIndex.addAll([...contentDocs, ...apiDocs])
+  return searchIndex
+}
+
+export async function handleSearch(req: Request): Promise<Response> {
+  const url = new URL(req.url)
+  const query = url.searchParams.get('query') ?? ''
+  const index = await getIndex()
+
+  if (!query) {
+    const contentDocs = await scanContent()
+    const suggestions = contentDocs.slice(0, 8).map((d) => ({
+      id: d.id,
+      url: d.url,
+      type: d.type,
+      content: d.title,
+    }))
+    return Response.json(suggestions)
+  }
+
+  const results = index.search(query).map((r) => ({
+    id: r.id,
+    url: r.url,
+    type: r.type,
+    content: r.title,
+  }))
+
+  return Response.json(results)
+}

package/src/server/handlers/sitemap.ts

@@ -0,0 +1,39 @@
+import { loadConfig } from '@/lib/config'
+import { getPages } from '@/lib/source'
+import { loadApiSpecs } from '@/lib/openapi'
+import { buildApiRoutes } from '@/lib/api-routes'
+
+export async function handleSitemap(): Promise<Response> {
+  const config = loadConfig()
+  if (!config.url) {
+    return new Response('<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"/>', {
+      headers: { 'Content-Type': 'application/xml' },
+    })
+  }
+
+  const baseUrl = config.url.replace(/\/$/, '')
+
+  const pages = await getPages()
+  const docPages = pages.map((page) => {
+    const lastmod = page.frontmatter.lastModified
+      ? `<lastmod>${new Date(page.frontmatter.lastModified).toISOString()}</lastmod>`
+      : ''
+    return `<url><loc>${baseUrl}/${page.slugs.join('/')}</loc>${lastmod}</url>`
+  })
+
+  const apiPages = config.api?.length
+    ? buildApiRoutes(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>`
+
+  return new Response(xml, {
+    headers: { 'Content-Type': 'application/xml' },
+  })
+}

package/src/server/handlers/specs.ts

@@ -0,0 +1,9 @@
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+
+export function handleSpecs(): Response {
+  const config = loadConfig()
+  const specs = config.api?.length ? loadApiSpecs(config.api) : []
+
+  return Response.json(specs)
+}

package/src/server/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!--head-outlet-->
+  </head>
+  <body>
+    <div id="root"><!--ssr-outlet--></div>
+    <script type="module" src="/src/server/entry-client.tsx"></script>
+  </body>
+</html>

package/src/server/prod.ts

@@ -0,0 +1,18 @@
+import path from 'path'
+import chalk from 'chalk'
+
+export interface ProdServerOptions {
+  port: number
+  root: string
+  distDir: string
+}
+
+export async function startProdServer(options: ProdServerOptions) {
+  const { port, distDir } = options
+
+  const serverEntry = path.resolve(distDir, 'server/entry-prod.js')
+  const { startServer } = await import(serverEntry)
+
+  console.log(chalk.cyan('Starting production server...'))
+  return startServer({ port, distDir })
+}

package/src/server/router.ts

@@ -0,0 +1,42 @@
+import { handleHealth } from './handlers/health'
+import { handleSearch } from './handlers/search'
+import { handleApisProxy } from './handlers/apis-proxy'
+import { handleOg } from './handlers/og'
+import { handleLlms } from './handlers/llms'
+import { handleSitemap } from './handlers/sitemap'
+import { handleRobots } from './handlers/robots'
+import { handleSpecs } from './handlers/specs'
+
+export type RouteHandler = (req: Request) => Response | Promise<Response>
+
+interface Route {
+  pattern: URLPattern
+  handler: RouteHandler
+}
+
+const routes: Route[] = []
+
+function addRoute(path: string, handler: RouteHandler) {
+  routes.push({
+    pattern: new URLPattern({ pathname: path }),
+    handler,
+  })
+}
+
+addRoute('/api/health', handleHealth)
+addRoute('/api/search', handleSearch)
+addRoute('/api/apis-proxy', handleApisProxy)
+addRoute('/api/specs', handleSpecs)
+addRoute('/og', handleOg)
+addRoute('/llms.txt', handleLlms)
+addRoute('/sitemap.xml', handleSitemap)
+addRoute('/robots.txt', handleRobots)
+
+export function matchRoute(url: string): RouteHandler | null {
+  for (const route of routes) {
+    if (route.pattern.test(url)) {
+      return route.handler
+    }
+  }
+  return null
+}

package/src/server/vite-config.ts

@@ -0,0 +1,71 @@
+import path from 'path'
+import { type InlineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import mdx from '@mdx-js/rollup'
+import remarkDirective from 'remark-directive'
+import remarkGfm from 'remark-gfm'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
+import rehypeShiki from '@shikijs/rehype'
+
+export interface ViteConfigOptions {
+  root: string
+  contentDir: string
+  isDev?: boolean
+}
+
+export async function createViteConfig(options: ViteConfigOptions): Promise<InlineConfig> {
+  const { root, contentDir, isDev = false } = options
+
+  return {
+    root,
+    configFile: false,
+    resolve: {
+      alias: {
+        '@': path.resolve(root, 'src'),
+        '@content': contentDir,
+      },
+      dedupe: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+    },
+    server: {
+      fs: {
+        allow: [root, contentDir],
+      },
+    },
+    plugins: [
+      mdx({
+        remarkPlugins: [
+          remarkFrontmatter,
+          remarkMdxFrontmatter,
+          remarkGfm,
+          remarkDirective,
+        ],
+        rehypePlugins: [
+          [rehypeShiki, { themes: { light: 'github-light', dark: 'github-dark' } }],
+        ],
+        mdExtensions: ['.md'],
+        mdxExtensions: ['.mdx'],
+      }),
+      react(),
+    ],
+    define: {
+      'process.env.CHRONICLE_CONTENT_DIR': JSON.stringify(contentDir),
+      'process.env.CHRONICLE_PROJECT_ROOT': JSON.stringify(root),
+    },
+    css: {
+      modules: {
+        localsConvention: 'camelCase',
+      },
+    },
+    ssr: {
+      noExternal: ['@raystack/apsara'],
+    },
+    build: {
+      rolldownOptions: {
+        input: isDev ? undefined : {
+          client: path.resolve(root, 'src/server/index.html'),
+        },
+      },
+    },
+  }
+}

package/src/themes/default/Layout.module.css

@@ -0,0 +1,81 @@
+.layout {
+  min-height: 100vh;
+}
+
+.header {
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
+}
+
+.search {
+  margin-left: var(--rs-space-5);
+}
+
+.body {
+  flex: 1;
+}
+
+.sidebar {
+  width: 260px;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+}
+
+.content {
+  flex: 1;
+  padding: var(--rs-space-9);
+}
+
+.sidebarList {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.separator {
+  height: 1px;
+  background: var(--rs-color-border-base-primary);
+  margin: var(--rs-space-3) 0;
+}
+
+.folder {
+  margin-bottom: var(--rs-space-3);
+}
+
+.folderLabel {
+  font-weight: 500;
+  font-size: 0.875rem;
+  color: var(--rs-color-text-base-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.folder > .sidebarList {
+  margin-top: var(--rs-space-2);
+  padding-left: var(--rs-space-4);
+}
+
+.navButton {
+  display: flex;
+  align-items: center;
+  height: 32px;
+  padding: 0 var(--rs-space-4);
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  color: var(--rs-color-foreground-base-primary);
+  text-decoration: none;
+}
+
+.navButton:hover {
+  background: var(--rs-color-background-base-primary-hover);
+}
+
+.groupItems {
+  padding-left: var(--rs-space-4);
+}
+
+.page {
+  padding: var(--rs-space-2) 0;
+}

package/src/themes/default/Layout.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { useMemo, useEffect, useRef } from "react";
+import { useLocation, Link } from "react-router-dom";
+import { cx } from "class-variance-authority";
+import { Flex, Navbar, Headline, Sidebar, Button } from "@raystack/apsara";
+import { RectangleStackIcon } from "@heroicons/react/24/outline";
+import { ClientThemeSwitcher } from "@/components/ui/client-theme-switcher";
+import { Search } from "@/components/ui/search";
+import { Footer } from "@/components/ui/footer";
+import { MethodBadge } from "@/components/api/method-badge";
+import type { ThemeLayoutProps, PageTreeItem } from "@/types";
+import styles from "./Layout.module.css";
+
+const iconMap: Record<string, React.ReactNode> = {
+  "rectangle-stack": <RectangleStackIcon width={16} height={16} />,
+  "method-get": <MethodBadge method="GET" size="micro" />,
+  "method-post": <MethodBadge method="POST" size="micro" />,
+  "method-put": <MethodBadge method="PUT" size="micro" />,
+  "method-delete": <MethodBadge method="DELETE" size="micro" />,
+  "method-patch": <MethodBadge method="PATCH" size="micro" />,
+};
+
+let savedScrollTop = 0;
+
+export function Layout({ children, config, tree, classNames }: ThemeLayoutProps) {
+  const { pathname } = useLocation();
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const onScroll = () => { savedScrollTop = el.scrollTop; };
+    el.addEventListener('scroll', onScroll);
+    return () => el.removeEventListener('scroll', onScroll);
+  }, []);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (el) requestAnimationFrame(() => { el.scrollTop = savedScrollTop; });
+  }, [pathname]);
+
+  return (
+    <Flex direction="column" className={cx(styles.layout, classNames?.layout)}>
+      <Navbar className={styles.header}>
+        <Navbar.Start>
+          <Link to="/" style={{ textDecoration: 'none', color: 'inherit' }}>
+            <Headline size="small" weight="medium" as="h1">
+              {config.title}
+            </Headline>
+          </Link>
+        </Navbar.Start>
+        <Navbar.End>
+          <Flex gap="medium" align="center" className={styles.navActions}>
+            {config.api?.map((api) => (
+              <Link key={api.name} to={api.basePath} className={styles.navButton}>
+                {api.name} API
+              </Link>
+            ))}
+            {config.navigation?.links?.map((link) => (
+              <Link key={link.href} to={link.href}>
+                {link.label}
+              </Link>
+            ))}
+            {config.search?.enabled && <Search />}
+          </Flex>
+          <ClientThemeSwitcher size={16} />
+        </Navbar.End>
+      </Navbar>
+      <Flex className={cx(styles.body, classNames?.body)}>
+        <Sidebar defaultOpen collapsible={false} className={cx(styles.sidebar, classNames?.sidebar)}>
+          <Sidebar.Main ref={scrollRef}>
+            {tree.children.map((item) => (
+              <SidebarNode
+                key={item.url ?? item.name}
+                item={item}
+                pathname={pathname}
+              />
+            ))}
+          </Sidebar.Main>
+        </Sidebar>
+        <main className={cx(styles.content, classNames?.content)}>{children}</main>
+      </Flex>
+      <Footer config={config.footer} />
+    </Flex>
+  );
+}
+
+function SidebarNode({
+  item,
+  pathname,
+}: {
+  item: PageTreeItem;
+  pathname: string;
+}) {
+  if (item.type === "separator") {
+    return null;
+  }
+
+  if (item.type === "folder" && item.children) {
+    return (
+      <Sidebar.Group
+        label={item.name}
+        leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+        classNames={{ items: styles.groupItems }}
+      >
+        {item.children.map((child) => (
+          <SidebarNode
+            key={child.url ?? child.name}
+            item={child}
+            pathname={pathname}
+          />
+        ))}
+      </Sidebar.Group>
+    );
+  }
+
+  const isActive = pathname === item.url;
+  const href = item.url ?? "#";
+  const link = useMemo(() => <Link to={href} />, [href]);
+
+  return (
+    <Sidebar.Item
+      href={href}
+      active={isActive}
+      leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+      as={link}
+    >
+      {item.name}
+    </Sidebar.Item>
+  );
+}

package/src/themes/default/Page.module.css

@@ -0,0 +1,102 @@
+.page {
+  gap: var(--rs-space-9);
+}
+
+.article {
+  flex: 1;
+  min-width: 0;
+  max-width: 768px;
+}
+
+.content {
+  line-height: 1.7;
+}
+
+.content h1,
+.content h2,
+.content h3,
+.content h4,
+.content h5,
+.content h6 {
+  margin-top: var(--rs-space-8);
+  margin-bottom: var(--rs-space-5);
+  line-height: 1.4;
+}
+
+.content ul,
+.content ol {
+  padding-left: var(--rs-space-5);
+  margin-bottom: var(--rs-space-5);
+}
+
+.content li {
+  font-size: var(--rs-font-size-regular);
+  margin: var(--rs-space-2) 0;
+}
+
+.content [role="tablist"] {
+  margin-bottom: var(--rs-space-3);
+}
+
+.content :global(pre code span) {
+  color: var(--shiki-light);
+}
+
+:global([data-theme="dark"]) .content :global(pre code span) {
+  color: var(--shiki-dark);
+}
+
+:global([data-theme="dark"]) .content :global(pre) {
+  background-color: var(--shiki-dark-bg, #24292e);
+}
+
+.content img {
+  max-width: 100%;
+  height: auto;
+}
+
+.content table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  margin-bottom: var(--rs-space-5);
+}
+
+.content details {
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  margin: var(--rs-space-5) 0;
+  overflow: hidden;
+}
+
+.content details summary {
+  padding: var(--rs-space-4) var(--rs-space-5);
+  cursor: pointer;
+  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);
+}
+
+.content details summary::-webkit-details-marker {
+  display: none;
+}
+
+.content details summary::before {
+  content: '▶';
+  font-size: 10px;
+  transition: transform 0.2s ease;
+  color: var(--rs-color-text-base-secondary);
+}
+
+.content details[open] > summary::before {
+  transform: rotate(90deg);
+}
+
+.content details > :not(summary) {
+  padding: var(--rs-space-4) var(--rs-space-5);
+}

package/src/themes/default/Page.tsx

@@ -0,0 +1,21 @@
+'use client'
+
+import { Flex } from '@raystack/apsara'
+import type { ThemePageProps } from '@/types'
+import { Breadcrumbs } from '@/components/ui/breadcrumbs'
+import { Toc } from './Toc'
+import styles from './Page.module.css'
+
+export function Page({ page, tree }: ThemePageProps) {
+  return (
+    <Flex className={styles.page}>
+      <article className={styles.article}>
+        <Breadcrumbs slug={page.slug} tree={tree} />
+        <div className={styles.content}>
+          {page.content}
+        </div>
+      </article>
+      <Toc items={page.toc} />
+    </Flex>
+  )
+}