feat: add the fanfold theme, and a short frontmatter field for narrow rails

README.md

@@ -5,7 +5,7 @@ Config-driven documentation framework built on Vite, Nitro, and Apsara UI.
 ## Features
 
 - **Config-driven** — Single `chronicle.yaml` for all site configuration
-- **Themeable** — Built-in themes: `default` (sidebar + TOC) and `paper` (book-style)
+- **Themeable** — Built-in themes: `default` (sidebar + TOC), `paper` (book-style) and `fanfold` (continuous-form line printer)
 - **MDX** — Write docs in MDX with callouts, tabs, mermaid diagrams, and syntax highlighting
 - **API docs** — Interactive OpenAPI documentation with "Try it out" panel
 - **LLMs** — Auto-generate `/llms.txt` and `/llms-full.txt` for AI consumption

docs/content/docs/configuration.mdx

@@ -250,7 +250,7 @@ theme:
 
 | Field | Type | Description | Default |
 |-------|------|-------------|---------|
-| `name` | `'default' \| 'paper'` | Theme to use | `default` |
+| `name` | `'default' \| 'paper' \| 'fanfold'` | Theme to use | `default` |
 | `colors` | `Record<string, string>` | Custom color overrides | — |
 
 See [Themes](/docs/themes) for details on each theme.
@@ -285,7 +285,7 @@ navigation:
 
 ### links
 
-Links shown in the sidebar footer, behind a `?` menu button next to the version switcher. Available in both the `default` and `paper` themes.
+Links shown in the sidebar footer, behind a `?` menu button next to the version switcher. Available in the `default`, `paper` and `fanfold` themes.
 
 ```yaml
 links:

docs/content/docs/frontmatter.mdx

@@ -13,6 +13,7 @@ Every MDX file supports YAML frontmatter at the top of the file for page-level c
 ```mdx
 ---
 title: Getting Started
+short: Start
 description: A quick guide to set up your project
 order: 2
 icon: rectangle-stack
@@ -35,6 +36,24 @@ Your content here...
 title: Installation Guide
 ```
 
+### short
+
+Optional short label for the sidebar. Use it when the full title is too long for
+a narrow rail but the page is known by a code its readers already use — a package
+name, a command, a standard's abbreviation.
+
+```yaml
+title: Space Packet Protocol
+short: SPP
+```
+
+The sidebar shows `SPP` and keeps the full title on the link's tooltip. Headings,
+breadcrumbs, the browser tab and search all keep using `title`. Pages that set no
+`short` fall back to their title, so this is opt-in per page.
+
+Honoured by the `fanfold` theme, whose rail is narrow enough to need it. The
+`default` and `paper` themes ignore it and always show `title`.
+
 ### description
 
 Optional meta description for the page. Used in SEO metadata.

docs/content/docs/themes.mdx

@@ -6,7 +6,7 @@ order: 7
 
 # Themes
 
-Chronicle ships with two built-in themes. Set the theme in your `chronicle.yaml`:
+Chronicle ships with three built-in themes. Set the theme in your `chronicle.yaml`:
 
 ```yaml
 theme:
@@ -58,3 +58,42 @@ theme:
 - Reading progress tracking
 - Optimized typography for long content
 - Light mode only (dark mode toggle is disabled)
+
+## Fanfold Theme
+
+A continuous-form line printer look — tractor-feed strips down both edges, faint
+zebra banding behind the page, and monospace type throughout.
+
+```yaml
+theme:
+  name: fanfold
+```
+
+### Layout
+
+- **Left rail** — A section switcher, then the page tree for the section you are in
+- **Sheet** — Centered content with a printed header block and a footer block
+- **Right rail** — Table of contents plus configured links
+
+### Features
+
+- Header block prints the breadcrumb trail, site name, path, and a page counter
+- Page title set in a dot-matrix face that steps down in size as titles get longer
+- Code blocks print as ruled listings with a line-number gutter
+- Tables print as field maps with no cell borders
+- Its own landing page: a masthead over a register of every section
+- Light and dark mode
+
+### Landing page
+
+When `landing` is turned on, this theme prints its own cover sheet instead of the
+shared card grid. It shows an ident line, the site title in the dot-matrix face,
+the site description, and then every content directory as a numbered row with its
+path and description.
+
+Set it in `chronicle.yaml`:
+
+```yaml
+latest:
+  landing: true
+```

packages/chronicle/src/components/ui/search.tsx

@@ -184,7 +184,7 @@ export function SearchProvider({ children }: { children: ReactNode }) {
   return <SearchContext.Provider value={value}>{children}</SearchContext.Provider>;
 }
 
-function useSearch(): SearchContextValue {
+export function useSearch(): SearchContextValue {
   const ctx = useContext(SearchContext);
   if (!ctx) throw new Error('Search components must be used within <SearchProvider>');
   return ctx;

packages/chronicle/src/lib/config.ts

@@ -4,6 +4,7 @@ import {
   type BadgeConfig,
   type ChronicleConfig,
   chronicleConfigSchema,
+  type LandingEntry,
 } from '@/types'
 
 const defaultConfig: ChronicleConfig = chronicleConfigSchema.parse({
@@ -80,14 +81,6 @@ export interface VersionDescriptor {
   isLatest: boolean
 }
 
-export interface LandingEntry {
-  label: string
-  description?: string
-  href: string
-  contentDir: string
-  icon?: string
-}
-
 export function getLandingEntries(
   config: ChronicleConfig,
   versionDir: string | null,

packages/chronicle/src/lib/source.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { normalizeAuthorList } from './authors';
 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 { Root, Node, Folder, Item } from 'fumadocs-core/page-tree';
 
 import { parentPath, getFolderPath } from './folder-utils';
 
@@ -181,6 +181,50 @@ function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[], me
   return { ...tree, children: sortNodes(tree.children, pageOrderMap, folderOrderMap) };
 }
 
+/**
+ * Copies each page's `short` frontmatter onto its node in the tree, so a sidebar
+ * can label a link without having to look the page up again. Nodes for pages
+ * that set no `short` are left exactly as they were.
+ */
+function attachShortNames(
+  tree: Root,
+  pages: { url: string; data: unknown }[],
+): Root {
+  const shortByUrl = new Map<string, string>();
+  for (const page of pages) {
+    const short = (page.data as Record<string, unknown>).short;
+    if (typeof short === 'string' && short.length > 0) {
+      shortByUrl.set(page.url, short);
+    }
+  }
+  if (shortByUrl.size === 0) return tree;
+
+  const withShort = (node: Item): Item => {
+    const short = shortByUrl.get(node.url);
+    if (!short) return node;
+    // fumadocs' `Item` has no `short`, so widen rather than cast a literal.
+    const labelled: Item & { short: string } = { ...node, short };
+    return labelled;
+  };
+
+  function walk(nodes: Node[]): Node[] {
+    return nodes.map(node => {
+      if (node.type === NodeType.Folder) {
+        const folder = { ...node, children: walk(node.children) } as Folder;
+        // Only touch `index` when there is one. Writing the key back as
+        // `undefined` gives the folder an `index` it never had, and compactTree
+        // walks every key it keeps — including that one.
+        if (node.index) folder.index = withShort(node.index);
+        return folder;
+      }
+      if (node.type !== NodeType.Page) return node;
+      return withShort(node);
+    });
+  }
+
+  return { ...tree, children: walk(tree.children) };
+}
+
 function filterDraftsFromTree(tree: Root, draftUrls: Set<string>): Root {
   function filterNodes(nodes: Node[]): Node[] {
     return nodes
@@ -197,8 +241,12 @@ export async function getPageTree(): Promise<Root> {
   if (cachedTree) return cachedTree;
   const s = await getSource();
   const metaFiles = buildFiles().filter(f => f.type === 'meta') as { path: string; data: Record<string, unknown> }[];
-  const sorted = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
-  const draftUrls = new Set(s.getPages().filter(p => isDraft(p)).map(p => p.url));
+  const pages = s.getPages();
+  const sorted = attachShortNames(
+    sortTreeByOrder(s.pageTree as Root, pages, metaFiles),
+    pages,
+  );
+  const draftUrls = new Set(pages.filter(p => isDraft(p)).map(p => p.url));
   cachedTree = draftUrls.size > 0 ? filterDraftsFromTree(sorted, draftUrls) : sorted;
   return cachedTree;
 }

packages/chronicle/src/lib/tree-utils.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test'
 import type { Node, Root } from 'fumadocs-core/page-tree'
 import type { ChronicleConfig } from '@/types'
 import type { VersionContext } from './version-source'
-import { getFirstPageUrl, findFolderFirstPage, resolveDocsRedirect, resolvePageAndSlug, compactTree } from './tree-utils'
+import { getFirstPageUrl, findFolderFirstPage, resolveDocsRedirect, resolvePageAndSlug, compactTree, shortName } from './tree-utils'
 
 function page(url: string, name = 'Page'): Node {
   return { type: 'page', name, url } as Node
@@ -300,4 +300,55 @@ describe('compactTree', () => {
     const tree: Root = { name: 'custom', children: [] }
     expect(compactTree(tree).name).toBe('custom')
   })
+
+  // `short` is not a field fumadocs knows about, so it only survives
+  // serialisation because it is named in KEEP_FIELDS.
+  test('keeps short on page nodes', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'page', name: 'Space Packet Protocol', short: 'SPP',
+        url: '/protocols/spp', $ref: 'spp.mdx',
+      } as Node],
+    }
+    const result = compactTree(tree)
+    expect(result.children[0]).toEqual({
+      type: 'page', name: 'Space Packet Protocol', short: 'SPP', url: '/protocols/spp',
+    })
+  })
+
+  test('keeps short on a folder index page', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'folder', name: 'Transport',
+        index: { type: 'page', name: 'Transport overview', short: 'TP', url: '/transport' } as Node,
+        children: [],
+      } as Node],
+    }
+    const folder = compactTree(tree).children[0] as any
+    expect(folder.index.short).toBe('TP')
+  })
+})
+
+describe('shortName', () => {
+  test('returns the short label a page set', () => {
+    const node = { type: 'page', name: 'Space Packet Protocol', short: 'SPP', url: '/spp' } as Node
+    expect(shortName(node)).toBe('SPP')
+  })
+
+  test('returns undefined when a page set none, so callers fall back to title', () => {
+    const node = { type: 'page', name: 'Install', url: '/install' } as Node
+    expect(shortName(node)).toBeUndefined()
+  })
+
+  test('ignores an empty string', () => {
+    const node = { type: 'page', name: 'Install', short: '', url: '/install' } as Node
+    expect(shortName(node)).toBeUndefined()
+  })
+
+  test('ignores a non-string value', () => {
+    const node = { type: 'page', name: 'Install', short: 42, url: '/install' } as unknown as Node
+    expect(shortName(node)).toBeUndefined()
+  })
 })

packages/chronicle/src/lib/tree-utils.ts

@@ -2,7 +2,17 @@ import type { Folder, Node, Root } from 'fumadocs-core/page-tree';
 import type { ChronicleConfig } from '@/types';
 import type { VersionContext } from './version-source';
 
-const KEEP_FIELDS = new Set(['type', 'name', 'url', 'icon', 'children', 'index']);
+// Anything not listed here is dropped when the tree is serialised for the
+// client, so a new node field has to be added or it will not survive the trip.
+const KEEP_FIELDS = new Set([
+  'type',
+  'name',
+  'short',
+  'url',
+  'icon',
+  'children',
+  'index',
+]);
 
 function compactLeaf(node: Node): Node {
   const out: Record<string, unknown> = {};
@@ -28,6 +38,15 @@ export function compactTree(tree: Root): Root {
   return { ...tree, children: tree.children.map(compactNode) };
 }
 
+/**
+ * The `short` frontmatter a page set, if any. `attachShortNames` in source.ts
+ * puts it on the node; fumadocs' own `Item` type does not know about it.
+ */
+export function shortName(node: Node): string | undefined {
+  const value = (node as { short?: unknown }).short;
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
 export const NodeType = {
   Page: 'page',
   Folder: 'folder',

packages/chronicle/src/pages/LandingPage.tsx

@@ -3,28 +3,59 @@ import { Link as RouterLink } from 'react-router';
 import { getLandingEntries } from '@/lib/config';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+import type { ThemeLandingProps } from '@/types';
 import styles from './LandingPage.module.css';
 
+/**
+ * Resolves what the landing page shows, then hands it to the active theme.
+ *
+ * Themes that fill the `Landing` slot get to lay the page out themselves; the
+ * rest fall through to `DefaultLanding` below. Config reading, the `<Head>`
+ * tags and the version label stay here either way, so a theme never has to
+ * repeat them.
+ */
 export function LandingPage() {
   const { config, version } = usePageContext();
   const entries = getLandingEntries(config, version.dir);
+  const { Landing } = getTheme(config.theme?.name);
 
-  const heading = version.dir === null
-    ? config.site.title
-    : `${config.site.title} — ${versionLabel(config, version.dir)}`;
+  // The heading only carries a version when an older one is being read, so the
+  // latest reads as the site itself. `versionLabel` is the label either way —
+  // a theme may want to print "0.3" even on the latest version.
+  const olderLabel =
+    version.dir === null ? null : versionLabel(config, version.dir);
+  const heading = olderLabel
+    ? `${config.site.title} — ${olderLabel}`
+    : config.site.title;
+
+  const props: ThemeLandingProps = {
+    config,
+    entries,
+    heading,
+    description: config.site.description,
+    versionLabel: olderLabel ?? config.latest?.label ?? null,
+  };
 
   return (
     <>
       <Head
-        title={version.dir ? `${config.site.title} — ${versionLabel(config, version.dir)}` : 'Documentation'}
+        title={olderLabel ? `${config.site.title} — ${olderLabel}` : 'Documentation'}
         description={config.site.description}
         config={config}
       />
+      {Landing ? <Landing {...props} /> : <DefaultLanding {...props} />}
+    </>
+  );
+}
+
+function DefaultLanding({ entries, heading, description }: ThemeLandingProps) {
+  return (
     <div className={styles.root}>
       <div className={styles.header}>
         <h1 className={styles.title}>{heading}</h1>
-        {config.site.description ? (
-          <p className={styles.description}>{config.site.description}</p>
+        {description ? (
+          <p className={styles.description}>{description}</p>
         ) : null}
       </div>
       <div className={styles.grid}>
@@ -49,7 +80,6 @@ export function LandingPage() {
         ))}
       </div>
     </div>
-    </>
   );
 }