@raystack/chronicle 0.11.2 → 0.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",

package/src/components/ui/search.module.css

@@ -1,10 +1,12 @@
 .dialogContent {
-  border-radius: var(--rs-radius-4);
+  border-radius: var(--rs-radius-5);
   padding: 0px;
   width: 80%;
   max-width: 600px;
   position: fixed;
   top: 20%;
+  overflow: clip;
+  box-shadow: var(--rs-shadow-floating);
 }
 
 .input {
@@ -13,7 +15,8 @@
 
 .list {
   max-height: 400px;
-  gap: var(--rs-space-3);
+  padding: 0 var(--rs-space-2);
+  gap: var(--rs-space-2);
 }
 
 .list :global([cmdk-group-heading]) {
@@ -25,35 +28,50 @@
 }
 
 .item {
-  min-height: 40px;
-  padding: var(--rs-space-3);
+  padding: var(--rs-space-5) var(--rs-space-4);
   gap: var(--rs-space-3);
-  border-radius: var(--rs-radius-2);
+  border-radius: var(--rs-radius-3);
   cursor: pointer;
 }
 
-
 .item[data-selected="true"] {
   background: var(--rs-color-background-base-primary-hover);
 }
 
 .itemContent {
   display: flex;
-  align-items: center;
-  gap: 12px;
+  align-items: flex-start;
+  gap: var(--rs-space-3);
   flex: 1;
 }
 
-.sectionBadge {
-  margin-left: auto;
-  flex-shrink: 0;
-}
-
 .resultText {
   display: flex;
   flex-direction: column;
-  gap: 2px;
+  gap: var(--rs-space-2);
   min-width: 0;
+  flex: 1;
+}
+
+.breadcrumb {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-2);
+}
+
+.breadcrumbText {
+  font-family: var(--rs-font-body);
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
+  color: var(--rs-color-foreground-base-primary);
+  white-space: nowrap;
+}
+
+.breadcrumbSeparator {
+  color: var(--rs-color-foreground-base-tertiary);
+  font-size: var(--rs-font-size-small);
 }
 
 .headingText {
@@ -64,10 +82,6 @@
   color: var(--rs-color-foreground-accent-primary-hover);
 }
 
-.separator {
-  color: var(--rs-color-foreground-base-secondary);
-}
-
 .pageText {
   color: var(--rs-color-foreground-base-primary);
 }
@@ -77,14 +91,15 @@
 }
 
 .icon {
-  width: 48px;
-  height: 24px;
+  width: 16px;
+  height: 16px;
   color: var(--rs-color-foreground-base-secondary);
   flex-shrink: 0;
+  margin-top: 1px;
 }
 
 .itemContent :global([class*="badge-module"]) {
-  min-width: 48px;
+  min-width: auto;
   justify-content: center;
 }
 
@@ -95,14 +110,15 @@
 .snippetText {
   font-size: var(--rs-font-size-mini);
   line-height: var(--rs-line-height-mini);
-  color: var(--rs-color-foreground-base-tertiary);
+  letter-spacing: var(--rs-letter-spacing-mini);
+  color: var(--rs-color-foreground-base-secondary);
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
 .matchHighlight {
-  color: var(--rs-color-foreground-accent-primary);
+  color: var(--rs-color-foreground-base-primary);
   font-weight: var(--rs-font-weight-medium);
 }
 

package/src/components/ui/search.tsx

@@ -1,15 +1,18 @@
 import {
   DocumentIcon,
   HashtagIcon,
-  MagnifyingGlassIcon
+  MagnifyingGlassIcon,
+  CodeBracketIcon,
+  ChevronRightIcon
 } from '@heroicons/react/24/outline';
-import { Badge, Command, IconButton, Text } from '@raystack/apsara';
+import { Command, IconButton, Text } from '@raystack/apsara';
 import { keepPreviousData, useQuery } from '@tanstack/react-query';
 import { debounce } from 'lodash-es';
 import { useCallback, useEffect, useMemo, useState, type ChangeEvent } from 'react';
 import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
 import { usePageContext } from '@/lib/page-context';
+import { SearchMatchType } from '@/types';
 import styles from './search.module.css';
 
 interface SearchResult {
@@ -17,7 +20,7 @@ interface SearchResult {
   url: string;
   type: string;
   content: string;
-  match?: 'title' | 'heading' | 'body';
+  match?: SearchMatchType;
   snippet?: string;
   section?: string;
 }
@@ -135,15 +138,7 @@ export function Search({ classNames }: SearchProps) {
                         onClick={() => onSelect(result.url)}
                         className={styles.item}
                       >
-                        <div className={styles.itemContent}>
-                          {getResultIcon(result)}
-                          <Text className={styles.pageText}>
-                            <HighlightedText
-                              html={stripMethod(result.content)}
-                            />
-                          </Text>
-                          {result.section && <Badge size="small" className={styles.sectionBadge}>{result.section}</Badge>}
-                        </div>
+                        <SearchResultItem result={result} query="" />
                       </Command.Item>
                     ))}
                   </Command.Group>
@@ -156,25 +151,7 @@ export function Search({ classNames }: SearchProps) {
                     onClick={() => onSelect(result.url)}
                     className={styles.item}
                   >
-                    <div className={styles.itemContent}>
-                      {getResultIcon(result)}
-                      <div className={styles.resultText}>
-                        <Text className={styles.pageText}>
-                          <HighlightQuery text={stripMethod(result.content)} query={search} />
-                        </Text>
-                        {result.snippet && result.match === 'heading' && (
-                          <Text className={styles.snippetText}>
-                            # <HighlightQuery text={result.snippet} query={search} />
-                          </Text>
-                        )}
-                        {result.snippet && result.match === 'body' && (
-                          <Text className={styles.snippetText}>
-                            <HighlightQuery text={result.snippet} query={search} />
-                          </Text>
-                        )}
-                      </div>
-                      {result.section && <Badge size="small" className={styles.sectionBadge}>{result.section}</Badge>}
-                    </div>
+                    <SearchResultItem result={result} query={search} />
                   </Command.Item>
                 ))}
             </Command.Content>
@@ -185,6 +162,38 @@ export function Search({ classNames }: SearchProps) {
   );
 }
 
+function SearchResultItem({ result, query }: { result: SearchResult; query: string }) {
+  const method = extractMethod(result.content);
+  const title = stripMethod(result.content);
+
+  return (
+    <div className={styles.itemContent}>
+      {getResultIcon(result)}
+      <div className={styles.resultText}>
+        <div className={styles.breadcrumb}>
+          {result.section && (
+            <>
+              <span className={styles.breadcrumbText}>{result.section}</span>
+              <ChevronRightIcon width={12} height={12} className={styles.breadcrumbSeparator} />
+            </>
+          )}
+          {method && <MethodBadge method={method} size='micro' />}
+          <Text className={styles.breadcrumbText}>
+            {query ? <HighlightQuery text={title} query={query} /> : <HighlightedText html={title} />}
+          </Text>
+        </div>
+        {result.snippet && (
+          <Text className={styles.snippetText}>
+            {query
+              ? <HighlightQuery text={result.snippet} query={query} />
+              : result.snippet}
+          </Text>
+        )}
+      </div>
+    </div>
+  );
+}
+
 function deduplicateByUrl(results: SearchResult[]): SearchResult[] {
   const seen = new Set<string>();
   return results.filter(r => {
@@ -233,15 +242,13 @@ function HighlightQuery({ text, query }: { text: string; query: string }) {
 }
 
 function getResultIcon(result: SearchResult): React.ReactNode {
-  if (!result.url.startsWith('/apis/')) {
-    return result.type === 'page' ? (
-      <DocumentIcon className={styles.icon} />
-    ) : (
-      <HashtagIcon className={styles.icon} />
-    );
+  if (result.url.startsWith('/apis/')) {
+    return <CodeBracketIcon className={styles.icon} />;
   }
-  const method = extractMethod(result.content);
-  return method ? <MethodBadge method={method} size='micro' /> : null;
+  if (result.match === SearchMatchType.Heading) {
+    return <HashtagIcon className={styles.icon} />;
+  }
+  return <DocumentIcon className={styles.icon} />;
 }
 
 function getPageTitle(url: string): string {

package/src/server/api/search.ts

@@ -7,6 +7,7 @@ import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { extractFrontmatter, getPageSearchContent, getPagesForVersion } from '@/lib/source';
 import { LATEST_CONTEXT, type VersionContext } from '@/lib/version-source';
+import { SearchResultType, SearchMatchType } from '@/types';
 
 interface SearchDocument {
   id: string;
@@ -14,7 +15,7 @@ interface SearchDocument {
   title: string;
   headings: string;
   body: string;
-  type: 'page' | 'api';
+  type: SearchResultType;
   section: string;
 }
 
@@ -104,7 +105,7 @@ async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
       title: fm.title,
       headings,
       body: [fm.description ?? '', body].join(' '),
-      type: 'page',
+      type: SearchResultType.Page,
       section: entry?.label ?? dir ?? '',
     });
   }
@@ -128,7 +129,7 @@ async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
             title: `${method.toUpperCase()} ${op.summary ?? opId}`,
             headings: op.summary ?? opId,
             body: [op.description ?? '', pathStr, method.toUpperCase()].join(' '),
-            type: 'api',
+            type: SearchResultType.Api,
             section: spec.name,
           });
         }
@@ -144,9 +145,9 @@ function findMatch(
   title: string,
   headings: string,
   body: string,
-): { match: 'title' | 'heading' | 'body'; snippet: string; slug?: string } {
+): { match: SearchMatchType; snippet: string; slug?: string } {
   if (title.toLowerCase().includes(query)) {
-    return { match: 'title', snippet: title };
+    return { match: SearchMatchType.Title, snippet: title };
   }
 
   const slugger = new GithubSlugger();
@@ -154,7 +155,7 @@ function findMatch(
   for (const h of headingList) {
     const slug = slugger.slug(h);
     if (h.toLowerCase().includes(query)) {
-      return { match: 'heading', snippet: h, slug };
+      return { match: SearchMatchType.Heading, snippet: h, slug };
     }
   }
 
@@ -163,10 +164,10 @@ function findMatch(
     const start = Math.max(0, idx - 40);
     const end = Math.min(body.length, idx + query.length + 80);
     const snippet = (start > 0 ? '...' : '') + body.slice(start, end).trim() + (end < body.length ? '...' : '');
-    return { match: 'body', snippet };
+    return { match: SearchMatchType.Body, snippet };
   }
 
-  return { match: 'title', snippet: title };
+  return { match: SearchMatchType.Title, snippet: title };
 }
 
 function resolveCtx(tag: string | null): VersionContext {
@@ -218,8 +219,8 @@ export default defineHandler(async event => {
   const queryLower = query.toLowerCase();
   return Response.json((result.rows ?? []).map(r => {
     const { match, snippet, slug } = findMatch(queryLower, r.title as string, r.headings as string, r.body as string);
-    const id = match === 'heading' && slug ? `${r.id}#${slug}` : r.id as string;
-    const url = match === 'heading' && slug ? `${r.url}#${slug}` : r.url as string;
+    const id = match === SearchMatchType.Heading && slug ? `${r.id}#${slug}` : r.id as string;
+    const url = match === SearchMatchType.Heading && slug ? `${r.url}#${slug}` : r.url as string;
     return {
       id,
       url,

package/src/server/utils/api-markdown.ts

@@ -41,6 +41,11 @@ function generateApiMarkdown(
     lines.push(operation.description)
     lines.push('')
   }
+  if (operation.externalDocs?.url) {
+    const label = operation.externalDocs.description || 'external documentation'
+    lines.push(`Read more about this operation in the [${label}](${operation.externalDocs.url}).`)
+    lines.push('')
+  }
   lines.push(`\`${method}\` \`${path}\``)
   lines.push('')
 

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

@@ -171,11 +171,15 @@
 }
 
 .groupItems {
-  padding-left: var(--rs-space-4);
+  padding-left: 0;
   padding-bottom: var(--rs-space-3);
   gap: 0;
 }
 
+.navGroup:not([data-depth='0']) .groupItems {
+  padding-left: var(--rs-space-4);
+}
+
 .navGroup {
   margin-top: 0;
 }

package/src/themes/default/Layout.tsx

@@ -28,8 +28,11 @@ import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
 import { OpenInAI } from './OpenInAI';
 import { SidebarLogo } from './SidebarLogo';
+
 import { VersionSwitcher } from './VersionSwitcher';
 
+const MAX_SIDEBAR_DEPTH = 3;
+
 const iconMap: Record<string, React.ReactNode> = {
   'rectangle-stack': <RectangleStackIcon width={16} height={16} />,
   'method-get': <MethodBadge method='GET' size='micro' />,
@@ -249,7 +252,7 @@ function SidebarNode({
   }
 
   if (item.type === 'folder') {
-    if (depth > 1) return null;
+    if (depth > MAX_SIDEBAR_DEPTH) return null;
     const icon = typeof item.icon === 'string' ? iconMap[item.icon] : item.icon;
     const hasActiveChild = hasActiveDescendant(item, pathname);
     return (
@@ -258,7 +261,7 @@ function SidebarNode({
         data-depth={depth}
         label={item.name?.toString() ?? ''}
         leadingIcon={icon ?? undefined}
-        collapsible={depth === 1}
+        collapsible={depth >= 1}
         defaultOpen={hasActiveChild}
         classNames={{
           items: styles.groupItems,

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

@@ -39,15 +39,22 @@
 .content h1 {
   font-size: var(--rs-font-size-t4);
   line-height: var(--rs-line-height-t4);
-  margin-top: 0;
-  margin-bottom: var(--rs-space-10);
+  margin: var(--rs-space-10) 0;
 }
 
 .content h2 {
   font-size: var(--rs-font-size-t3);
   line-height: var(--rs-line-height-t3);
-  margin-top: var(--rs-space-8);
-  margin-bottom: var(--rs-space-8);
+  margin-top: var(--rs-space-10);
+  margin-bottom: var(--rs-space-7);
+}
+
+.content p + h2,
+.content ul + h2,
+.content ol + h2,
+.content div + h2,
+.content table + h2 {
+  margin-top: var(--rs-space-13);
 }
 
 .content h3 {
@@ -77,6 +84,7 @@
   font-style: normal;
   font-weight: var(--rs-font-weight-regular);
   line-height: 171.429%;
+  margin-bottom: var(--rs-space-7);
 }
 
 .content ul,
@@ -90,6 +98,15 @@
   margin: var(--rs-space-2) 0;
 }
 
+.content table td {
+  font-size: var(--rs-font-size-regular);
+}
+
+.content table th {
+  font-size: var(--rs-font-size-regular);
+  font-weight: var(--rs-font-weight-medium);
+}
+
 .content a {
   font-size: inherit;
 }
@@ -101,6 +118,7 @@
 .content img {
   max-width: 100%;
   height: auto;
+  margin: var(--rs-space-7) 0;
 }
 
 .content table {

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

@@ -213,6 +213,11 @@
   text-overflow: unset;
   word-wrap: break-word;
   vertical-align: top;
+  font-size: var(--rs-font-size-regular);
+}
+
+.content table th {
+  font-weight: var(--rs-font-weight-medium);
 }
 
 .content a {

package/src/types/content.ts

@@ -24,6 +24,21 @@ export interface PageNav {
   next: PageNavLink | null
 }
 
+export const SearchResultType = {
+  Page: 'page',
+  Api: 'api',
+} as const;
+
+export type SearchResultType = (typeof SearchResultType)[keyof typeof SearchResultType];
+
+export const SearchMatchType = {
+  Title: 'title',
+  Heading: 'heading',
+  Body: 'body',
+} as const;
+
+export type SearchMatchType = (typeof SearchMatchType)[keyof typeof SearchMatchType];
+
 export interface Page extends PageNav {
   slug: string[]
   frontmatter: Frontmatter