- {page.content}
-
+ {page.content}
-
- ),
- {
- width: 1200,
- height: 630,
- }
- )
-}
diff --git a/packages/chronicle/src/app/providers.tsx b/packages/chronicle/src/app/providers.tsx
deleted file mode 100644
index 389b797..0000000
--- a/packages/chronicle/src/app/providers.tsx
+++ /dev/null
@@ -1,8 +0,0 @@
-'use client'
-
-import { ThemeProvider } from '@raystack/apsara'
-import type { ReactNode } from 'react'
-
-export function Providers({ children }: { children: ReactNode }) {
- return
- {siteName}
-
-
- {title}
-
- {description && (
-
- {description}
-
- )}
-
{title &&
@@ -129,10 +129,12 @@ export function Search({ className }: SearchProps) {
{title}
}
diff --git a/packages/chronicle/src/components/mdx/details.module.css b/packages/chronicle/src/components/mdx/details.module.css
index f79a00a..e3a6eec 100644
--- a/packages/chronicle/src/components/mdx/details.module.css
+++ b/packages/chronicle/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 {
diff --git a/packages/chronicle/src/components/mdx/details.tsx b/packages/chronicle/src/components/mdx/details.tsx
index 2d29ac0..aa98714 100644
--- a/packages/chronicle/src/components/mdx/details.tsx
+++ b/packages/chronicle/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 (
-
+
+
{children}
)
@@ -11,7 +10,7 @@ export function MdxDetails({ children, className, ...props }: ComponentProps<'de
export function MdxSummary({ children, className, ...props }: ComponentProps<'summary'>) {
return (
-
+
{children}
)
diff --git a/packages/chronicle/src/components/mdx/image.tsx b/packages/chronicle/src/components/mdx/image.tsx
index fcf511d..0f7aa80 100644
--- a/packages/chronicle/src/components/mdx/image.tsx
+++ b/packages/chronicle/src/components/mdx/image.tsx
@@ -1,38 +1,9 @@
-'use client'
+import type { ComponentProps } from 'react';
-import NextImage from 'next/image'
-import type { ComponentProps } from 'react'
+type ImageProps = ComponentProps<'img'>;
-type ImageProps = Omit, 'src'> & {
- src?: string
- width?: number | string
- height?: number | string
-}
-
-export function Image({ src, alt, width, height, ...props }: ImageProps) {
- if (!src || typeof src !== 'string') return null
-
- const isExternal = src.startsWith('http://') || src.startsWith('https://')
-
- if (isExternal) {
- return (
- // eslint-disable-next-line @next/next/no-img-element
- 
- )
- }
+export function Image({ src, alt, ...props }: ImageProps) {
+ if (!src) return null;
- return (
- ) {
+ return
{children}
- )
+ );
}
if (isExternal) {
return (
-
+
{children}
- )
+ );
}
return (
-
+
{children}
-
- )
+
+ );
}
diff --git a/packages/chronicle/src/components/ui/breadcrumbs.tsx b/packages/chronicle/src/components/ui/breadcrumbs.tsx
index 4eaff20..6babcd7 100644
--- a/packages/chronicle/src/components/ui/breadcrumbs.tsx
+++ b/packages/chronicle/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 (
@@ -55,10 +21,10 @@ export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
const breadcrumbItem = (
- {item.label}
+ {item.name}
)
if (index === 0) return [breadcrumbItem]
diff --git a/packages/chronicle/src/components/ui/search.tsx b/packages/chronicle/src/components/ui/search.tsx
index fb56aaa..293893d 100644
--- a/packages/chronicle/src/components/ui/search.tsx
+++ b/packages/chronicle/src/components/ui/search.tsx
@@ -1,21 +1,19 @@
-"use client";
-
-import { useState, useEffect, useCallback } from "react";
-import { useRouter } from "next/navigation";
-import { Button, Command, Dialog, Text } from "@raystack/apsara";
-import { cx } from "class-variance-authority";
-import { useDocsSearch } from "fumadocs-core/search/client";
-import type { SortedResult } from "fumadocs-core/search";
-import { DocumentIcon, HashtagIcon } from "@heroicons/react/24/outline";
-import { isMacOs } from "react-device-detect";
-import { MethodBadge } from "@/components/api/method-badge";
-import styles from "./search.module.css";
+import { DocumentIcon, HashtagIcon } from '@heroicons/react/24/outline';
+import { Button, Command, Dialog, Text } from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import type { SortedResult } from 'fumadocs-core/search';
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import { useCallback, useEffect, useState } from 'react';
+import { useNavigate } from 'react-router';
+import { MethodBadge } from '@/components/api/method-badge';
+import styles from './search.module.css';
function SearchShortcutKey({ className }: { className?: string }) {
- const [key, setKey] = useState("⌘");
+ const [key, setKey] = useState('⌘');
useEffect(() => {
- setKey(isMacOs ? "⌘" : "Ctrl");
+ const isMac = navigator.platform?.toUpperCase().includes('MAC');
+ setKey(isMac ? '⌘' : 'Ctrl');
}, []);
return (
@@ -26,50 +24,50 @@ function SearchShortcutKey({ className }: { className?: string }) {
}
interface SearchProps {
- className?: string
+ className?: string;
}
export function Search({ className }: SearchProps) {
const [open, setOpen] = useState(false);
- const router = useRouter();
+ const navigate = useNavigate();
const { search, setSearch, query } = useDocsSearch({
- type: "fetch",
- api: "/api/search",
+ type: 'fetch',
+ api: '/api/search',
delayMs: 100,
- allowEmpty: true,
+ allowEmpty: true
});
const onSelect = useCallback(
(url: string) => {
setOpen(false);
- router.push(url);
+ navigate(url);
},
- [router],
+ [navigate]
);
useEffect(() => {
const down = (e: KeyboardEvent) => {
- if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+ if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
e.preventDefault();
- setOpen((open) => !open);
+ setOpen(open => !open);
}
};
- document.addEventListener("keydown", down);
- return () => document.removeEventListener("keydown", down);
+ document.addEventListener('keydown', down);
+ return () => document.removeEventListener('keydown', down);
}, []);
const results = deduplicateByUrl(
- query.data === "empty" ? [] : (query.data ?? []),
+ query.data === 'empty' ? [] : (query.data ?? [])
);
return (
<>
{getResultIcon(result)}
();
- return results.filter((r) => {
- const base = r.url.split("#")[0];
+ return results.filter(r => {
+ const base = r.url.split('#')[0];
if (seen.has(base)) return false;
seen.add(base);
return true;
});
}
-const API_METHODS = new Set(["GET", "POST", "PUT", "DELETE", "PATCH"]);
+const API_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
function extractMethod(content: string): string | null {
- const first = content.split(" ")[0];
+ const first = content.split(' ')[0];
return API_METHODS.has(first) ? first : null;
}
function stripMethod(content: string): string {
- const first = content.split(" ")[0];
+ const first = content.split(' ')[0];
return API_METHODS.has(first) ? content.slice(first.length + 1) : content;
}
-function HighlightedText({ html, className }: { html: string; className?: string }) {
- return ;
+function HighlightedText({
+ html,
+ className
+}: {
+ html: string;
+ className?: string;
+}) {
+ return (
+
+ );
}
function getResultIcon(result: SortedResult): React.ReactNode {
- if (!result.url.startsWith("/apis/")) {
- return result.type === "page" ? (
+ if (!result.url.startsWith('/apis/')) {
+ return result.type === 'page' ? (
()
+ const opsByTag = new Map()
const tagDisplayName = new Map()
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)
}
diff --git a/packages/chronicle/src/lib/config.ts b/packages/chronicle/src/lib/config.ts
index aa77280..8237c64 100644
--- a/packages/chronicle/src/lib/config.ts
+++ b/packages/chronicle/src/lib/config.ts
@@ -1,56 +1,32 @@
-import fs from 'fs'
-import path from 'path'
-import { parse } from 'yaml'
-import type { ChronicleConfig } from '@/types'
-
-const CONFIG_FILE = 'chronicle.yaml'
+import { parse } from 'yaml';
+import type { ChronicleConfig } from '@/types';
const defaultConfig: ChronicleConfig = {
title: 'Documentation',
theme: { name: 'default' },
- search: { enabled: true, placeholder: 'Search...' },
-}
-
-function resolveConfigPath(): string | null {
- // Check project root via env var
- const projectRoot = process.env.CHRONICLE_PROJECT_ROOT
- if (projectRoot) {
- const rootPath = path.join(projectRoot, CONFIG_FILE)
- if (fs.existsSync(rootPath)) return rootPath
- }
- // Check cwd
- const cwdPath = path.join(process.cwd(), CONFIG_FILE)
- if (fs.existsSync(cwdPath)) return cwdPath
- // Check content dir
- const contentDir = process.env.CHRONICLE_CONTENT_DIR
- if (contentDir) {
- const contentPath = path.join(contentDir, CONFIG_FILE)
- if (fs.existsSync(contentPath)) return contentPath
- }
- return null
-}
+ search: { enabled: true, placeholder: 'Search...' }
+};
export function loadConfig(): ChronicleConfig {
- const configPath = resolveConfigPath()
+ const raw = typeof __CHRONICLE_CONFIG_RAW__ !== 'undefined' ? __CHRONICLE_CONFIG_RAW__ : null;
- if (!configPath) {
- return defaultConfig
+ if (!raw) {
+ return defaultConfig;
}
- const raw = fs.readFileSync(configPath, 'utf-8')
- const userConfig = parse(raw) as Partial
+ const userConfig = parse(raw) as Partial;
return {
...defaultConfig,
...userConfig,
theme: {
name: userConfig.theme?.name ?? defaultConfig.theme!.name,
- colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors },
+ colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors }
},
search: { ...defaultConfig.search, ...userConfig.search },
footer: userConfig.footer,
api: userConfig.api,
llms: { enabled: false, ...userConfig.llms },
- analytics: { enabled: false, ...userConfig.analytics },
- }
-}
\ No newline at end of file
+ analytics: { enabled: false, ...userConfig.analytics }
+ };
+}
diff --git a/packages/chronicle/src/lib/head.tsx b/packages/chronicle/src/lib/head.tsx
new file mode 100644
index 0000000..74b0621
--- /dev/null
+++ b/packages/chronicle/src/lib/head.tsx
@@ -0,0 +1,49 @@
+import type { ChronicleConfig } from '@/types';
+
+export interface HeadProps {
+ title: string;
+ description?: string;
+ config: ChronicleConfig;
+ jsonLd?: Record;
+}
+
+export function Head({ title, description, config, jsonLd }: HeadProps) {
+ const fullTitle = `${title} | ${config.title}`;
+ const ogParams = new URLSearchParams({ title });
+ if (description) ogParams.set('description', description);
+
+ return (
+ <>
+ {fullTitle}
+ {description && }
+
+ {config.url && (
+ <>
+
+ {description && (
+
+ )}
+
+
+
+
+
+
+
+
+ {description && (
+
+ )}
+
+
+ )}
+
+ {jsonLd && (
+
+ )}
+
+ );
+}
diff --git a/packages/chronicle/src/lib/openapi.ts b/packages/chronicle/src/lib/openapi.ts
index 4e12086..0d8a85c 100644
--- a/packages/chronicle/src/lib/openapi.ts
+++ b/packages/chronicle/src/lib/openapi.ts
@@ -1,5 +1,5 @@
-import fs from 'fs'
-import path from 'path'
+import fs from 'node:fs/promises'
+import path from 'node:path'
import { parse as parseYaml } from 'yaml'
import type { OpenAPIV2, OpenAPIV3 } from 'openapi-types'
import type { ApiConfig, ApiServerConfig, ApiAuthConfig } from '@/types/config'
@@ -17,14 +17,14 @@ export interface ApiSpec {
export type { SchemaField } from './schema'
export { flattenSchema } from './schema'
-export function loadApiSpecs(apiConfigs: ApiConfig[]): ApiSpec[] {
- const contentDir = process.env.CHRONICLE_CONTENT_DIR ?? process.cwd()
- return apiConfigs.map((config) => loadApiSpec(config, contentDir))
+export async function loadApiSpecs(apiConfigs: ApiConfig[]): Promise {
+ const projectRoot = typeof __CHRONICLE_PROJECT_ROOT__ !== 'undefined' ? __CHRONICLE_PROJECT_ROOT__ : process.cwd()
+ return Promise.all(apiConfigs.map((config) => loadApiSpec(config, projectRoot)))
}
-export function loadApiSpec(config: ApiConfig, contentDir: string): ApiSpec {
- const specPath = path.resolve(contentDir, config.spec)
- const raw = fs.readFileSync(specPath, 'utf-8')
+export async function loadApiSpec(config: ApiConfig, projectRoot: string): Promise {
+ const specPath = path.resolve(projectRoot, config.spec)
+ const raw = await fs.readFile(specPath, 'utf-8')
const isYaml = specPath.endsWith('.yaml') || specPath.endsWith('.yml')
const doc = (isYaml ? parseYaml(raw) : JSON.parse(raw)) as OpenAPIV2.Document | OpenAPIV3.Document
diff --git a/packages/chronicle/src/lib/page-context.tsx b/packages/chronicle/src/lib/page-context.tsx
new file mode 100644
index 0000000..893790a
--- /dev/null
+++ b/packages/chronicle/src/lib/page-context.tsx
@@ -0,0 +1,111 @@
+import {
+ createContext,
+ type ReactNode,
+ useContext,
+ useEffect,
+ useState
+} from 'react';
+import { useLocation } from 'react-router';
+import type { ApiSpec } from '@/lib/openapi';
+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: Root;
+ page: PageData | null;
+ apiSpecs: ApiSpec[];
+}
+
+const PageContext = createContext(null);
+
+export function usePageContext(): PageContextValue {
+ const ctx = useContext(PageContext);
+ if (!ctx) {
+ console.error('usePageContext: no context found!');
+ return {
+ config: { title: 'Documentation' },
+ tree: { name: 'root', children: [] } as Root,
+ page: null,
+ apiSpecs: []
+ };
+ }
+ return ctx;
+}
+
+interface PageProviderProps {
+ initialConfig: ChronicleConfig;
+ initialTree: Root;
+ initialPage: PageData | null;
+ initialApiSpecs: ApiSpec[];
+ loadMdx: MdxLoader;
+ children: ReactNode;
+}
+
+export function PageProvider({
+ initialConfig,
+ initialTree,
+ initialPage,
+ initialApiSpecs,
+ loadMdx,
+ children
+}: PageProviderProps) {
+ const { pathname } = useLocation();
+ const [tree] = useState(initialTree);
+ const [page, setPage] = useState(initialPage);
+ const [apiSpecs, setApiSpecs] = useState(initialApiSpecs);
+ const [currentPath, setCurrentPath] = useState(pathname);
+
+ useEffect(() => {
+ if (pathname === currentPath) return;
+ setCurrentPath(pathname);
+
+ const cancelled = { current: false };
+
+ if (pathname.startsWith('/apis')) {
+ if (apiSpecs.length === 0) {
+ fetch('/api/specs')
+ .then(res => res.json())
+ .then(specs => {
+ if (!cancelled.current) setApiSpecs(specs);
+ })
+ .catch(() => {});
+ }
+ return () => { cancelled.current = true; };
+ }
+
+ const slug = pathname === '/'
+ ? []
+ : pathname.slice(1).split('/').filter(Boolean);
+
+ const apiPath = slug.length === 0 ? '/api/page/' : `/api/page/${slug.join('/')}`;
+
+ fetch(apiPath)
+ .then(res => res.json())
+ .then(async (data: { frontmatter: Frontmatter; relativePath: string }) => {
+ if (cancelled.current) return;
+ const { content, toc } = await loadMdx(data.relativePath);
+ if (cancelled.current) return;
+ setPage({ slug, frontmatter: data.frontmatter, content, toc });
+ })
+ .catch(() => {});
+
+ return () => { cancelled.current = true; };
+ }, [pathname]);
+
+ return (
+
+ {children}
+
+ );
+}
diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts
index 71cb663..083792b 100644
--- a/packages/chronicle/src/lib/source.ts
+++ b/packages/chronicle/src/lib/source.ts
@@ -1,67 +1,138 @@
-import { docs } from '@/.source/server'
-import { loader } from 'fumadocs-core/source'
-import type { PageTree, PageTreeItem, Frontmatter } from '@/types'
-
-export const source = loader({
- baseUrl: '/',
- source: docs.toFumadocsSource(),
-})
-
-export function sortByOrder(
- items: T[]
-): T[] {
- return [...items].sort((a, b) => {
- const orderA = a.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
- const orderB = b.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
- return orderA - orderB
- })
-}
+import { loader } from 'fumadocs-core/source';
+import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
+import type { MDXContent } from 'mdx/types';
+import type { TableOfContents } from 'fumadocs-core/toc';
+import type { Frontmatter } from '@/types';
+
+const CONTENT_PREFIX = '../../.content/';
+
+const frontmatterGlob: Record> = import.meta.glob(
+ '../../.content/**/*.{mdx,md}',
+ { eager: true, import: 'frontmatter' }
+);
+
+const metaGlob: Record> = import.meta.glob(
+ '../../.content/**/meta.json',
+ { eager: true }
+);
-export function buildPageTree(): PageTree {
- const pages = source.getPages()
- const folders = new Map()
- const rootPages: PageTreeItem[] = []
+function buildFiles() {
+ const files: {
+ type: 'page' | 'meta';
+ path: string;
+ data: Record;
+ }[] = [];
- pages.forEach((page) => {
- const data = page.data as { title?: string; order?: number }
- const isIndex = page.url === '/'
- const item: PageTreeItem = {
+ for (const [key, data] of Object.entries(frontmatterGlob)) {
+ const relativePath = key.slice(CONTENT_PREFIX.length);
+ files.push({
type: 'page',
- name: data.title ?? page.slugs.join('/') ?? 'Untitled',
- url: page.url,
- order: data.order ?? (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)
- }
- })
-
- const sortByOrder = (items: PageTreeItem[]) =>
- items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
-
- const children: PageTreeItem[] = sortByOrder(rootPages)
-
- const folderItems: PageTreeItem[] = []
- folders.forEach((items, folder) => {
- 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,
- })
- })
-
- children.push(...sortByOrder(folderItems))
-
- return { name: 'root', children }
+ path: relativePath,
+ data: { ...data, _relativePath: relativePath }
+ });
+ }
+
+ for (const [key, data] of Object.entries(metaGlob)) {
+ const relativePath = key.slice(CONTENT_PREFIX.length);
+ files.push({ type: 'meta', path: relativePath, data: data ?? {} });
+ }
+
+ return files;
+}
+
+let cachedSource: ReturnType | null = null;
+
+async function getSource() {
+ if (cachedSource) return cachedSource;
+ const files = buildFiles();
+ cachedSource = loader({
+ source: { files },
+ baseUrl: '/'
+ });
+ return cachedSource;
+}
+
+export { getSource as source };
+
+export function invalidate() {
+ cachedSource = null;
+}
+
+function getOrder(node: Node, orderMap: Map): 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;
+}
+
+function sortNodes(nodes: Node[], orderMap: Map): 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)
+ );
+}
+
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
+ const orderMap = new Map();
+ for (const page of pages) {
+ const d = page.data as Record;
+ const order = d.order as number | undefined;
+ if (order !== undefined) orderMap.set(page.url, order);
+ if (page.url === '/') orderMap.set('/', order ?? 0);
+ }
+ return { ...tree, children: sortNodes(tree.children, orderMap) };
+}
+
+export async function getPageTree(): Promise {
+ const s = await getSource();
+ return sortTreeByOrder(s.pageTree as Root, s.getPages());
+}
+
+export async function getPages() {
+ const s = await getSource();
+ return s.getPages();
+}
+
+export async function getPage(slugs?: string[]) {
+ const s = await getSource();
+ return s.getPage(slugs);
+}
+
+export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {
+ const d = page.data as Record;
+ 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,
+ };
+}
+
+export function getRelativePath(page: { data: unknown }): string {
+ return ((page.data as Record)._relativePath as string) ?? '';
+}
+
+const ssrModules = import.meta.glob<{ default?: MDXContent; toc?: TableOfContents }>(
+ '../../.content/**/*.{mdx,md}'
+);
+
+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 ?? [] };
}
diff --git a/packages/chronicle/src/app/apis/[[...slug]]/layout.module.css b/packages/chronicle/src/pages/ApiLayout.module.css
similarity index 100%
rename from packages/chronicle/src/app/apis/[[...slug]]/layout.module.css
rename to packages/chronicle/src/pages/ApiLayout.module.css
diff --git a/packages/chronicle/src/pages/ApiLayout.tsx b/packages/chronicle/src/pages/ApiLayout.tsx
new file mode 100644
index 0000000..bfd6631
--- /dev/null
+++ b/packages/chronicle/src/pages/ApiLayout.tsx
@@ -0,0 +1,33 @@
+import { cx } from 'class-variance-authority';
+import type { ReactNode } from 'react';
+import { Search } from '@/components/ui/search';
+import { buildApiPageTree } from '@/lib/api-routes';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+import styles from './ApiLayout.module.css';
+
+interface ApiLayoutProps {
+ children: ReactNode;
+}
+
+export function ApiLayout({ children }: ApiLayoutProps) {
+ const { config, apiSpecs } = usePageContext();
+ const { Layout, className } = getTheme(config.theme?.name);
+ const tree = buildApiPageTree(apiSpecs);
+
+ return (
+
+
+ );
+}
diff --git a/packages/chronicle/src/pages/ApiPage.tsx b/packages/chronicle/src/pages/ApiPage.tsx
new file mode 100644
index 0000000..84858c5
--- /dev/null
+++ b/packages/chronicle/src/pages/ApiPage.tsx
@@ -0,0 +1,73 @@
+import { Flex, Headline, Text } from '@raystack/apsara';
+import type { OpenAPIV3 } from 'openapi-types';
+import { EndpointPage } from '@/components/api';
+import { findApiOperation } from '@/lib/api-routes';
+import { Head } from '@/lib/head';
+import type { ApiSpec } from '@/lib/openapi';
+import { usePageContext } from '@/lib/page-context';
+
+interface ApiPageProps {
+ slug: string[];
+}
+
+export function ApiPage({ slug }: ApiPageProps) {
+ const { config, apiSpecs } = usePageContext();
+
+ if (slug.length === 0) {
+ return (
+ <>
+
+
+
+
+ API Reference
+
+ {specs.map(spec => (
+
+
+ {spec.name}
+
+ {spec.document.info.description && (
+ {spec.document.info.description}
+ )}
+
+ ))}
+
+ );
+}
diff --git a/packages/chronicle/src/pages/DocsLayout.tsx b/packages/chronicle/src/pages/DocsLayout.tsx
new file mode 100644
index 0000000..da59652
--- /dev/null
+++ b/packages/chronicle/src/pages/DocsLayout.tsx
@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+
+interface DocsLayoutProps {
+ children: ReactNode;
+}
+
+export function DocsLayout({ children }: DocsLayoutProps) {
+ const { config, tree } = usePageContext();
+ const { Layout, className } = getTheme(config.theme?.name);
+
+ return (
+
+ {children}
+
+ );
+}
diff --git a/packages/chronicle/src/pages/DocsPage.tsx b/packages/chronicle/src/pages/DocsPage.tsx
new file mode 100644
index 0000000..94a0206
--- /dev/null
+++ b/packages/chronicle/src/pages/DocsPage.tsx
@@ -0,0 +1,43 @@
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+
+interface DocsPageProps {
+ slug: string[];
+}
+
+export function DocsPage({ slug }: DocsPageProps) {
+ const { config, tree, page } = usePageContext();
+
+ if (!page) return null;
+
+ const { Page } = getTheme(config.theme?.name);
+ const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined;
+
+ return (
+ <>
+
+
+
+ 404
+
+ Page not found
+
+ );
+}
diff --git a/packages/chronicle/src/server/App.tsx b/packages/chronicle/src/server/App.tsx
new file mode 100644
index 0000000..2f7b349
--- /dev/null
+++ b/packages/chronicle/src/server/App.tsx
@@ -0,0 +1,67 @@
+import '@raystack/apsara/normalize.css';
+import '@raystack/apsara/style.css';
+import { ThemeProvider } from '@raystack/apsara';
+import { useLocation } from 'react-router';
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { ApiLayout } from '@/pages/ApiLayout';
+import { ApiPage } from '@/pages/ApiPage';
+import { DocsLayout } from '@/pages/DocsLayout';
+import { DocsPage } from '@/pages/DocsPage';
+import type { ChronicleConfig } from '@/types';
+
+function resolveRoute(pathname: string) {
+ if (pathname.startsWith('/apis')) {
+ const slug = pathname
+ .replace(/^\/apis\/?/, '')
+ .split('/')
+ .filter(Boolean);
+ return { type: 'api' as const, slug };
+ }
+
+ const slug =
+ pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean);
+ return { type: 'docs' as const, slug };
+}
+
+export function App() {
+ const { pathname } = useLocation();
+ const { config } = usePageContext();
+ const route = resolveRoute(pathname);
+
+ return (
+
+
+
+ ) : (
+
+
+ )}
+
+ );
+}
+
+function RootHead({ config }: { config: ChronicleConfig }) {
+ return (
+
+ );
+}
diff --git a/packages/chronicle/src/server/api/apis-proxy.ts b/packages/chronicle/src/server/api/apis-proxy.ts
new file mode 100644
index 0000000..83e8642
--- /dev/null
+++ b/packages/chronicle/src/server/api/apis-proxy.ts
@@ -0,0 +1,69 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+
+interface ProxyRequest {
+ specName: string;
+ method: string;
+ path: string;
+ headers?: Record;
+ body?: unknown;
+}
+
+export default defineHandler(async event => {
+ if (event.req.method !== 'POST') {
+ throw new HTTPError({ status: 405, message: 'Method not allowed' });
+ }
+
+ const { specName, method, path, headers, body } =
+ (await event.req.json()) as ProxyRequest;
+
+ if (!specName || !method || !path) {
+ throw new HTTPError({
+ status: 400,
+ message: 'Missing specName, method, or path'
+ });
+ }
+
+ const config = loadConfig();
+ const specs = await loadApiSpecs(config.api ?? []);
+ const spec = specs.find(s => s.name === specName);
+
+ if (!spec) {
+ throw new HTTPError({ status: 404, message: `Unknown spec: ${specName}` });
+ }
+
+ if (/^[a-z]+:\/\//i.test(path) || path.includes('..')) {
+ throw new HTTPError({ status: 400, message: 'Invalid path' });
+ }
+
+ const url = spec.server.url + path;
+
+ try {
+ const response = await fetch(url, {
+ method,
+ headers,
+ body: body ? JSON.stringify(body) : undefined
+ });
+
+ const contentType = response.headers.get('content-type') ?? '';
+ const responseBody = contentType.includes('application/json')
+ ? await response.json()
+ : await response.text();
+
+ return {
+ status: response.status,
+ statusText: response.statusText,
+ body: responseBody
+ };
+ } catch (error) {
+ const message =
+ error instanceof Error
+ ? `${error.message}${error.cause ? `: ${(error.cause as Error).message}` : ''}`
+ : 'Request failed';
+ throw new HTTPError({
+ status: 502,
+ message: `Could not reach ${url}\n${message}`
+ });
+ }
+});
diff --git a/packages/chronicle/src/server/api/health.ts b/packages/chronicle/src/server/api/health.ts
new file mode 100644
index 0000000..6691999
--- /dev/null
+++ b/packages/chronicle/src/server/api/health.ts
@@ -0,0 +1,5 @@
+import { defineHandler } from 'nitro';
+
+export default defineHandler(() => {
+ return { status: 'ok' };
+});
diff --git a/packages/chronicle/src/server/api/page/[...slug].ts b/packages/chronicle/src/server/api/page/[...slug].ts
new file mode 100644
index 0000000..c9e8ecf
--- /dev/null
+++ b/packages/chronicle/src/server/api/page/[...slug].ts
@@ -0,0 +1,17 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { getPage, extractFrontmatter, getRelativePath } from '@/lib/source';
+
+export default defineHandler(async event => {
+ const slugParam = event.context.params?.slug ?? '';
+ const slug = slugParam ? slugParam.split('/') : [];
+ const page = await getPage(slug);
+
+ if (!page) {
+ throw new HTTPError({ status: 404, message: 'Page not found' });
+ }
+
+ return {
+ frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+ relativePath: getRelativePath(page),
+ };
+});
diff --git a/packages/chronicle/src/server/api/search.ts b/packages/chronicle/src/server/api/search.ts
new file mode 100644
index 0000000..86d2166
--- /dev/null
+++ b/packages/chronicle/src/server/api/search.ts
@@ -0,0 +1,118 @@
+import MiniSearch from 'minisearch';
+import { defineHandler } from 'nitro';
+import type { OpenAPIV3 } from 'openapi-types';
+import { getSpecSlug } from '@/lib/api-routes';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+import { getPages, extractFrontmatter } from '@/lib/source';
+
+interface SearchDocument {
+ id: string;
+ url: string;
+ title: string;
+ content: string;
+ type: 'page' | 'api';
+}
+
+let searchIndex: MiniSearch | null = null;
+let cachedDocs: SearchDocument[] | null = null;
+
+function createIndex(docs: SearchDocument[]): MiniSearch {
+ const index = new MiniSearch({
+ fields: ['title', 'content'],
+ storeFields: ['url', 'title', 'type'],
+ searchOptions: {
+ boost: { title: 2 },
+ fuzzy: 0.2,
+ prefix: true
+ }
+ });
+ index.addAll(docs);
+ return index;
+}
+
+async function scanContent(): Promise {
+ const pages = await getPages();
+ return pages.map(p => {
+ const fm = extractFrontmatter(p);
+ return {
+ id: p.url,
+ url: p.url,
+ title: fm.title,
+ content: fm.description ?? '',
+ type: 'page' as const
+ };
+ });
+}
+
+async function buildApiDocs(): Promise {
+ const config = loadConfig();
+ if (!config.api?.length) return [];
+
+ const docs: SearchDocument[] = [];
+ const specs = await loadApiSpecs(config.api);
+
+ for (const spec of specs) {
+ const specSlug = getSpecSlug(spec);
+ const paths = spec.document.paths ?? {};
+ for (const [, 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 getDocs(): Promise {
+ if (cachedDocs) return cachedDocs;
+ const [contentDocs, apiDocs] = await Promise.all([
+ scanContent(),
+ buildApiDocs()
+ ]);
+ cachedDocs = [...contentDocs, ...apiDocs];
+ return cachedDocs;
+}
+
+async function getIndex(): Promise> {
+ if (searchIndex) return searchIndex;
+ const docs = await getDocs();
+ searchIndex = createIndex(docs);
+ return searchIndex;
+}
+
+export default defineHandler(async event => {
+ const query = event.url.searchParams.get('query') ?? '';
+ const index = await getIndex();
+
+ if (!query) {
+ const docs = await getDocs();
+ return docs
+ .filter(d => d.type === 'page')
+ .slice(0, 8)
+ .map(d => ({
+ id: d.id,
+ url: d.url,
+ type: d.type,
+ content: d.title
+ }));
+ }
+
+ return index.search(query).map(r => ({
+ id: r.id,
+ url: r.url,
+ type: r.type,
+ content: r.title
+ }));
+});
diff --git a/packages/chronicle/src/server/api/specs.ts b/packages/chronicle/src/server/api/specs.ts
new file mode 100644
index 0000000..3d4f1f7
--- /dev/null
+++ b/packages/chronicle/src/server/api/specs.ts
@@ -0,0 +1,9 @@
+import { defineHandler } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+
+export default defineHandler(async () => {
+ const config = loadConfig();
+ const specs = config.api?.length ? await loadApiSpecs(config.api) : [];
+ return specs;
+});
diff --git a/packages/chronicle/src/server/build-search-index.ts b/packages/chronicle/src/server/build-search-index.ts
new file mode 100644
index 0000000..4196a78
--- /dev/null
+++ b/packages/chronicle/src/server/build-search-index.ts
@@ -0,0 +1,117 @@
+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';
+}
+
+function extractHeadings(markdown: string): string {
+ 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 {
+ const docs: SearchDocument[] = [];
+
+ 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, 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;
+}
+
+async function buildApiDocs(): Promise {
+ const config = loadConfig();
+ if (!config.api?.length) return [];
+
+ const docs: SearchDocument[] = [];
+ const specs = await loadApiSpecs(config.api);
+
+ for (const spec of specs) {
+ const specSlug = getSpecSlug(spec);
+ const paths = spec.document.paths ?? {};
+ for (const [, 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;
+}
+
+export async function generateSearchIndex(contentDir: string, outDir: string) {
+ const [contentDocs, apiDocs] = await Promise.all([
+ scanContent(contentDir),
+ buildApiDocs()
+ ]);
+
+ const documents = [...contentDocs, ...apiDocs];
+ const outPath = path.join(outDir, 'search-index.json');
+ await fs.writeFile(outPath, JSON.stringify(documents));
+
+ return documents.length;
+}
diff --git a/packages/chronicle/src/server/entry-client.tsx b/packages/chronicle/src/server/entry-client.tsx
new file mode 100644
index 0000000..c4b1834
--- /dev/null
+++ b/packages/chronicle/src/server/entry-client.tsx
@@ -0,0 +1,86 @@
+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: Root;
+ slug: string[];
+ frontmatter: Frontmatter;
+ relativePath: string;
+}
+
+const contentModules = import.meta.glob<{ default?: React.ComponentType; toc?: TableOfContents }>(
+ '../../.content/**/*.{mdx,md}'
+);
+
+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 ?? [] };
+}
+
+async function hydrate() {
+ try {
+ const embedded = (
+ window as unknown as { __PAGE_DATA__?: EmbeddedData }
+ ).__PAGE_DATA__;
+
+ 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 page = embedded?.relativePath
+ ? {
+ slug: embedded.slug,
+ frontmatter: embedded.frontmatter,
+ ...(await loadMdxModule(embedded.relativePath)),
+ }
+ : null;
+
+ hydrateRoot(
+ document.getElementById('root') as HTMLElement,
+
+
+
+
+
+
+ );
+ } catch (err) {
+ console.error('Hydration failed:', err);
+ }
+}
+
+hydrate();
diff --git a/packages/chronicle/src/server/entry-server.tsx b/packages/chronicle/src/server/entry-server.tsx
new file mode 100644
index 0000000..be5b2d0
--- /dev/null
+++ b/packages/chronicle/src/server/entry-server.tsx
@@ -0,0 +1,100 @@
+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(/
+
+
+
+ {assets.css.map((attr: { href: string }) => (
+
+ ))}
+ {assets.js.map((attr: { href: string }) => (
+
+ ))}
+
+
+
+
+ {
+ 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(
+ ;
+ const lastmod = data.lastModified
+ ? `${new Date(data.lastModified as string).toISOString()} `
+ : '';
+ return `${baseUrl}/${page.slugs.join('/')} ${lastmod}${baseUrl}/apis/${route.slug.join('/')}
+${baseUrl} `;
+
+ event.res.headers.set('Content-Type', 'application/xml');
+ return xml;
+});
diff --git a/packages/chronicle/src/server/utils/safe-path.ts b/packages/chronicle/src/server/utils/safe-path.ts
new file mode 100644
index 0000000..4d3867d
--- /dev/null
+++ b/packages/chronicle/src/server/utils/safe-path.ts
@@ -0,0 +1,17 @@
+import path from 'node:path';
+
+/**
+ * Resolve a URL path within a base directory, preventing path traversal.
+ * Returns null if the resolved path escapes the base directory.
+ */
+export function safePath(baseDir: string, urlPath: string): string | null {
+ const decoded = decodeURIComponent(urlPath.split('?')[0]);
+ const resolved = path.resolve(baseDir, '.' + decoded);
+ if (
+ !resolved.startsWith(path.resolve(baseDir) + path.sep) &&
+ resolved !== path.resolve(baseDir)
+ ) {
+ return null;
+ }
+ return resolved;
+}
diff --git a/packages/chronicle/src/server/vite-config.ts b/packages/chronicle/src/server/vite-config.ts
new file mode 100644
index 0000000..1e333cf
--- /dev/null
+++ b/packages/chronicle/src/server/vite-config.ts
@@ -0,0 +1,126 @@
+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 fs from 'node:fs/promises';
+import path from 'node:path';
+import remarkDirective from 'remark-directive';
+import { type InlineConfig } from 'vite';
+import remarkUnusedDirectives from '../lib/remark-unused-directives';
+
+function resolveOutputDir(projectRoot: string, preset?: string): string {
+ if (preset === 'vercel' || preset === 'vercel-static') return path.resolve(projectRoot, '.vercel/output');
+ return path.resolve(projectRoot, '.output');
+}
+
+export interface ViteConfigOptions {
+ packageRoot: string;
+ projectRoot: string;
+ contentDir: string;
+ preset?: string;
+}
+
+async function readChronicleConfig(projectRoot: string, contentDir: string): Promise {
+ for (const dir of [projectRoot, contentDir]) {
+ const filePath = path.join(dir, 'chronicle.yaml');
+ try {
+ return await fs.readFile(filePath, 'utf-8');
+ } catch {
+ // not found, try next
+ }
+ }
+ return null;
+}
+
+export async function createViteConfig(
+ options: ViteConfigOptions
+): Promise {
+ const { packageRoot, projectRoot, contentDir, preset } = options;
+ const rawConfig = await readChronicleConfig(projectRoot, contentDir);
+
+ return {
+ root: packageRoot,
+ configFile: false,
+ plugins: [
+ nitro({
+ serverDir: path.resolve(packageRoot, 'src/server'),
+ ...(preset && { preset }),
+ }),
+ 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',
+ },
+ }],
+ remarkUnusedDirectives,
+ remarkMdxMermaid,
+ ],
+ },
+ }),
+ }, { index: false }),
+ react()
+ ],
+ resolve: {
+ alias: {
+ '@': path.resolve(packageRoot, 'src'),
+ },
+ conditions: ['module-sync', 'import', 'node'],
+ dedupe: [
+ 'react',
+ 'react-dom',
+ 'react/jsx-runtime',
+ 'react/jsx-dev-runtime',
+ 'react-router',
+ ]
+ },
+ server: {
+ fs: {
+ allow: [packageRoot, projectRoot, contentDir]
+ }
+ },
+ define: {
+ __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentDir),
+ __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot),
+ __CHRONICLE_CONFIG_RAW__: JSON.stringify(rawConfig),
+ },
+ css: {
+ modules: {
+ localsConvention: 'camelCase'
+ }
+ },
+ ssr: {
+ noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core']
+ },
+ environments: {
+ client: {
+ build: {
+ rollupOptions: {
+ input: path.resolve(packageRoot, 'src/server/entry-client.tsx')
+ }
+ }
+ }
+ },
+ nitro: {
+ output: {
+ dir: resolveOutputDir(projectRoot, preset),
+ },
+ },
+ };
+}
diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
index 9bb93f6..625784d 100644
--- a/packages/chronicle/src/themes/default/Layout.tsx
+++ b/packages/chronicle/src/themes/default/Layout.tsx
@@ -1,64 +1,86 @@
-"use client";
-
-import { useMemo, useEffect, useRef } from "react";
-import { usePathname } from "next/navigation";
-import NextLink from "next/link";
-import { cx } from "class-variance-authority";
-import { Flex, Navbar, Headline, Link, 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";
+import { RectangleStackIcon } from '@heroicons/react/24/outline';
+import {
+ Button,
+ Flex,
+ Headline,
+ Link,
+ Navbar,
+ Sidebar
+} from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import { useEffect, useRef } from 'react';
+import { Link as RouterLink, useLocation } from 'react-router';
+import { MethodBadge } from '@/components/api/method-badge';
+import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
+import { Footer } from '@/components/ui/footer';
+import { Search } from '@/components/ui/search';
+import type { Node } from 'fumadocs-core/page-tree';
+import type { ThemeLayoutProps } from '@/types';
+import styles from './Layout.module.css';
const iconMap: Record = {
- "rectangle-stack": (null);
useEffect(() => {
const el = scrollRef.current;
if (!el) return;
- const onScroll = () => { savedScrollTop = el.scrollTop; };
+ 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; });
+ if (el)
+ requestAnimationFrame(() => {
+ el.scrollTop = savedScrollTop;
+ });
}, [pathname]);
return (
-
+
-
-
+
+
{config.title}
-
+
-
- {config.api?.map((api) => (
-
+
+ {config.api?.map(api => (
+
{api.name} API
-
+
))}
- {config.navigation?.links?.map((link) => (
+ {config.navigation?.links?.map(link => (
{link.label}
@@ -69,18 +91,24 @@ export function Layout({ children, config, tree, classNames }: ThemeLayoutProps)
-
+
- {tree.children.map((item) => (
+ {tree.children.map((item, i) => (
- {children}
+
+ {children}
+
@@ -89,25 +117,26 @@ export function Layout({ children, config, tree, classNames }: ThemeLayoutProps)
function SidebarNode({
item,
- pathname,
+ pathname
}: {
- item: PageTreeItem;
+ item: Node;
pathname: string;
}) {
- if (item.type === "separator") {
+ if (item.type === 'separator') {
return null;
}
- if (item.type === "folder" && item.children) {
+ if (item.type === 'folder') {
+ const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
return (
- {item.children.map((child) => (
+ {item.children.map((child, i) => (
{item.name}
diff --git a/packages/chronicle/src/themes/default/Page.module.css b/packages/chronicle/src/themes/default/Page.module.css
index 1ad7cb2..f83bfd0 100644
--- a/packages/chronicle/src/themes/default/Page.module.css
+++ b/packages/chronicle/src/themes/default/Page.module.css
@@ -38,9 +38,53 @@
margin-bottom: var(--rs-space-3);
}
+.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);
+}
diff --git a/packages/chronicle/src/themes/default/Page.tsx b/packages/chronicle/src/themes/default/Page.tsx
index 9d1599a..247acf9 100644
--- a/packages/chronicle/src/themes/default/Page.tsx
+++ b/packages/chronicle/src/themes/default/Page.tsx
@@ -1,21 +1,19 @@
-'use client'
+'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'
+import { Flex } from '@raystack/apsara';
+import { Breadcrumbs } from '@/components/ui/breadcrumbs';
+import type { ThemePageProps } from '@/types';
+import styles from './Page.module.css';
+import { Toc } from './Toc';
export function Page({ page, tree }: ThemePageProps) {
return (
-
+
- )
+ );
}
diff --git a/packages/chronicle/src/themes/default/Toc.tsx b/packages/chronicle/src/themes/default/Toc.tsx
index 03da673..455befc 100644
--- a/packages/chronicle/src/themes/default/Toc.tsx
+++ b/packages/chronicle/src/themes/default/Toc.tsx
@@ -1,55 +1,41 @@
-'use client'
+'use client';
-import { useEffect, useState } from 'react'
-import { Text } from '@raystack/apsara'
-import type { TocItem } from '@/types'
-import styles from './Toc.module.css'
+import { Text } from '@raystack/apsara';
+import { AnchorProvider, useActiveAnchor } from 'fumadocs-core/toc';
+import type { TableOfContents, TOCItemType } from 'fumadocs-core/toc';
+import styles from './Toc.module.css';
interface TocProps {
- items: TocItem[]
+ items: TableOfContents;
}
export function Toc({ items }: TocProps) {
- const [activeId, setActiveId] = useState('')
+ const filteredItems = items.filter(
+ item => item.depth >= 2 && item.depth <= 3
+ );
- // Filter to only show h2 and h3 headings
- const filteredItems = items.filter((item) => item.depth >= 2 && item.depth <= 3)
+ if (filteredItems.length === 0) return null;
- useEffect(() => {
- const headingIds = filteredItems.map((item) => item.url.replace('#', ''))
-
- const observer = new IntersectionObserver(
- (entries) => {
- entries.forEach((entry) => {
- if (entry.isIntersecting) {
- setActiveId(entry.target.id)
- }
- })
- },
- // -80px top: offset for fixed header, -80% bottom: trigger when heading is in top 20% of viewport
- { rootMargin: '-80px 0px -80% 0px' }
- )
-
- headingIds.forEach((id) => {
- const element = document.getElementById(id)
- if (element) observer.observe(element)
- })
-
- return () => observer.disconnect()
- }, [filteredItems])
+ return (
+
+
+ );
+}
- if (filteredItems.length === 0) return null
+function TocContent({ items }: { items: TOCItemType[] }) {
+ const activeAnchor = useActiveAnchor();
return (
- )
+ );
}
diff --git a/packages/chronicle/src/themes/default/font.ts b/packages/chronicle/src/themes/default/font.ts
deleted file mode 100644
index 97d4976..0000000
--- a/packages/chronicle/src/themes/default/font.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import { Inter } from 'next/font/google'
-
-export const inter = Inter({
- subsets: ['latin'],
- display: 'swap',
-})
diff --git a/packages/chronicle/src/themes/default/index.ts b/packages/chronicle/src/themes/default/index.ts
index b145a3d..c081197 100644
--- a/packages/chronicle/src/themes/default/index.ts
+++ b/packages/chronicle/src/themes/default/index.ts
@@ -1,13 +1,11 @@
-import { Layout } from './Layout'
-import { Page } from './Page'
-import { Toc } from './Toc'
-import { inter } from './font'
-import type { Theme } from '@/types'
+import type { Theme } from '@/types';
+import { Layout } from './Layout';
+import { Page } from './Page';
+import { Toc } from './Toc';
export const defaultTheme: Theme = {
Layout,
- Page,
- className: inter.className,
-}
+ Page
+};
-export { Layout, Page, Toc }
+export { Layout, Page, Toc };
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.tsx b/packages/chronicle/src/themes/paper/ChapterNav.tsx
index e267d49..3d9bcad 100644
--- a/packages/chronicle/src/themes/paper/ChapterNav.tsx
+++ b/packages/chronicle/src/themes/paper/ChapterNav.tsx
@@ -1,96 +1,115 @@
-'use client'
-
-import { usePathname } from 'next/navigation'
-import NextLink from 'next/link'
-import { MethodBadge } from '@/components/api/method-badge'
-import type { PageTree, PageTreeItem } from '@/types'
-import styles from './ChapterNav.module.css'
+import { Link as RouterLink, useLocation } from 'react-router';
+import { MethodBadge } from '@/components/api/method-badge';
+import type { Root, Node } from 'fumadocs-core/page-tree';
+import styles from './ChapterNav.module.css';
const iconMap: Record = {
- 'method-get': {
- const indices = new Map()
- let index = 0
+function buildChapterIndices(
+ children: Node[]
+): Map {
+ const indices = new Map();
+ let index = 0;
for (const item of children) {
- if (item.type === 'folder' && item.children) {
- index++
- indices.set(item, index)
+ if (item.type === 'folder') {
+ index++;
+ indices.set(item, index);
}
}
- return indices
+ return indices;
}
export function ChapterNav({ tree }: ChapterNavProps) {
- const pathname = usePathname()
- const chapterIndices = buildChapterIndices(tree.children)
+ const { pathname } = useLocation();
+ const chapterIndices = buildChapterIndices(tree.children);
return (
- )
+ );
}
-function ChapterItem({ item, pathname }: { item: PageTreeItem; pathname: string }) {
- if (item.type === 'separator') return null
+function ChapterItem({
+ item,
+ pathname
+}: {
+ item: Node;
+ pathname: string;
+}) {
+ if (item.type === 'separator') return null;
- if (item.type === 'folder' && item.children) {
+ if (item.type === 'folder') {
return (
{item.name}
- )
+ );
}
- const isActive = pathname === item.url
- const icon = item.icon ? iconMap[item.icon] : null
+ const isActive = pathname === item.url;
+ const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
return (
-
{icon && {icon}}
{item.name}
-
+
- )
+ );
}
diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index ec9fd54..673716e 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -13,7 +13,7 @@
padding: var(--rs-space-7) var(--rs-space-5);
background: var(--rs-color-background-neutral-primary);
overflow-y: auto;
- font-family: 'SF Mono', 'Fira Code', 'Fira Mono', 'Roboto Mono', monospace;
+ font-family: "SF Mono", "Fira Code", "Fira Mono", "Roboto Mono", monospace;
}
.title {
diff --git a/packages/chronicle/src/themes/paper/Layout.tsx b/packages/chronicle/src/themes/paper/Layout.tsx
index 8bd499a..805dcd2 100644
--- a/packages/chronicle/src/themes/paper/Layout.tsx
+++ b/packages/chronicle/src/themes/paper/Layout.tsx
@@ -1,25 +1,37 @@
-'use client'
+'use client';
-import { Flex, Headline } from '@raystack/apsara'
-import { cx } from 'class-variance-authority'
-import { Footer } from '@/components/ui/footer'
-import { ChapterNav } from './ChapterNav'
-import type { ThemeLayoutProps } from '@/types'
-import styles from './Layout.module.css'
+import { Flex, Headline } from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import { Footer } from '@/components/ui/footer';
+import type { ThemeLayoutProps } from '@/types';
+import { ChapterNav } from './ChapterNav';
+import styles from './Layout.module.css';
-export function Layout({ children, config, tree, classNames }: ThemeLayoutProps) {
+export function Layout({
+ children,
+ config,
+ tree,
+ classNames
+}: ThemeLayoutProps) {
return (
-
+
-
- )
+ );
}
diff --git a/packages/chronicle/src/themes/paper/Page.module.css b/packages/chronicle/src/themes/paper/Page.module.css
index 26eaddb..df8bca8 100644
--- a/packages/chronicle/src/themes/paper/Page.module.css
+++ b/packages/chronicle/src/themes/paper/Page.module.css
@@ -1,7 +1,12 @@
.main {
--paper-navbar-height: 40px;
--paper-navbar-padding: var(--rs-space-3);
- --paper-navbar-total: calc(var(--paper-navbar-height) + var(--paper-navbar-padding) * 2 + 1px);
+ --paper-navbar-total: calc(
+ var(--paper-navbar-height) +
+ var(--paper-navbar-padding) *
+ 2 +
+ 1px
+ );
flex: 1;
max-width: 1024px;
@@ -52,7 +57,7 @@
}
.breadcrumb {
- font-family: 'SF Mono', 'Fira Code', monospace;
+ font-family: "SF Mono", "Fira Code", monospace;
font-size: var(--rs-font-size-small);
text-transform: uppercase;
letter-spacing: 0.05em;
@@ -94,13 +99,15 @@
}
.content {
- font-family: Georgia, 'Times New Roman', serif;
+ font-family: Georgia, "Times New Roman", serif;
line-height: 1.8;
background: var(--rs-color-background-base-primary);
padding: var(--rs-space-9);
border-left: 1px solid var(--rs-color-border-base-primary);
border-right: 1px solid var(--rs-color-border-base-primary);
- box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08), 0 4px 12px rgba(0, 0, 0, 0.04);
+ box-shadow:
+ 0 1px 3px rgba(0, 0, 0, 0.08),
+ 0 4px 12px rgba(0, 0, 0, 0.04);
margin-bottom: var(--rs-space-9);
}
@@ -167,6 +174,11 @@
margin-bottom: var(--rs-space-3);
}
+.content img {
+ max-width: 100%;
+ height: auto;
+}
+
.content blockquote {
margin: 1rem 0;
padding-left: 1rem;
diff --git a/packages/chronicle/src/themes/paper/Page.tsx b/packages/chronicle/src/themes/paper/Page.tsx
index 113bcc1..bb66fe9 100644
--- a/packages/chronicle/src/themes/paper/Page.tsx
+++ b/packages/chronicle/src/themes/paper/Page.tsx
@@ -1,78 +1,71 @@
-'use client'
-
-import { useMemo } from 'react'
-import { usePathname } from 'next/navigation'
-import NextLink from 'next/link'
-import { Flex } from '@raystack/apsara'
-import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline'
-import type { ThemePageProps, PageTreeItem } from '@/types'
-import { Search } from '@/components/ui/search'
-import { ReadingProgress } from './ReadingProgress'
-import styles from './Page.module.css'
-
-function flattenTree(items: PageTreeItem[]): PageTreeItem[] {
- const result: PageTreeItem[] = []
- for (const item of items) {
- if (item.type === 'page' && item.url) result.push(item)
- if (item.children) result.push(...flattenTree(item.children))
- }
- return result
-}
-
-function findBreadcrumb(items: PageTreeItem[], slug: string[]): { label: string; href: string }[] {
- const result: { label: string; href: string }[] = []
- for (let i = 0; i < slug.length; i++) {
- const path = '/' + slug.slice(0, i + 1).join('/')
- const found = findInTree(items, path)
- result.push({ label: found?.name ?? slug[i], href: path })
- }
- return result
-}
-
-function findInTree(items: PageTreeItem[], path: string): PageTreeItem | undefined {
- for (const item of items) {
- if (item.url === path) return item
- if (item.children) {
- const found = findInTree(item.children, path)
- if (found) return found
- }
- }
- return undefined
-}
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
+import { Flex } from '@raystack/apsara';
+import { useMemo } from 'react';
+import { Link as RouterLink, useLocation } from 'react-router';
+import { getBreadcrumbItems } from 'fumadocs-core/breadcrumb';
+import { flattenTree } from 'fumadocs-core/page-tree';
+import { Search } from '@/components/ui/search';
+import type { ThemePageProps } from '@/types';
+import styles from './Page.module.css';
+import { ReadingProgress } from './ReadingProgress';
export function Page({ page, config, tree }: ThemePageProps) {
- const pathname = usePathname()
+ const { pathname } = useLocation();
const { prev, next, crumbs } = useMemo(() => {
- const pages = flattenTree(tree.children)
- const currentIndex = pages.findIndex((p) => p.url === pathname)
+ const pages = flattenTree(tree.children);
+ const currentIndex = pages.findIndex(p => p.url === pathname);
+ const breadcrumbItems = getBreadcrumbItems(
+ pathname,
+ tree,
+ { includePage: true }
+ );
return {
prev: currentIndex > 0 ? pages[currentIndex - 1] : null,
next: currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null,
- crumbs: findBreadcrumb(tree.children, page.slug),
- }
- }, [tree, pathname, page.slug])
+ crumbs: breadcrumbItems.map(item => ({
+ label: item.name,
+ href: item.url ?? pathname,
+ })),
+ };
+ }, [tree, pathname]);
return (
<>
-
-
+
+
{prev ? (
-
+
+
) : (
-
-
- {config.search?.enabled &&
+ {config.search?.enabled && (
+
-
([])
- const [containerHeight, setContainerHeight] = useState(0)
- const [ready, setReady] = useState(false)
- const [isScrollable, setIsScrollable] = useState(true)
- const containerRef = useRef(null)
- const scrollMarkerRef = useRef(null)
- const scrollPosRef = useRef(0)
+ const [headings, setHeadings] = useState([]);
+ const [containerHeight, setContainerHeight] = useState(0);
+ const [ready, setReady] = useState(false);
+ const [isScrollable, setIsScrollable] = useState(true);
+ const containerRef = useRef(null);
+ const scrollMarkerRef = useRef(null);
+ const scrollPosRef = useRef(0);
const { numTicks, maxPosition } = useMemo(
() => calculateTickBounds(containerHeight),
[containerHeight]
- )
+ );
const recalcHeadings = useCallback(() => {
- const article = document.querySelector(ARTICLE_SELECTOR)
- const container = containerRef.current
- if (!article || !container || !items.length) return
+ const article = document.querySelector(ARTICLE_SELECTOR);
+ const container = containerRef.current;
+ if (!article || !container || !items.length) return;
- const articleBox = article.getBoundingClientRect()
- const containerBox = container.getBoundingClientRect()
- const articleTop = articleBox.top + window.scrollY
+ const articleBox = article.getBoundingClientRect();
+ const containerBox = container.getBoundingClientRect();
+ const articleTop = articleBox.top + window.scrollY;
- const hasScroll = articleBox.height > window.innerHeight
- setIsScrollable(hasScroll)
- setContainerHeight(containerBox.height)
+ const hasScroll = articleBox.height > window.innerHeight;
+ setIsScrollable(hasScroll);
+ setContainerHeight(containerBox.height);
- const { maxPosition: maxPos } = calculateTickBounds(containerBox.height)
+ const { maxPosition: maxPos } = calculateTickBounds(containerBox.height);
const mapped = items
- .map((tocItem) => {
- const id = tocItem.url.startsWith('#') ? tocItem.url.slice(1) : tocItem.url
- const node = document.getElementById(id)
- if (!node) return null
-
- const { top } = node.getBoundingClientRect()
- const headingPosInArticle = top + window.scrollY - articleTop
- const progress = headingPosInArticle / articleBox.height
- const rawY = progress * maxPos
- const yPos = snapToTick(rawY, maxPos)
+ .map(tocItem => {
+ const id = tocItem.url.startsWith('#')
+ ? tocItem.url.slice(1)
+ : tocItem.url;
+ const node = document.getElementById(id);
+ if (!node) return null;
+
+ const { top } = node.getBoundingClientRect();
+ const headingPosInArticle = top + window.scrollY - articleTop;
+ const progress = headingPosInArticle / articleBox.height;
+ const rawY = progress * maxPos;
+ const yPos = snapToTick(rawY, maxPos);
return {
title: tocItem.title,
level: tocItem.depth,
id,
url: tocItem.url,
- yPosition: yPos,
- }
+ yPosition: yPos
+ };
})
- .filter((item): item is Heading => item !== null)
+ .filter((item): item is Heading => item !== null);
- const resolvedItems = resolveOverlaps(mapped, maxPos)
- setHeadings(resolvedItems)
- }, [items])
+ const resolvedItems = resolveOverlaps(mapped, maxPos);
+ setHeadings(resolvedItems);
+ }, [items]);
// Imperative DOM updates to avoid React re-render on every scroll event
const handleScroll = useCallback(() => {
- const article = document.querySelector(ARTICLE_SELECTOR)
- const container = containerRef.current
- const scrollMarker = scrollMarkerRef.current
- if (!article || !container || !scrollMarker) return
+ const article = document.querySelector(ARTICLE_SELECTOR);
+ const container = containerRef.current;
+ const scrollMarker = scrollMarkerRef.current;
+ if (!article || !container || !scrollMarker) return;
- const { top, height } = article.getBoundingClientRect()
- const { height: cHeight } = container.getBoundingClientRect()
- const viewportHeight = window.innerHeight
- const { maxPosition: maxPos } = calculateTickBounds(cHeight)
+ const { top, height } = article.getBoundingClientRect();
+ const { height: cHeight } = container.getBoundingClientRect();
+ const viewportHeight = window.innerHeight;
+ const { maxPosition: maxPos } = calculateTickBounds(cHeight);
- let newScrollPos: number
+ let newScrollPos: number;
if (top > 0) {
- newScrollPos = 0
+ newScrollPos = 0;
} else {
- const scrolled = Math.abs(top)
- const scrollRange = height - viewportHeight
- const progress = scrollRange > 0 ? Math.min(1, scrolled / scrollRange) : 0
- const rawPos = progress * maxPos
- newScrollPos = snapToTick(rawPos, maxPos)
+ const scrolled = Math.abs(top);
+ const scrollRange = height - viewportHeight;
+ const progress =
+ scrollRange > 0 ? Math.min(1, scrolled / scrollRange) : 0;
+ const rawPos = progress * maxPos;
+ newScrollPos = snapToTick(rawPos, maxPos);
}
- const prevScrollPos = scrollPosRef.current
+ const prevScrollPos = scrollPosRef.current;
if (newScrollPos !== prevScrollPos) {
- scrollPosRef.current = newScrollPos
- scrollMarker.style.top = `${newScrollPos}px`
+ scrollPosRef.current = newScrollPos;
+ scrollMarker.style.top = `${newScrollPos}px`;
- const textEl = scrollMarker.querySelector('[data-scroll-text]')
+ const textEl = scrollMarker.querySelector('[data-scroll-text]');
if (textEl) {
- textEl.textContent = (maxPos > 0 ? newScrollPos / maxPos : 0).toFixed(2)
+ textEl.textContent = (maxPos > 0 ? newScrollPos / maxPos : 0).toFixed(
+ 2
+ );
}
- const tickLines = container.querySelectorAll('[data-tick-line]')
- tickLines.forEach((tick) => {
- const tickPos = Number(tick.getAttribute('data-tick-pos'))
+ const tickLines = container.querySelectorAll('[data-tick-line]');
+ tickLines.forEach(tick => {
+ const tickPos = Number(tick.getAttribute('data-tick-pos'));
if (tickPos < newScrollPos) {
- tick.classList.remove(styles.tickLineAfter)
- tick.classList.add(styles.tickLineBefore)
+ tick.classList.remove(styles.tickLineAfter);
+ tick.classList.add(styles.tickLineBefore);
} else {
- tick.classList.remove(styles.tickLineBefore)
- tick.classList.add(styles.tickLineAfter)
+ tick.classList.remove(styles.tickLineBefore);
+ tick.classList.add(styles.tickLineAfter);
}
- })
+ });
}
- }, [])
+ }, []);
useEffect(() => {
- recalcHeadings()
- handleScroll()
- setReady(true)
+ recalcHeadings();
+ handleScroll();
+ setReady(true);
- const article = document.querySelector(ARTICLE_SELECTOR)
- let ro: ResizeObserver | undefined
+ const article = document.querySelector(ARTICLE_SELECTOR);
+ let ro: ResizeObserver | undefined;
if (article) {
ro = new ResizeObserver(() => {
- recalcHeadings()
- handleScroll()
- })
- ro.observe(article)
+ recalcHeadings();
+ handleScroll();
+ });
+ ro.observe(article);
}
- window.addEventListener('resize', recalcHeadings)
- window.addEventListener('scroll', handleScroll, { passive: true })
+ window.addEventListener('resize', recalcHeadings);
+ window.addEventListener('scroll', handleScroll, { passive: true });
return () => {
- ro?.disconnect()
- window.removeEventListener('resize', recalcHeadings)
- window.removeEventListener('scroll', handleScroll)
- }
- }, [recalcHeadings, handleScroll])
+ ro?.disconnect();
+ window.removeEventListener('resize', recalcHeadings);
+ window.removeEventListener('scroll', handleScroll);
+ };
+ }, [recalcHeadings, handleScroll]);
const scrollToTick = (y: number): void => {
- const article = document.querySelector(ARTICLE_SELECTOR)
- if (!article || maxPosition === 0) return
+ const article = document.querySelector(ARTICLE_SELECTOR);
+ if (!article || maxPosition === 0) return;
- const articleBox = article.getBoundingClientRect()
- const articleTop = articleBox.top + window.scrollY
- const progress = y / maxPosition
- const articlePos = progress * articleBox.height
- const targetScroll = articleTop + articlePos - NAV_HEIGHT
+ const articleBox = article.getBoundingClientRect();
+ const articleTop = articleBox.top + window.scrollY;
+ const progress = y / maxPosition;
+ const articlePos = progress * articleBox.height;
+ const targetScroll = articleTop + articlePos - NAV_HEIGHT;
- window.scrollTo({ top: Math.max(0, targetScroll), behavior: 'smooth' })
- }
+ window.scrollTo({ top: Math.max(0, targetScroll), behavior: 'smooth' });
+ };
const scrollToHeading = (id: string): void => {
- const element = document.getElementById(id)
- if (!element) return
+ const element = document.getElementById(id);
+ if (!element) return;
- const elementTop = element.getBoundingClientRect().top + window.scrollY
- window.scrollTo({ top: Math.max(0, elementTop - NAV_HEIGHT), behavior: 'smooth' })
- }
+ const elementTop = element.getBoundingClientRect().top + window.scrollY;
+ window.scrollTo({
+ top: Math.max(0, elementTop - NAV_HEIGHT),
+ behavior: 'smooth'
+ });
+ };
const ticks = useMemo(
() => Array.from({ length: numTicks }, (_, i) => i * TICK_HEIGHT),
[numTicks]
- )
+ );
if (!isScrollable || ticks.length < 2) {
- return
+ return ;
}
return (
- {result.type === "heading" ? (
+ {result.type === 'heading' ? (
<>
-
-
@@ -141,7 +143,9 @@ export function Search({ className }: SearchProps) {
) : (
-
)}
@@ -158,49 +162,57 @@ export function Search({ className }: SearchProps) {
function deduplicateByUrl(results: SortedResult[]): SortedResult[] {
const seen = new Set
+
+
+ ({ content: null, toc: [] })}
+ >
+
+
+
+
+
+ ,
+ );
+
+ 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' },
+ });
+ },
+};
diff --git a/packages/chronicle/src/server/routes/llms.txt.ts b/packages/chronicle/src/server/routes/llms.txt.ts
new file mode 100644
index 0000000..aafabf7
--- /dev/null
+++ b/packages/chronicle/src/server/routes/llms.txt.ts
@@ -0,0 +1,21 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { getPages, extractFrontmatter } from '@/lib/source';
+
+export default defineHandler(async event => {
+ const config = loadConfig();
+
+ if (!config.llms?.enabled) {
+ throw new HTTPError({ status: 404, message: 'Not Found' });
+ }
+
+ const pages = await getPages();
+ const index = pages.map(p => {
+ const fm = extractFrontmatter(p);
+ return `- [${fm.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;
+});
diff --git a/packages/chronicle/src/server/routes/og.tsx b/packages/chronicle/src/server/routes/og.tsx
new file mode 100644
index 0000000..2fb15ca
--- /dev/null
+++ b/packages/chronicle/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
+
,
+ {
+ 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;
+});
diff --git a/packages/chronicle/src/server/routes/robots.txt.ts b/packages/chronicle/src/server/routes/robots.txt.ts
new file mode 100644
index 0000000..31c06d0
--- /dev/null
+++ b/packages/chronicle/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;
+});
diff --git a/packages/chronicle/src/server/routes/sitemap.xml.ts b/packages/chronicle/src/server/routes/sitemap.xml.ts
new file mode 100644
index 0000000..ea93437
--- /dev/null
+++ b/packages/chronicle/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 '
+ {siteName}
+
+
+ {title}
+
+ {description && (
+
+ {description}
+
+ )}
+ -
- {item.children.map((child) => (
-
{children}
+
+ {children}
+
- {page.content}
-
+ {page.content}
{ticks.map((y, i) => (
- = {
default: defaultTheme,
- paper: paperTheme,
-}
+ paper: paperTheme
+};
export function getTheme(name?: string): Theme {
- if (!name || !themes[name]) return defaultTheme
+ if (!name || !themes[name]) return defaultTheme;
- return themes[name]
+ return themes[name];
}
diff --git a/packages/chronicle/src/types/content.ts b/packages/chronicle/src/types/content.ts
index a9147e7..0ca7ecf 100644
--- a/packages/chronicle/src/types/content.ts
+++ b/packages/chronicle/src/types/content.ts
@@ -1,4 +1,8 @@
import type { ReactNode } from 'react'
+import type { TableOfContents } from 'fumadocs-core/toc'
+
+export type { Root, Node, Item, Folder, Separator } from 'fumadocs-core/page-tree'
+export type { TOCItemType, TableOfContents } from 'fumadocs-core/toc'
export interface Frontmatter {
title: string
@@ -12,25 +16,5 @@ export interface Page {
slug: string[]
frontmatter: Frontmatter
content: ReactNode
- toc: TocItem[]
-}
-
-export interface TocItem {
- title: string
- url: string
- depth: number
-}
-
-export interface PageTreeItem {
- type: 'page' | 'folder' | 'separator'
- name: string
- url?: string
- order?: number
- icon?: string
- children?: PageTreeItem[]
-}
-
-export interface PageTree {
- name: string
- children: PageTreeItem[]
+ toc: TableOfContents
}
diff --git a/packages/chronicle/src/types/globals.d.ts b/packages/chronicle/src/types/globals.d.ts
new file mode 100644
index 0000000..59d30f7
--- /dev/null
+++ b/packages/chronicle/src/types/globals.d.ts
@@ -0,0 +1,4 @@
+// Vite build-time constants (injected via define in vite-config.ts)
+declare const __CHRONICLE_CONTENT_DIR__: string
+declare const __CHRONICLE_PROJECT_ROOT__: string
+declare const __CHRONICLE_CONFIG_RAW__: string | null
diff --git a/packages/chronicle/src/types/theme.ts b/packages/chronicle/src/types/theme.ts
index 206ac7d..c948bd1 100644
--- a/packages/chronicle/src/types/theme.ts
+++ b/packages/chronicle/src/types/theme.ts
@@ -1,18 +1,19 @@
import type { ReactNode } from 'react'
+import type { Root } from 'fumadocs-core/page-tree'
import type { ChronicleConfig } from './config'
-import type { Page, PageTree } from './content'
+import type { Page } from './content'
export interface ThemeLayoutProps {
children: ReactNode
config: ChronicleConfig
- tree: PageTree
+ tree: Root
classNames?: { layout?: string; body?: string; sidebar?: string; content?: string }
}
export interface ThemePageProps {
page: Page
config: ChronicleConfig
- tree: PageTree
+ tree: Root
}
export interface Theme {
diff --git a/packages/chronicle/tsconfig.json b/packages/chronicle/tsconfig.json
index b21ec05..50ac79e 100644
--- a/packages/chronicle/tsconfig.json
+++ b/packages/chronicle/tsconfig.json
@@ -21,10 +21,9 @@
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"moduleResolution": "bundler",
"paths": {
- "@/*": ["./src/*"],
- "@/.source/*": ["./.source/*"]
+ "@/*": ["./src/*"]
}
},
- "include": ["src", ".source", "source.config.ts"],
+ "include": ["src"],
"exclude": ["node_modules", "dist"]
}
-
-
- )
+ );
}
diff --git a/packages/chronicle/src/themes/paper/index.ts b/packages/chronicle/src/themes/paper/index.ts
index 0229a4d..65543a5 100644
--- a/packages/chronicle/src/themes/paper/index.ts
+++ b/packages/chronicle/src/themes/paper/index.ts
@@ -1,8 +1,8 @@
-import { Layout } from './Layout'
-import { Page } from './Page'
-import type { Theme } from '@/types'
+import type { Theme } from '@/types';
+import { Layout } from './Layout';
+import { Page } from './Page';
export const paperTheme: Theme = {
Layout,
- Page,
-}
+ Page
+};
diff --git a/packages/chronicle/src/themes/registry.ts b/packages/chronicle/src/themes/registry.ts
index ec48d76..25c2db2 100644
--- a/packages/chronicle/src/themes/registry.ts
+++ b/packages/chronicle/src/themes/registry.ts
@@ -1,14 +1,14 @@
-import type { Theme } from '@/types'
-import { defaultTheme } from './default'
-import { paperTheme } from './paper'
+import type { Theme } from '@/types';
+import { defaultTheme } from './default';
+import { paperTheme } from './paper';
const themes: Record scrollToTick(y)} />
+
+
+
scrollToTick(y)}
+ />
))}
@@ -246,16 +265,16 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
top: `${h.yPosition - 6}px`,
right: '24px',
zIndex: h.level < 4 ? 10 : 0,
- transitionDelay: `${50 * i}ms`,
+ transitionDelay: `${50 * i}ms`
}}
>
{
- e.preventDefault()
- e.stopPropagation()
- scrollToHeading(h.id)
+ onClick={e => {
+ e.preventDefault();
+ e.stopPropagation();
+ scrollToHeading(h.id);
}}
>
{h.title}
@@ -270,7 +289,7 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
className={styles.connectingLine}
style={{
top: `${h.yPosition}px`,
- width: `${Math.max(4, (3 - h.level) * 4 + 12)}px`,
+ width: `${Math.max(4, (3 - h.level) * 4 + 12)}px`
}}
/>
))}
@@ -279,7 +298,9 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
ref={scrollMarkerRef}
className={cx(
styles.scrollMarkerContainer,
- ready ? styles.scrollMarkerContainerReady : styles.scrollMarkerContainerNotReady
+ ready
+ ? styles.scrollMarkerContainerReady
+ : styles.scrollMarkerContainerNotReady
)}
style={{ top: '0px' }}
>
@@ -290,5 +311,5 @@ export function ReadingProgress({ items }: ReadingProgressProps) {