@raystack/chronicle 0.5.3 → 0.6.0

package/src/lib/route-resolver.ts

@@ -0,0 +1,73 @@
+import type { ChronicleConfig } from '@/types'
+import { getLatestContentRoots, getVersionContentRoots } from './config'
+import { type VersionContext, resolveVersionFromUrl } from './version-source'
+
+export const RouteType = {
+  Redirect: 'redirect',
+  DocsIndex: 'docs-index',
+  DocsPage: 'docs-page',
+  ApiIndex: 'api-index',
+  ApiPage: 'api-page',
+} as const
+
+export type RouteType = (typeof RouteType)[keyof typeof RouteType]
+
+export type Route =
+  | { type: typeof RouteType.Redirect; to: string; status: 302 }
+  | { type: typeof RouteType.DocsIndex; version: VersionContext }
+  | { type: typeof RouteType.DocsPage; version: VersionContext; slug: string[] }
+  | { type: typeof RouteType.ApiIndex; version: VersionContext }
+  | { type: typeof RouteType.ApiPage; version: VersionContext; slug: string[] }
+
+function contentDirsFor(
+  config: ChronicleConfig,
+  version: VersionContext,
+): string[] {
+  if (version.dir === null) {
+    return getLatestContentRoots(config).map((root) => root.contentDir)
+  }
+  return getVersionContentRoots(config, version.dir).map(
+    (root) => root.contentDir,
+  )
+}
+
+function isLandingEnabled(
+  config: ChronicleConfig,
+  version: VersionContext,
+): boolean {
+  if (version.dir === null) return config.latest?.landing === true
+  return (
+    config.versions?.find((v) => v.dir === version.dir)?.landing === true
+  )
+}
+
+export function resolveRoute(
+  pathname: string,
+  config: ChronicleConfig,
+): Route {
+  const parts = pathname.split('/').filter(Boolean)
+  const version = resolveVersionFromUrl(pathname, config)
+  const remainder =
+    version.dir !== null && parts[0] === version.dir ? parts.slice(1) : parts
+
+  if (remainder[0] === 'apis') {
+    const slug = remainder.slice(1)
+    if (slug.length === 0) return { type: RouteType.ApiIndex, version }
+    return { type: RouteType.ApiPage, version, slug }
+  }
+
+  if (remainder.length === 0) {
+    if (isLandingEnabled(config, version)) {
+      return { type: RouteType.DocsIndex, version }
+    }
+    const dirs = contentDirsFor(config, version)
+    if (dirs.length === 0) return { type: RouteType.DocsIndex, version }
+    return {
+      type: RouteType.Redirect,
+      to: `${version.urlPrefix}/${dirs[0]}`,
+      status: 302,
+    }
+  }
+
+  return { type: RouteType.DocsPage, version, slug: parts }
+}

package/src/lib/source.ts

@@ -1,8 +1,20 @@
 import { loader } from 'fumadocs-core/source';
+import { flattenTree } from 'fumadocs-core/page-tree';
 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';
+import {
+  getLatestContentRoots,
+  getVersionContentRoots,
+  loadConfig,
+} from './config';
+import {
+  filterPagesByVersion,
+  filterPageTreeByVersion,
+  resolveVersionFromUrl,
+  type VersionContext,
+} from './version-source';
+import type { Frontmatter, PageNav, PageNavLink } from '@/types';
 
 const CONTENT_PREFIX = '../../.content/';
 
@@ -33,14 +45,50 @@ function buildFiles() {
     });
   }
 
+  const userMetaPaths = new Set<string>();
   for (const [key, data] of Object.entries(metaGlob)) {
     const relativePath = key.slice(CONTENT_PREFIX.length);
+    userMetaPaths.add(relativePath);
     files.push({ type: 'meta', path: relativePath, data: data ?? {} });
   }
 
+  for (const entry of buildSyntheticMeta()) {
+    if (userMetaPaths.has(entry.path)) continue;
+    files.push(entry);
+  }
+
   return files;
 }
 
+function buildSyntheticMeta(): {
+  type: 'meta';
+  path: string;
+  data: Record<string, unknown>;
+}[] {
+  const config = loadConfig();
+  const entries: { type: 'meta'; path: string; data: Record<string, unknown> }[] = [];
+
+  for (const root of getLatestContentRoots(config)) {
+    entries.push({
+      type: 'meta',
+      path: `${root.contentDir}/meta.json`,
+      data: { title: root.contentLabel, root: true },
+    });
+  }
+
+  for (const version of config.versions ?? []) {
+    for (const root of getVersionContentRoots(config, version.dir)) {
+      entries.push({
+        type: 'meta',
+        path: `${version.dir}/${root.contentDir}/meta.json`,
+        data: { title: root.contentLabel, root: true },
+      });
+    }
+  }
+
+  return entries;
+}
+
 let cachedSource: ReturnType<typeof loader> | null = null;
 
 async function getSource() {
@@ -105,6 +153,51 @@ export async function getPage(slugs?: string[]) {
   return s.getPage(slugs);
 }
 
+export async function getPageTreeForVersion(ctx: VersionContext): Promise<Root> {
+  const tree = await getPageTree();
+  return filterPageTreeByVersion(tree, ctx, loadConfig());
+}
+
+export async function getPagesForVersion(ctx: VersionContext) {
+  const pages = await getPages();
+  return filterPagesByVersion(pages, ctx, loadConfig());
+}
+
+export function getVersionContextForUrl(url: string): VersionContext {
+  return resolveVersionFromUrl(url, loadConfig());
+}
+
+export type { VersionContext } from './version-source';
+
+function titleFromUrl(url: string): string {
+  if (url === '/') return 'Home';
+  const last = url.split('/').filter(Boolean).pop();
+  if (!last) return 'Home';
+  return last
+    .split('-')
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+export async function getPageNav(slug: string[], tree?: Root): Promise<PageNav> {
+  const resolvedTree = tree ?? (await getPageTree());
+  const pages = flattenTree(resolvedTree.children);
+  const url = slug.length === 0 ? '/' : `/${slug.join('/')}`;
+  const i = pages.findIndex(p => p.url === url);
+  if (i < 0) return { prev: null, next: null };
+  const toLink = (p: (typeof pages)[number]): PageNavLink => ({
+    url: p.url,
+    title:
+      typeof p.name === 'string' && p.name.length > 0
+        ? p.name
+        : titleFromUrl(p.url)
+  });
+  return {
+    prev: i > 0 ? toLink(pages[i - 1]) : null,
+    next: i < pages.length - 1 ? toLink(pages[i + 1]) : null
+  };
+}
+
 export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {
   const d = page.data as Record<string, unknown>;
   return {

package/src/lib/version-source.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test } from 'bun:test'
+import type { Folder, Item, Root } from 'fumadocs-core/page-tree'
+import { type ChronicleConfig, chronicleConfigSchema } from '@/types'
+import {
+  filterPagesByVersion,
+  filterPageTreeByContentDir,
+  filterPageTreeByVersion,
+  LATEST_CONTEXT,
+  resolveVersionFromUrl,
+} from './version-source'
+
+function makeConfig(): ChronicleConfig {
+  return chronicleConfigSchema.parse({
+    site: { title: 'x' },
+    content: [{ dir: 'docs', label: 'Docs' }],
+    latest: { label: '3.0' },
+    versions: [
+      {
+        dir: 'v2',
+        label: '2.0',
+        content: [{ dir: 'docs', label: 'Docs' }],
+      },
+      {
+        dir: 'v1',
+        label: '1.0',
+        content: [
+          { dir: 'docs', label: 'Docs' },
+          { dir: 'dev', label: 'Dev' },
+        ],
+      },
+    ],
+  })
+}
+
+function page(url: string): Item {
+  return { type: 'page', name: url, url }
+}
+
+function folder(name: string, children: (Item | Folder)[]): Folder {
+  return { type: 'folder', name, children }
+}
+
+describe('resolveVersionFromUrl', () => {
+  const config = makeConfig()
+
+  test('returns latest context for unprefixed URLs', () => {
+    expect(resolveVersionFromUrl('/docs/getting-started', config)).toEqual(
+      LATEST_CONTEXT,
+    )
+    expect(resolveVersionFromUrl('/', config)).toEqual(LATEST_CONTEXT)
+  })
+
+  test('returns version context when URL matches a version prefix', () => {
+    expect(resolveVersionFromUrl('/v1/docs/intro', config)).toEqual({
+      dir: 'v1',
+      urlPrefix: '/v1',
+    })
+    expect(resolveVersionFromUrl('/v2', config)).toEqual({
+      dir: 'v2',
+      urlPrefix: '/v2',
+    })
+  })
+
+  test('does not match a version when prefix is only a substring', () => {
+    expect(resolveVersionFromUrl('/v1beta/docs', config)).toEqual(LATEST_CONTEXT)
+  })
+})
+
+describe('filterPagesByVersion', () => {
+  const config = makeConfig()
+  const pages = [
+    { url: '/docs/a' },
+    { url: '/docs/b' },
+    { url: '/v1/docs/a' },
+    { url: '/v1/dev/b' },
+    { url: '/v2/docs/a' },
+  ]
+
+  test('latest excludes all versioned pages', () => {
+    expect(filterPagesByVersion(pages, LATEST_CONTEXT, config)).toEqual([
+      { url: '/docs/a' },
+      { url: '/docs/b' },
+    ])
+  })
+
+  test('version returns only pages under its prefix', () => {
+    expect(
+      filterPagesByVersion(pages, { dir: 'v1', urlPrefix: '/v1' }, config),
+    ).toEqual([{ url: '/v1/docs/a' }, { url: '/v1/dev/b' }])
+  })
+})
+
+describe('filterPageTreeByVersion', () => {
+  const config = makeConfig()
+  const latestDocs = folder('docs', [page('/docs/a'), page('/docs/b')])
+  const v1Folder = folder('v1', [
+    folder('docs', [page('/v1/docs/a')]),
+    folder('dev', [page('/v1/dev/a')]),
+  ])
+  const v2Folder = folder('v2', [folder('docs', [page('/v2/docs/a')])])
+
+  const tree: Root = {
+    name: 'root',
+    children: [latestDocs, v1Folder, v2Folder],
+  }
+
+  test('latest drops version folders', () => {
+    const filtered = filterPageTreeByVersion(tree, LATEST_CONTEXT, config)
+    expect(filtered.children).toEqual([latestDocs])
+  })
+
+  test('version returns the inner children of its folder', () => {
+    const filtered = filterPageTreeByVersion(
+      tree,
+      { dir: 'v1', urlPrefix: '/v1' },
+      config,
+    )
+    expect(filtered.children).toEqual(v1Folder.children)
+  })
+
+  test('version returns empty children when the version folder is absent', () => {
+    const filtered = filterPageTreeByVersion(
+      { name: 'root', children: [latestDocs] },
+      { dir: 'v1', urlPrefix: '/v1' },
+      config,
+    )
+    expect(filtered.children).toEqual([])
+  })
+})
+
+describe('filterPageTreeByContentDir', () => {
+  const latestDocs = folder('docs', [page('/docs/a'), page('/docs/b')])
+  const latestDev = folder('dev', [page('/dev/x')])
+  const latestTree: Root = {
+    name: 'root',
+    children: [latestDocs, latestDev],
+  }
+
+  test('null contentDir returns tree unchanged', () => {
+    const out = filterPageTreeByContentDir(latestTree, LATEST_CONTEXT, null)
+    expect(out).toBe(latestTree)
+  })
+
+  test('returns just the matching content folder children (latest)', () => {
+    const out = filterPageTreeByContentDir(latestTree, LATEST_CONTEXT, 'docs')
+    expect(out.children).toEqual(latestDocs.children)
+  })
+
+  test('returns empty children when content dir is absent', () => {
+    const out = filterPageTreeByContentDir(latestTree, LATEST_CONTEXT, 'missing')
+    expect(out.children).toEqual([])
+  })
+
+  test('uses version urlPrefix to disambiguate within a version', () => {
+    const v1Docs = folder('docs', [page('/v1/docs/a')])
+    const v1Dev = folder('dev', [page('/v1/dev/x')])
+    const ctx = { dir: 'v1', urlPrefix: '/v1' }
+    const tree: Root = { name: 'root', children: [v1Docs, v1Dev] }
+    expect(
+      filterPageTreeByContentDir(tree, ctx, 'dev').children,
+    ).toEqual(v1Dev.children)
+  })
+})

package/src/lib/version-source.ts

@@ -0,0 +1,101 @@
+import type { Folder, Node, Root } from 'fumadocs-core/page-tree'
+import type { ChronicleConfig } from '@/types'
+
+export interface VersionContext {
+  dir: string | null
+  urlPrefix: string
+}
+
+export const LATEST_CONTEXT: VersionContext = { dir: null, urlPrefix: '' }
+
+export function resolveVersionFromUrl(
+  url: string,
+  config: ChronicleConfig,
+): VersionContext {
+  for (const v of config.versions ?? []) {
+    const prefix = `/${v.dir}`
+    if (url === prefix || url.startsWith(`${prefix}/`)) {
+      return { dir: v.dir, urlPrefix: prefix }
+    }
+  }
+  return LATEST_CONTEXT
+}
+
+function versionPrefixes(config: ChronicleConfig): string[] {
+  return (config.versions ?? []).map((v) => `/${v.dir}`)
+}
+
+function isUnderPrefix(url: string, prefix: string): boolean {
+  return url === prefix || url.startsWith(`${prefix}/`)
+}
+
+export function filterPagesByVersion<T extends { url: string }>(
+  pages: T[],
+  ctx: VersionContext,
+  config: ChronicleConfig,
+): T[] {
+  if (ctx.dir !== null) {
+    return pages.filter((p) => isUnderPrefix(p.url, ctx.urlPrefix))
+  }
+  const prefixes = versionPrefixes(config)
+  return pages.filter((p) => !prefixes.some((pre) => isUnderPrefix(p.url, pre)))
+}
+
+function nodeUrls(node: Node): string[] {
+  if (node.type === 'page') return [node.url]
+  if (node.type === 'folder') {
+    const urls: string[] = []
+    if (node.index) urls.push(node.index.url)
+    for (const child of node.children) urls.push(...nodeUrls(child))
+    return urls
+  }
+  return []
+}
+
+function nodeMatchesVersion(
+  node: Node,
+  ctx: VersionContext,
+  config: ChronicleConfig,
+): boolean {
+  const urls = nodeUrls(node)
+  if (urls.length === 0) return ctx.dir === null
+  if (ctx.dir !== null) {
+    return urls.every((u) => isUnderPrefix(u, ctx.urlPrefix))
+  }
+  const prefixes = versionPrefixes(config)
+  return urls.every((u) => !prefixes.some((pre) => isUnderPrefix(u, pre)))
+}
+
+export function filterPageTreeByVersion(
+  tree: Root,
+  ctx: VersionContext,
+  config: ChronicleConfig,
+): Root {
+  if (ctx.dir !== null) {
+    const versionFolder = tree.children.find(
+      (n): n is Folder =>
+        n.type === 'folder' && nodeMatchesVersion(n, ctx, config),
+    )
+    return { ...tree, children: versionFolder ? versionFolder.children : [] }
+  }
+  return {
+    ...tree,
+    children: tree.children.filter((n) => nodeMatchesVersion(n, ctx, config)),
+  }
+}
+
+export function filterPageTreeByContentDir(
+  tree: Root,
+  ctx: VersionContext,
+  contentDir: string | null,
+): Root {
+  if (contentDir === null) return tree
+  const expectedPrefix = `${ctx.urlPrefix}/${contentDir}`
+  const match = tree.children.find((n): n is Folder => {
+    if (n.type !== 'folder') return false
+    const urls = nodeUrls(n)
+    return urls.length > 0 && urls.every((u) => isUnderPrefix(u, expectedPrefix))
+  })
+  if (!match) return { ...tree, children: [] }
+  return { ...tree, children: match.children }
+}

package/src/pages/ApiPage.tsx

@@ -18,7 +18,7 @@ export function ApiPage({ slug }: ApiPageProps) {
       <>
         <Head
           title='API Reference'
-          description={`API documentation for ${config.title}`}
+          description={`API documentation for ${config.site.title}`}
           config={config}
         />
         <ApiLanding specs={apiSpecs} />

package/src/pages/DocsLayout.tsx

@@ -1,17 +1,38 @@
 import type { ReactNode } from 'react';
+import { useLocation } from 'react-router';
 import { usePageContext } from '@/lib/page-context';
+import { getActiveContentDir } from '@/lib/navigation';
+import {
+  filterPageTreeByContentDir,
+  filterPageTreeByVersion,
+} from '@/lib/version-source';
 import { getTheme } from '@/themes/registry';
 
 interface DocsLayoutProps {
   children: ReactNode;
+  hideSidebar?: boolean;
 }
 
-export function DocsLayout({ children }: DocsLayoutProps) {
-  const { config, tree } = usePageContext();
+export function DocsLayout({ children, hideSidebar }: DocsLayoutProps) {
+  const { config, tree, version } = usePageContext();
+  const { pathname } = useLocation();
   const { Layout, className } = getTheme(config.theme?.name);
 
+  const activeContentDir = getActiveContentDir(pathname, config);
+  const versionScoped = filterPageTreeByVersion(tree, version, config);
+  const scopedTree = filterPageTreeByContentDir(
+    versionScoped,
+    version,
+    activeContentDir,
+  );
+
   return (
-    <Layout config={config} tree={tree} classNames={{ layout: className }}>
+    <Layout
+      config={config}
+      tree={scopedTree}
+      hideSidebar={hideSidebar}
+      classNames={{ layout: className }}
+    >
       {children}
     </Layout>
   );

package/src/pages/DocsPage.tsx

@@ -1,5 +1,6 @@
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
+import { NotFound } from '@/pages/NotFound';
 import { getTheme } from '@/themes/registry';
 
 interface DocsPageProps {
@@ -7,12 +8,15 @@ interface DocsPageProps {
 }
 
 export function DocsPage({ slug }: DocsPageProps) {
-  const { config, tree, page } = usePageContext();
+  const { config, tree, page, errorStatus } = usePageContext();
 
+  if (errorStatus === 404) return <NotFound />;
+  if (errorStatus) return <NotFound />;
   if (!page) return null;
 
   const { Page } = getTheme(config.theme?.name);
   const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined;
+  const markdownHref = `/${slug.join('/')}.md`;
 
   return (
     <>
@@ -20,6 +24,7 @@ export function DocsPage({ slug }: DocsPageProps) {
         title={page.frontmatter.title}
         description={page.frontmatter.description}
         config={config}
+        markdownHref={markdownHref}
         jsonLd={{
           '@context': 'https://schema.org',
           '@type': 'Article',
@@ -29,12 +34,7 @@ export function DocsPage({ slug }: DocsPageProps) {
         }}
       />
       <Page
-        page={{
-          slug: page.slug,
-          frontmatter: page.frontmatter,
-          content: page.content,
-          toc: page.toc
-        }}
+        page={page}
         config={config}
         tree={tree}
       />

package/src/pages/LandingPage.module.css

@@ -0,0 +1,56 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-8);
+  padding: var(--rs-space-9) var(--rs-space-7);
+  max-width: 960px;
+  margin: 0 auto;
+}
+
+.title {
+  font-size: var(--rs-font-size-h3);
+  font-weight: 600;
+  color: var(--rs-color-foreground-base-primary);
+  margin: 0;
+}
+
+.description {
+  font-size: var(--rs-font-size-regular);
+  color: var(--rs-color-foreground-base-secondary);
+  margin: 0;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+  gap: var(--rs-space-6);
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-3);
+  padding: var(--rs-space-6);
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-3);
+  text-decoration: none;
+  color: inherit;
+  background: var(--rs-color-background-base-primary);
+  transition: border-color 0.15s ease, background 0.15s ease;
+}
+
+.card:hover {
+  border-color: var(--rs-color-border-accent-primary);
+  background: var(--rs-color-background-neutral-secondary);
+}
+
+.cardLabel {
+  font-size: var(--rs-font-size-large);
+  font-weight: 500;
+}
+
+.cardHref {
+  font-size: var(--rs-font-size-small);
+  color: var(--rs-color-foreground-base-secondary);
+  font-family: var(--rs-font-family-mono);
+}

package/src/pages/LandingPage.tsx

@@ -0,0 +1,39 @@
+import { Link as RouterLink } from 'react-router';
+import { getLandingEntries } from '@/lib/config';
+import { usePageContext } from '@/lib/page-context';
+import styles from './LandingPage.module.css';
+
+export function LandingPage() {
+  const { config, version } = usePageContext();
+  const entries = getLandingEntries(config, version.dir);
+
+  const heading = version.dir === null
+    ? config.site.title
+    : `${config.site.title} — ${versionLabel(config, version.dir)}`;
+
+  return (
+    <div className={styles.root}>
+      <h1 className={styles.title}>{heading}</h1>
+      {config.site.description ? (
+        <p className={styles.description}>{config.site.description}</p>
+      ) : null}
+      <div className={styles.grid}>
+        {entries.map((entry) => (
+          <RouterLink key={entry.href} to={entry.href} className={styles.card}>
+            <span className={styles.cardLabel}>{entry.label}</span>
+            <span className={styles.cardHref}>{entry.href}</span>
+          </RouterLink>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function versionLabel(
+  config: ReturnType<typeof usePageContext>['config'],
+  versionDir: string,
+): string {
+  return (
+    config.versions?.find((v) => v.dir === versionDir)?.label ?? versionDir
+  );
+}

package/src/pages/NotFound.module.css

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

package/src/pages/NotFound.tsx

@@ -1,17 +1,14 @@
-import { Flex, Headline, Text } from '@raystack/apsara';
+import { DocumentTextIcon } from '@heroicons/react/24/outline';
+import { EmptyState } from '@raystack/apsara';
+import styles from './NotFound.module.css';
 
 export function NotFound() {
   return (
-    <Flex
-      direction='column'
-      align='center'
-      justify='center'
-      style={{ minHeight: '60vh' }}
-    >
-      <Headline size='large' as='h1'>
-        404
-      </Headline>
-      <Text size={3}>Page not found</Text>
-    </Flex>
+    <EmptyState
+      icon={<DocumentTextIcon width={32} height={32} />}
+      heading="404"
+      subHeading="Page not found"
+      classNames={{ container: styles.emptyState }}
+    />
   );
 }