feat: support order in meta.json and folder redirect (#62)

* feat: add index_page config for content directories

Set index_page in chronicle.yaml content entry to specify which page
to redirect to when visiting a content root (e.g., /docs).
Falls back to first page in tree when not set.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: restore isContentRoot with some() check

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: use contentConfig with explicit isContentRoot check

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: support order in meta.json and folder redirect to first child

- meta.json order field sorts folders in sidebar
- Visiting a folder URL redirects to its first sorted child page
- Folder order from meta.json takes priority over index page frontmatter

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rsbh

packages/chronicle/src/lib/source.ts

@@ -118,41 +118,60 @@ export function invalidate() {
   cachedNavMap = null;
 }
 
-function getOrder(node: Node, orderMap: Map<string, number>): number | undefined {
-  if (node.type === 'page') return orderMap.get(node.url);
-  if (node.type === 'folder' && node.index) return orderMap.get(node.index.url);
+function getOrder(node: Node, pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): number | undefined {
+  if (node.type === 'page') return pageOrderMap.get(node.url);
+  if (node.type === 'folder') {
+    if (node.index) {
+      const fromMeta = folderOrderMap.get(node.index.url);
+      if (fromMeta !== undefined) return fromMeta;
+      return pageOrderMap.get(node.index.url);
+    }
+  }
   return undefined;
 }
 
-function sortNodes(nodes: Node[], orderMap: Map<string, number>): Node[] {
+function sortNodes(nodes: Node[], pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): Node[] {
   return [...nodes]
     .map(n =>
       n.type === 'folder'
-        ? ({ ...n, children: sortNodes(n.children, orderMap) } as Folder)
+        ? ({ ...n, children: sortNodes(n.children, pageOrderMap, folderOrderMap) } as Folder)
         : n
     )
     .sort(
       (a, b) =>
-        (getOrder(a, orderMap) ?? Number.MAX_SAFE_INTEGER) -
-        (getOrder(b, orderMap) ?? Number.MAX_SAFE_INTEGER)
+        (getOrder(a, pageOrderMap, folderOrderMap) ?? Number.MAX_SAFE_INTEGER) -
+        (getOrder(b, pageOrderMap, folderOrderMap) ?? Number.MAX_SAFE_INTEGER)
     );
 }
 
-function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
-  const orderMap = new Map<string, number>();
+function buildFolderOrderMap(metaFiles: { path: string; data: Record<string, unknown> }[]): Map<string, number> {
+  const map = new Map<string, number>();
+  for (const meta of metaFiles) {
+    const order = meta.data.order as number | undefined;
+    if (order === undefined) continue;
+    const folderUrl = '/' + meta.path.replace(/\/meta\.json$/, '');
+    map.set(folderUrl, order);
+  }
+  return map;
+}
+
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[], metaFiles: { path: string; data: Record<string, unknown> }[]): Root {
+  const pageOrderMap = new Map<string, number>();
   for (const page of pages) {
     const d = page.data as Record<string, unknown>;
     const order = d.order as number | undefined;
-    if (order !== undefined) orderMap.set(page.url, order);
-    if (page.url === '/') orderMap.set('/', order ?? 0);
+    if (order !== undefined) pageOrderMap.set(page.url, order);
+    if (page.url === '/') pageOrderMap.set('/', order ?? 0);
   }
-  return { ...tree, children: sortNodes(tree.children, orderMap) };
+  const folderOrderMap = buildFolderOrderMap(metaFiles);
+  return { ...tree, children: sortNodes(tree.children, pageOrderMap, folderOrderMap) };
 }
 
 export async function getPageTree(): Promise<Root> {
   if (cachedTree) return cachedTree;
   const s = await getSource();
-  cachedTree = sortTreeByOrder(s.pageTree as Root, s.getPages());
+  const metaFiles = buildFiles().filter(f => f.type === 'meta') as { path: string; data: Record<string, unknown> }[];
+  cachedTree = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
   return cachedTree;
 }
 

packages/chronicle/src/pages/DocsPage.tsx

@@ -16,6 +16,18 @@ function getFirstPageUrl(nodes: Node[]): string | null {
   return null;
 }
 
+function findFolderFirstPage(nodes: Node[], pathname: string): string | null {
+  for (const node of nodes) {
+    if (node.type === 'folder') {
+      const folderUrl = node.index?.url;
+      if (folderUrl === pathname) return getFirstPageUrl(node.children);
+      const found = findFolderFirstPage(node.children, pathname);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
 interface DocsPageProps {
   slug: string[];
 }
@@ -24,11 +36,18 @@ export function DocsPage({ slug }: DocsPageProps) {
   const { config, tree, page, isLoading, errorStatus } = usePageContext();
 
   if (errorStatus === 404) {
-    const isContentRoot = config.content?.some(c => slug.length === 1 && slug[0] === c.dir);
+    const pathname = `/${slug.join('/')}`;
+    const contentConfig = config.content?.find(c => c.dir === slug[0]);
+    const isContentRoot = slug.length === 1 && slug[0] === contentConfig?.dir;
+    if (contentConfig?.index_page) {
+      return <Navigate to={`/${contentConfig.dir}/${contentConfig.index_page}`} replace />;
+    }
     if (isContentRoot) {
       const firstUrl = getFirstPageUrl(tree.children);
       if (firstUrl) return <Navigate to={firstUrl} replace />;
     }
+    const folderFirstUrl = findFolderFirstPage(tree.children, pathname);
+    if (folderFirstUrl) return <Navigate to={folderFirstUrl} replace />;
     return <NotFound />;
   }
   if (errorStatus) return <NotFound />;

packages/chronicle/src/types/config.ts

@@ -86,6 +86,7 @@ const contentEntrySchema = z.object({
   label: z.string().min(1),
   description: z.string().optional(),
   icon: z.string().optional(),
+  index_page: z.string().optional(),
 })
 
 // Variants map to Apsara Badge color prop.