@clidey/dory 0.46.0 → 0.48.0

package/src/theme.scss

@@ -1,39 +1,162 @@
 :root {
-    font-synthesis: none;
     text-rendering: optimizeLegibility;
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
 
     // Brand colors (dynamically set from dory.json via loadColors())
-    // These variables are set at runtime:
-    // --brand-primary: primary color
-    // --brand-light: light mode accent
-    // --brand-dark: dark mode accent
-    // --brand-foreground: legacy/fallback (set to primary)
-
-    // Default fallback colors (will be overridden by loadColors())
     --brand-foreground: #0ea5e9;
     --brand-primary: #0ea5e9;
     --brand-light: #38bdf8;
     --brand-dark: #0284c7;
 
+    // Font families
+    --font-body: inherit;
+    --font-heading: inherit;
+    --font-mono: inherit;
+
     // ShadCN/clidey/ux compatible primary color
-    // Using light color for light mode
     --primary: var(--brand-light);
     --primary-rgb: var(--brand-light-rgb);
-    
+
     --ring: rgba(0, 0, 0, 0.1);
 }
 
-// Dark mode overrides
 :root.dark {
-    // Use dark color for dark mode
     --primary: var(--brand-dark);
     --primary-rgb: var(--brand-dark-rgb);
-
     --ring: rgba(255, 255, 255, 0.1);
 }
-  
+
+// Apply background from CSS variables
+html, body, #app {
+    background-color: var(--background);
+    color: var(--foreground);
+}
+
+// === THEMED MODE: override Tailwind utility classes ===
+[data-dory-themed="true"] {
+    // Navigation sidebar text
+    .dory-navigation {
+        a {
+            color: var(--muted-foreground) !important;
+        }
+
+        a:hover {
+            color: var(--foreground) !important;
+        }
+
+        a.font-semibold {
+            color: var(--brand-foreground) !important;
+        }
+
+        h2, h3 {
+            color: var(--foreground) !important;
+        }
+
+        ul[role="list"] {
+            border-color: var(--border) !important;
+        }
+    }
+
+    // Override hardcoded Tailwind text colors
+    .text-slate-500,
+    .text-slate-400,
+    .text-slate-600,
+    .text-zinc-500,
+    .text-zinc-400,
+    .text-gray-500,
+    .text-gray-400 {
+        color: var(--muted-foreground) !important;
+    }
+
+    .text-slate-900,
+    .text-zinc-900,
+    .text-gray-900 {
+        color: var(--foreground) !important;
+    }
+
+    // Override hardcoded Tailwind border colors
+    .border-slate-100,
+    .border-slate-200,
+    .border-slate-800,
+    .border-zinc-200,
+    .border-zinc-800 {
+        border-color: var(--border) !important;
+    }
+
+    // Header
+    .dory-header {
+        border-color: var(--border) !important;
+    }
+
+    // Accordion & divider borders — subtle low opacity
+    [data-slot="accordion-item"],
+    hr,
+    .border-t,
+    .border-b {
+        border-color: color-mix(in oklch, var(--foreground) 8%, transparent) !important;
+    }
+}
+
+// === FONT OVERRIDES ===
+[data-dory-themed="true"] {
+    // Page title — large display serif
+    .dory-page-title {
+        font-family: var(--font-heading, var(--font-body, inherit));
+        font-weight: 380;
+        font-variation-settings: "opsz" 144, "SOFT" 30;
+        letter-spacing: -0.02em;
+    }
+
+    // Subtitle / eyebrow — mono, muted amber
+    .dory-subtitle {
+        font-family: var(--font-mono, monospace);
+        color: var(--brand-foreground);
+        opacity: 0.8;
+        letter-spacing: 0.15em;
+        font-size: 11px;
+    }
+
+    // Article headings — serif with proper optical sizing
+    article h2 {
+        font-family: var(--font-heading, var(--font-body, inherit));
+        font-weight: 400;
+        font-variation-settings: "opsz" 48, "SOFT" 50;
+        letter-spacing: -0.015em;
+    }
+
+    article h3,
+    article h4 {
+        font-family: var(--font-body, inherit);
+        font-weight: 600;
+    }
+
+    code, pre {
+        font-family: var(--font-mono, monospace);
+    }
+}
+
+// === CODE BLOCK STYLING ===
+// Make code blocks translucent to match app feel
+[data-dory-themed="true"] {
+    [data-slot="card"],
+    .bg-card {
+        background-color: transparent !important;
+        border-color: var(--border) !important;
+    }
+
+    pre {
+        background-color: transparent !important;
+    }
+
+    // Inline code
+    .dory-mdx-code {
+        background-color: transparent !important;
+        border: 1px solid var(--border);
+    }
+}
+
+// === DEFAULT STYLES ===
 article h2:first-of-type {
     display: none;
 }
@@ -69,4 +192,4 @@ article img {
     outline: none !important;
     border: 0px;
     box-shadow: none !important;
-}
+}

package/src/types/config.ts

@@ -6,12 +6,29 @@ export interface DoryColors {
   primary: string;
   light: string;
   dark: string;
+  background?: string;
+  surface?: string;
+  surfaceElevated?: string;
+  foreground?: string;
+  mutedForeground?: string;
+  border?: string;
+  accent?: string;
+}
+
+export interface DoryFontDefinition {
+  family: string;
+  source?: string;
+  format?: string;
+  weight?: string;
 }
 
 export interface DoryFonts {
   family: string;
-  source: string;
-  format: string;
+  source?: string;
+  format?: string;
+  stylesheet?: string;
+  heading?: DoryFontDefinition;
+  mono?: DoryFontDefinition;
 }
 
 export interface DoryLogo {
@@ -85,6 +102,27 @@ export interface DoryAnalytics {
   };
 }
 
+export interface DorySeo {
+  /** Applied to page titles, e.g. "%s — WhoDB"; %s is the page title. Default: no template. */
+  titleTemplate?: string;
+  keywords?: string[];
+  author?: string;
+  /** Absolute URL or path resolved against config.url. */
+  ogImage?: string;
+  twitterCard?: 'summary' | 'summary_large_image';
+  /** e.g. "en_US" */
+  locale?: string;
+  /** Extra lines appended to robots.txt. */
+  robotsTxt?: string[];
+  /** Site-wide meta robots noindex (for staging environments). */
+  noindex?: boolean;
+}
+
+export interface DoryTheme {
+  mode?: 'light' | 'dark' | 'system';
+  radius?: string;
+}
+
 export interface DoryConfig {
   name: string;
   title?: string;
@@ -95,8 +133,10 @@ export interface DoryConfig {
   favicon: string;
   colors?: DoryColors;
   fonts?: DoryFonts;
+  theme?: DoryTheme;
   navigation: DoryNavigation;
   logo: DoryLogo;
   embed?: DoryEmbedConfig;
   analytics?: DoryAnalytics;
+  seo?: DorySeo;
 }

package/src/types/globals.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Window globals injected by the SSR build (see scripts/prerender).
+ */
+interface Window {
+  __DORY_FRONTMATTER__?: Array<Record<string, any>>;
+  __DORY_ROUTE__?: string;
+}

package/src/ui/header.tsx

@@ -11,6 +11,7 @@ import { ModeToggle } from '@clidey/ux';
 import { useIsEmbedded } from '../components/hooks';
 
 const config = docsConfig as DoryConfig;
+const isThemeForced = config.theme?.mode === 'dark' || config.theme?.mode === 'light';
 
 function TopLevelNavItem({ href, children, isActive }: { href: string; children: string; isActive?: boolean }) {
   return (
@@ -30,6 +31,13 @@ function TopLevelNavItem({ href, children, isActive }: { href: string; children:
   );
 }
 
+/**
+ * Site header with logo, top-level navigation, search, and theme toggle.
+ *
+ * SYNC NOTE: src/entry-server.tsx renders a static SSR copy of this header's
+ * structure (the <header> block inside render()). If you change the markup
+ * structure here, update entry-server.tsx to match or hydration will mismatch.
+ */
 export function Header({ className }: { className?: string }) {
   const [isScrolled, setIsScrolled] = useState(false);
   const pathname = usePathname();
@@ -53,13 +61,13 @@ export function Header({ className }: { className?: string }) {
   return (
     <header
       className={classNames(
-        'sticky top-0 z-50 flex flex-none flex-wrap items-center justify-between bg-white px-4 py-5 shadow-md shadow-gray-900/5 sm:px-6 lg:px-8 dark:shadow-none',
+        'dory-header sticky top-0 z-50 flex flex-none flex-wrap items-center justify-between px-4 py-5 sm:px-6 lg:px-8 border-b',
         className,
         {
-          'dark:bg-gray-900/95 dark:backdrop-blur-sm dark:[@supports(backdrop-filter:blur(0))]:bg-neutral-900/75': isScrolled,
-          'dark:bg-transparent': !isScrolled,
+          'backdrop-blur-sm': isScrolled,
         },
       )}
+      style={{ backgroundColor: 'var(--background)', borderColor: 'var(--border)' }}
     >
       <div className="relative flex justify-between gap-6 sm:gap-8 md:grow items-center w-full px-4">
         <div className="flex items-center grow gap-2">
@@ -90,7 +98,7 @@ export function Header({ className }: { className?: string }) {
           <MobileSearch />
           <Search />
           {
-            !isEmbedded &&
+            !isEmbedded && !isThemeForced &&
             <ModeToggle data-testid="mode-toggle" />
           }
           <MobileNavigation />

package/src/ui/layout.tsx

@@ -1,7 +1,9 @@
 import type { ComponentChildren } from 'preact';
 import { useCallback, useEffect, useMemo, useState } from 'preact/hooks';
 import { Navigation } from '../components/navigation';
-import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, ALL_PAGES, pathFromFilename, preloadFrontmatter, ALL_ASYNCAPI } from '../components/store';
+import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, preloadFrontmatter, ALL_ASYNCAPI, isFrontmatterReady } from '../components/store';
+import docsConfig from '../../docs/dory.json' with { type: 'json' };
+import type { DoryConfig } from '../types/config';
 import { usePathname } from '../components/hooks';
 import { OpenAPI } from '../mdx/open-api';
 import { AsyncAPI } from '../mdx/async-api';
@@ -16,6 +18,8 @@ import { useIsEmbedded } from '../components/hooks';
 import { ErrorBoundary } from '../components/error-boundary';
 import { cn } from '@clidey/ux';
 
+const config = docsConfig as DoryConfig;
+
 interface LayoutProps {
   children: ComponentChildren;
 }
@@ -24,9 +28,19 @@ const prompt = (pathname: string) => `Please read and analyze the content from t
   `Then, help me understand and answer any questions I have about it. ` +
   `Please provide clear, detailed explanations and examples where relevant.`;
 
+/**
+ * Main documentation layout: header, sidebar navigation, article content,
+ * table of contents, and prev/next links.
+ *
+ * SYNC NOTE: src/entry-server.tsx renders a static SSR copy of this layout's
+ * shell (the #container / sidebar nav / main / article wrappers in render()).
+ * If you change that markup structure here, update entry-server.tsx to match
+ * or hydration will mismatch.
+ */
 export default function Layout({ children }: LayoutProps) {
-  const [loading, setLoading] = useState(true);
-  const pathname = usePathname();
+  const [loading, setLoading] = useState(!isFrontmatterReady());
+  const rawPathname = usePathname();
+  const pathname = rawPathname === '/' ? ALL_NAVIGATION[0]?.groups[0]?.pages[0]?.href ?? '/' : rawPathname;
   const { showNotification } = useNotification();
   const isEmbedded = useIsEmbedded();
 
@@ -34,12 +48,17 @@ export default function Layout({ children }: LayoutProps) {
     window.open(`${window.location.origin}${pathname}.mdx`, '_blank');
   }, [pathname]);
 
-  const handleCopyMDX = useCallback(() => {
-    ALL_PAGES[pathFromFilename(pathname)]().then((mdx) => {
-      navigator.clipboard.writeText(mdx.default.toString());
-    });
-    showNotification('Copied to clipboard');
-  }, []);
+  const handleCopyMDX = useCallback(async () => {
+    try {
+      const response = await fetch(`${pathname}.mdx`);
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      await navigator.clipboard.writeText(await response.text());
+      showNotification('Copied to clipboard');
+    } catch (error) {
+      console.warn(`Failed to fetch ${pathname}.mdx:`, error);
+      showNotification('Could not copy MDX', 'The raw MDX file is not available.');
+    }
+  }, [pathname, showNotification]);
   const handleOpenChatGPT = useCallback(() => {
     const url = `https://chat.openai.com/?q=${encodeURIComponent(prompt(pathname))}`;
     window.open(url, '_blank');
@@ -69,9 +88,9 @@ export default function Layout({ children }: LayoutProps) {
   ], [handleOpenMDX, handleCopyMDX, handleOpenChatGPT, handleOpenAnthropic]);
 
   useEffect(() => {
-    // Try to preload frontmatter first (optimized approach)
+    // Try to preload frontmatter first (optimized approach).
+    // If inline data was available from SSR, preloadFrontmatter() resolves immediately.
     preloadFrontmatter().then(() => {
-      // If preloading succeeds, we're done
       setLoading(false);
     }).catch(() => {
       // Fallback to the original approach
@@ -87,6 +106,7 @@ export default function Layout({ children }: LayoutProps) {
     });
   }, [pathname]);
 
+
   const { title: group, group: title, page } = useMemo(() => {
     const group = ALL_NAVIGATION.flatMap((tab) =>
       tab.groups.find((group) =>
@@ -101,7 +121,9 @@ export default function Layout({ children }: LayoutProps) {
   // Update document title and meta tags when page changes
   useEffect(() => {
     if (page?.title) {
-      document.title = page.title;
+      // Mirror the build-time SSR title template (config.seo.titleTemplate, e.g. "%s — Site")
+      const titleTemplate = (config as { seo?: { titleTemplate?: string } }).seo?.titleTemplate;
+      document.title = titleTemplate ? titleTemplate.replace('%s', page.title) : page.title;
 
       // Update Open Graph title
       const ogTitle = document.querySelector('meta[property="og:title"]');
@@ -151,44 +173,20 @@ export default function Layout({ children }: LayoutProps) {
     }
     canonical.setAttribute('href', `${window.location.origin}${window.location.pathname}`);
 
-    // Add/update JSON-LD structured data
-    const structuredData = {
-      '@context': 'https://schema.org',
-      '@graph': [
-        {
-          '@type': 'Article',
-          'headline': page?.title || document.title,
-          'description': page?.description || '',
-        },
-        {
-          '@type': 'BreadcrumbList',
-          'itemListElement': [
-            {
-              '@type': 'ListItem',
-              'position': 1,
-              'name': 'Home',
-              'item': window.location.origin
-            },
-            ...(page?.title ? [{
-              '@type': 'ListItem',
-              'position': 2,
-              'name': page.title,
-              'item': window.location.href
-            }] : [])
-          ]
-        }
-      ]
-    };
-
-    let ldScript = document.querySelector('script[type="application/ld+json"]');
-    if (!ldScript) {
-      ldScript = document.createElement('script');
-      ldScript.setAttribute('type', 'application/ld+json');
-      document.head.appendChild(ldScript);
-    }
-    ldScript.textContent = JSON.stringify(structuredData);
+    // JSON-LD structured data is emitted at build time (prerender) — crawlers consume
+    // that version, so it is intentionally not rewritten on client-side navigation.
   }, [page]);
 
+  const isLandingPage = useMemo(() => {
+    const firstTab = ALL_NAVIGATION[0];
+    if (!firstTab) return false;
+    return (
+      firstTab.groups.length === 1 &&
+      firstTab.groups[0].pages.length === 1 &&
+      pathname === firstTab.groups[0].pages[0].href
+    );
+  }, [pathname]);
+
   const tab = useMemo(() => {
     return completeFrontMatter.find((page) => page.path === pathname);
   }, [pathname, loading]);
@@ -225,6 +223,28 @@ export default function Layout({ children }: LayoutProps) {
 
   if (loading) return <div className="h-[25vh] flex grow"><Loading /></div>;
 
+  if (isLandingPage) {
+    return (
+      <div className="flex w-full flex-col">
+        <Header />
+        <main className="w-full">
+          <ErrorBoundary fallback={(error) => (
+            <div className="flex flex-col items-center justify-center py-16 px-6 text-center">
+              <p className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
+                This page failed to render
+              </p>
+              <pre className="text-sm text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-900/30 border border-red-200 dark:border-red-800 rounded-md p-3 max-w-md overflow-auto">
+                {error.message}
+              </pre>
+            </div>
+          )}>
+            {children}
+          </ErrorBoundary>
+        </main>
+      </div>
+    );
+  }
+
   return (
     <div className="flex w-full flex-col">
       <Header />
@@ -248,14 +268,14 @@ export default function Layout({ children }: LayoutProps) {
               <div className="flex justify-between items-start">
                 <header className="mb-8">
                   {title && (
-                    <h1 className="font-display text-lg tracking-tight">
+                    <p className="dory-subtitle text-sm font-medium tracking-widest uppercase mb-2">
                       {title}
-                    </h1>
+                    </p>
                   )}
                   {group && (
-                    <p className="text-4xl tracking-tight">
+                    <h1 className="dory-page-title text-4xl tracking-tight">
                       {group}
-                    </p>
+                    </h1>
                   )}
                 </header>
                 {

package/src/ui/table-of-content.tsx

@@ -1,6 +1,20 @@
 import { useCallback, useEffect, useState } from 'react'
 import classNames from 'classnames'
 
+/**
+ * Slugifies heading text matching rehype-slug (github-slugger) behavior:
+ * lowercase, strip punctuation, spaces to dashes. Used only as a fallback
+ * for headings that did not get an id at build time, so client-assigned
+ * anchors agree with SSR-assigned ones.
+ */
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+    .replace(/\s+/g, '-')
+}
+
 export type Section = {
   id: string
   title: string
@@ -33,8 +47,11 @@ export function TableOfContents() {
         const style = window.getComputedStyle(heading)
         if (style.display === 'none' || style.visibility === 'hidden') return
 
-        const id = heading.id || heading.textContent?.toLowerCase().replace(/\s+/g, '-') || ''
-        heading.id = id
+        // Prefer the build-time id from rehype-slug; only assign when missing
+        const id = heading.id || slugify(heading.textContent || '')
+        if (!heading.id && id) {
+          heading.id = id
+        }
 
         if (heading.tagName === 'H2') {
           currentSection = {

package/src/utils/colors.ts

@@ -3,52 +3,72 @@ import type { DoryConfig } from '../types/config';
 
 const config = docsConfig as DoryConfig;
 
-/**
- * Converts hex color to RGB values for CSS variable usage
- */
 function hexToRgb(hex: string): string {
-  // Remove # if present
   const cleanHex = hex.replace('#', '');
-
-  // Parse hex values
   const r = parseInt(cleanHex.substring(0, 2), 16);
   const g = parseInt(cleanHex.substring(2, 4), 16);
   const b = parseInt(cleanHex.substring(4, 6), 16);
-
   return `${r} ${g} ${b}`;
 }
 
-/**
- * Load and apply brand colors from dory.json configuration
- * Sets CSS variables for use throughout the application
- */
 export function loadColors() {
   const { colors } = config;
   if (!colors) return;
 
-  // Set CSS variables on the root element for both light and dark modes
   const root = document.documentElement;
 
-  // Set primary color (used in both light and dark mode)
+  // Brand accent colors
   if (colors.primary) {
     root.style.setProperty('--brand-primary', colors.primary);
     root.style.setProperty('--brand-primary-rgb', hexToRgb(colors.primary));
+    root.style.setProperty('--brand-foreground', colors.primary);
   }
 
-  // Set light mode brand color
   if (colors.light) {
     root.style.setProperty('--brand-light', colors.light);
     root.style.setProperty('--brand-light-rgb', hexToRgb(colors.light));
   }
 
-  // Set dark mode brand color
   if (colors.dark) {
     root.style.setProperty('--brand-dark', colors.dark);
     root.style.setProperty('--brand-dark-rgb', hexToRgb(colors.dark));
   }
 
-  // Set the legacy variable for backward compatibility
-  if (colors.primary) {
-    root.style.setProperty('--brand-foreground', colors.primary);
+  // Override shadcn/ux theme variables
+  if (colors.background) {
+    root.style.setProperty('--background', colors.background);
+  }
+
+  if (colors.foreground) {
+    root.style.setProperty('--foreground', colors.foreground);
+    root.style.setProperty('--card-foreground', colors.foreground);
+    root.style.setProperty('--popover-foreground', colors.foreground);
+    root.style.setProperty('--secondary-foreground', colors.foreground);
+  }
+
+  if (colors.surface) {
+    root.style.setProperty('--card', colors.surface);
+    root.style.setProperty('--popover', colors.surface);
+    root.style.setProperty('--sidebar', colors.surface);
+  }
+
+  if (colors.surfaceElevated) {
+    root.style.setProperty('--muted', colors.surfaceElevated);
+    root.style.setProperty('--secondary', colors.surfaceElevated);
+  }
+
+  if (colors.mutedForeground) {
+    root.style.setProperty('--muted-foreground', colors.mutedForeground);
+  }
+
+  if (colors.border) {
+    root.style.setProperty('--border', colors.border);
+    root.style.setProperty('--input', colors.border);
+    root.style.setProperty('--sidebar-border', colors.border);
+  }
+
+  if (colors.accent) {
+    root.style.setProperty('--accent', colors.accent);
+    root.style.setProperty('--ring', colors.accent);
   }
 }