@classic-homes/theme-docs 0.2.0 → 0.3.0

package/dist/lib/components/CategoryIndex.svelte

@@ -6,7 +6,7 @@
    * Pass a `CategoryPage` from `loadDocs`. Page cards show `descriptions[route]` when
    * given; category cards show how many entries they hold.
    */
-  import { PageHeader } from '@classic-homes/theme-svelte';
+  import { ActionHeader } from '@classic-homes/theme-svelte';
   import DocsHub from './DocsHub.svelte';
   import { countPages, flattenNav } from '../content/nav.js';
   import type { CategoryPage } from '../content/types.js';
@@ -46,6 +46,6 @@
 </script>
 
 <div class={className}>
-  <PageHeader class="mb-8" title={category.title} subtitle={category.description || undefined} />
+  <ActionHeader class="mb-6" title={category.title} subtitle={category.description || undefined} />
   <DocsHub {columns} config={{ sections: [{ id: 'items', items }] }} />
 </div>

package/dist/lib/components/DocPage.svelte

@@ -3,13 +3,13 @@
    * DocPage - one docs page, laid out the way Docusaurus lays out a doc.
    *
    * Takes HTML rendered at build time (`renderDocs`), so it renders on the server with no
-   * client-side parsing. Around the content: breadcrumbs, a `<h1>` from the title when the
-   * body has none, tags, an edit link, previous/next links and the table of contents. In
+   * client-side parsing. Around the content: breadcrumbs, the title as an `ActionHeader`
+   * (like app pages) when the body has no `<h1>`, tags, an edit link, previous/next links and the table of contents. In
    * the browser it mounts allowlisted components, renders mermaid diagrams, adds copy
    * buttons to code blocks and highlights `?highlight=` search terms.
    */
   import type { Component, Snippet } from 'svelte';
-  import { Button } from '@classic-homes/theme-svelte';
+  import { ActionHeader, Button } from '@classic-homes/theme-svelte';
   import { cn } from '../utils.js';
   import Breadcrumbs from './Breadcrumbs.svelte';
   import DocPager from './DocPager.svelte';
@@ -22,7 +22,9 @@
   import type { RenderedDoc, Tag } from '../content/types.js';
 
   interface Props {
-    page: Pick<RenderedDoc, 'title' | 'html' | 'toc' | 'hasH1'> & { description?: string };
+    page: Pick<RenderedDoc, 'title' | 'heading' | 'html' | 'toc' | 'hasH1'> & {
+      description?: string;
+    };
     /** `breadcrumbs(sidebar.items, route)` */
     breadcrumbs?: Crumb[];
     /** First breadcrumb, e.g. `{ label: 'Docs', href: '/' }` */
@@ -39,6 +41,8 @@
     components?: Record<string, Component<any>>;
     /** Render mermaid diagrams (needs the optional `mermaid` peer). Default: true */
     mermaid?: boolean;
+    /** Mermaid theme. Default: `brand` (colours from the theme tokens) */
+    mermaidTheme?: 'brand' | 'default' | 'dark' | 'forest' | 'neutral';
     /** Copy buttons on code blocks. Default: true */
     copyButtons?: boolean;
     /** Query parameter whose words are highlighted in the page. Default: `highlight` */
@@ -74,6 +78,7 @@
     editLabel = 'Edit this page',
     components,
     mermaid = true,
+    mermaidTheme = 'brand',
     copyButtons = true,
     highlightParam = 'highlight',
     tocMinDepth = 2,
@@ -125,14 +130,16 @@
   <div class="min-w-0 max-w-3xl flex-1">
     <Breadcrumbs crumbs={breadcrumbs} {home} />
 
+    <!-- The title as app pages show theirs (ActionHeader); render with `hoistTitle` so
+         the body's own `# Title` becomes this rather than a markdown-styled h1. -->
+    {#if !page.hasH1}<ActionHeader class="mb-6" title={page.heading ?? page.title} />{/if}
     <article class="markdown-content">
-      {#if !page.hasH1}<h1>{page.title}</h1>{/if}
       {@render header?.()}
       {#key page.html}
         <div bind:this={content}>{@html page.html}</div>
       {/key}
     </article>
-    {#if mermaid}<MermaidInit watch />{/if}
+    {#if mermaid}<MermaidInit watch theme={mermaidTheme} />{/if}
 
     <footer class="mt-12 space-y-6">
       {#if tags.length}<TagList {tags} href={tagHref} />{/if}

package/dist/lib/components/DocPage.svelte.d.ts

@@ -2,8 +2,8 @@
    * DocPage - one docs page, laid out the way Docusaurus lays out a doc.
    *
    * Takes HTML rendered at build time (`renderDocs`), so it renders on the server with no
-   * client-side parsing. Around the content: breadcrumbs, a `<h1>` from the title when the
-   * body has none, tags, an edit link, previous/next links and the table of contents. In
+   * client-side parsing. Around the content: breadcrumbs, the title as an `ActionHeader`
+   * (like app pages) when the body has no `<h1>`, tags, an edit link, previous/next links and the table of contents. In
    * the browser it mounts allowlisted components, renders mermaid diagrams, adds copy
    * buttons to code blocks and highlights `?highlight=` search terms.
    */
@@ -11,7 +11,7 @@ import type { Component, Snippet } from 'svelte';
 import type { Crumb, NavLink } from '../content/nav.js';
 import type { RenderedDoc, Tag } from '../content/types.js';
 interface Props {
-    page: Pick<RenderedDoc, 'title' | 'html' | 'toc' | 'hasH1'> & {
+    page: Pick<RenderedDoc, 'title' | 'heading' | 'html' | 'toc' | 'hasH1'> & {
         description?: string;
     };
     /** `breadcrumbs(sidebar.items, route)` */
@@ -33,6 +33,8 @@ interface Props {
     components?: Record<string, Component<any>>;
     /** Render mermaid diagrams (needs the optional `mermaid` peer). Default: true */
     mermaid?: boolean;
+    /** Mermaid theme. Default: `brand` (colours from the theme tokens) */
+    mermaidTheme?: 'brand' | 'default' | 'dark' | 'forest' | 'neutral';
     /** Copy buttons on code blocks. Default: true */
     copyButtons?: boolean;
     /** Query parameter whose words are highlighted in the page. Default: `highlight` */

package/dist/lib/components/MermaidInit.svelte

@@ -12,8 +12,11 @@
   import { onMount } from 'svelte';
 
   interface Props {
-    /** Mermaid theme (default: 'default') */
-    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    /**
+     * Mermaid theme (default: 'default'). `brand` colours diagrams from the theme tokens
+     * on the page (muted node fills, foreground text and lines, Figtree).
+     */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral' | 'brand';
     /** Whether to watch for new diagrams via MutationObserver */
     watch?: boolean;
   }
@@ -22,6 +25,42 @@
 
   let initialized = $state(false);
 
+  /** A token's HSL triplet (`357 72% 39%`) as a colour mermaid's colour math can parse */
+  function token(styles: CSSStyleDeclaration, name: string, fallback: string): string {
+    const parts = styles.getPropertyValue(`--${name}`).trim().split(/\s+/);
+    return parts.length === 3 ? `hsl(${parts.join(', ')})` : fallback;
+  }
+
+  function brandConfig() {
+    const s = getComputedStyle(document.documentElement);
+    const foreground = token(s, 'foreground', '#4f4f4f');
+    return {
+      theme: 'base' as const,
+      themeVariables: {
+        fontFamily: 'Figtree, ui-sans-serif, system-ui, sans-serif',
+        fontSize: '14px',
+        background: token(s, 'background', '#ffffff'),
+        primaryColor: token(s, 'muted', '#e8e9e4'),
+        primaryTextColor: foreground,
+        primaryBorderColor: token(s, 'secondary', '#5f6150'),
+        secondaryColor: token(s, 'sidebar-background', '#f5f5f3'),
+        secondaryTextColor: foreground,
+        secondaryBorderColor: token(s, 'outline', '#8b8e7b'),
+        tertiaryColor: token(s, 'content-bg', '#fafafa'),
+        tertiaryTextColor: foreground,
+        tertiaryBorderColor: token(s, 'outline', '#8b8e7b'),
+        clusterBkg: token(s, 'content-bg', '#fafafa'),
+        clusterBorder: token(s, 'outline', '#8b8e7b'),
+        lineColor: token(s, 'muted-foreground', '#666666'),
+        textColor: foreground,
+        noteBkgColor: token(s, 'muted', '#e8e9e4'),
+        noteTextColor: foreground,
+        noteBorderColor: token(s, 'outline', '#8b8e7b'),
+        edgeLabelBackground: token(s, 'background', '#ffffff'),
+      },
+    };
+  }
+
   async function renderDiagrams() {
     try {
       const mermaid = await import('mermaid');
@@ -29,7 +68,7 @@
       // Initialize mermaid
       mermaid.default.initialize({
         startOnLoad: false,
-        theme: theme,
+        ...(theme === 'brand' ? brandConfig() : { theme }),
         securityLevel: 'strict',
       });
 

package/dist/lib/components/MermaidInit.svelte.d.ts

@@ -1,6 +1,9 @@
 interface Props {
-    /** Mermaid theme (default: 'default') */
-    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    /**
+     * Mermaid theme (default: 'default'). `brand` colours diagrams from the theme tokens
+     * on the page (muted node fills, foreground text and lines, Figtree).
+     */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral' | 'brand';
     /** Whether to watch for new diagrams via MutationObserver */
     watch?: boolean;
 }

package/dist/lib/content/render.d.ts

@@ -13,8 +13,8 @@ export interface RenderDocsOptions {
     onBrokenAnchors?: BrokenLinkPolicy;
     /**
      * Lift a page's leading `# Heading` out of the body: it becomes the title when the page
-     * has no `title` front matter, and the layout renders it (so content such as a lead
-     * paragraph can sit between title and body). Default: false
+     * has no `title` front matter (else `heading`, when it differs), and the layout renders
+     * it (so content such as a lead paragraph can sit between title and body). Default: false
      */
     hoistTitle?: boolean;
 }

package/dist/lib/content/render.js

@@ -13,13 +13,17 @@ export async function renderDocs(docs, options = {}) {
         const rendered = await parseMarkdown(markdown, parse);
         let html = rendered.html;
         let { title } = page;
+        let heading;
         let toc = rendered.toc;
         if (hoistTitle) {
             const leading = /^\s*<h1\b[^>]*>([\s\S]*?)<\/h1>\s*/.exec(html);
             if (leading) {
                 html = html.slice(leading[0].length);
+                const text = plainText(leading[1]);
                 if (page.frontmatter.title === undefined)
-                    title = plainText(leading[1]);
+                    title = text;
+                else if (text && text !== title)
+                    heading = text;
                 toc = toc.filter((entry, i) => !(i === 0 && entry.level === 1));
             }
         }
@@ -32,6 +36,7 @@ export async function renderDocs(docs, options = {}) {
         return {
             ...page,
             title,
+            ...(heading && { heading }),
             html,
             toc,
             hasH1: toc.some((entry) => entry.level === 1) || /<h1[\s>]/.test(html),

package/dist/lib/content/types.d.ts

@@ -85,6 +85,12 @@ export interface RenderedDoc extends Omit<DocSource, 'markdown'> {
     toc: TocEntry[];
     /** Whether the body has its own `<h1>`. When it doesn't, the layout shows `title`. */
     hasH1: boolean;
+    /**
+     * With `hoistTitle`: the text of the `# Heading` lifted out of the body, when it differs
+     * from `title`. Docusaurus shows the body heading on the page and keeps `title` for the
+     * sidebar and `<title>`, so layouts show this in place of `title` when set.
+     */
+    heading?: string;
     /** Searchable plain text: the page without markup, code blocks or diagrams */
     text: string;
 }

package/dist/lib/search/index.d.ts

@@ -52,6 +52,6 @@ export interface SearchQueryOptions {
 export declare function createSearch(indexJson: string | object, texts?: Map<string, string> | Record<string, string>): {
     search(query: string, options?: SearchQueryOptions): SearchHit[];
 };
-/** About 160 characters around the first matched term. */
+/** About 160 characters around the first matched term, cut at word boundaries. */
 export declare function snippet(text: string, terms: string[]): string;
 export {};

package/dist/lib/search/index.js

@@ -62,7 +62,7 @@ export function createSearch(indexJson, texts) {
                     title: stored.title,
                     description: stored.description,
                     sidebar: stored.sidebar,
-                    snippet: snippet(textOf(route) ?? stored.description ?? '', hit.terms),
+                    snippet: snippet(withoutTitle(textOf(route), stored.title) ?? stored.description ?? '', hit.terms),
                     terms: hit.terms,
                     score: hit.score,
                 };
@@ -70,13 +70,38 @@ export function createSearch(indexJson, texts) {
         },
     };
 }
-/** About 160 characters around the first matched term. */
+/**
+ * A page's text minus its leading title: the body's `# Title` heading is the first thing in
+ * the text, and the result already shows the title, so a snippet would repeat it.
+ */
+function withoutTitle(text, title) {
+    if (!text || !title || !text.startsWith(title))
+        return text;
+    return text.slice(title.length).trimStart();
+}
+/** About 160 characters around the first matched term, cut at word boundaries. */
 export function snippet(text, terms) {
     const lower = text.toLowerCase();
     const at = Math.min(...terms.map((term) => lower.indexOf(term.toLowerCase())).filter((i) => i >= 0));
     if (!Number.isFinite(at))
-        return text.length > 160 ? `${text.slice(0, 160).trim()}…` : text;
-    const start = Math.max(0, at - 60);
-    const end = start + 160;
+        return clip(text, 0, 160);
+    return clip(text, Math.max(0, at - 60), Math.max(0, at - 60) + 160, at);
+}
+/** `text[start, end)` widened or narrowed to whole words (never past `keep`), with ellipses. */
+function clip(text, start, end, keep = start) {
+    if (start > 0) {
+        // Start after the space before the cut, so the snippet opens on a whole word.
+        const space = text.indexOf(' ', start);
+        if (space >= 0 && space < keep)
+            start = space + 1;
+    }
+    if (end < text.length) {
+        const space = text.lastIndexOf(' ', end);
+        if (space > keep)
+            end = space;
+    }
+    else {
+        end = text.length;
+    }
     return `${start > 0 ? '…' : ''}${text.slice(start, end).trim()}${end < text.length ? '…' : ''}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/theme-docs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Markdown documentation components for the Classic theme system",
   "type": "module",
   "main": "./dist/lib/index.js",