@clidey/dory 1.0.3 → 1.0.6

package/src/theme.scss

@@ -157,12 +157,13 @@ html, body, #app {
 }
 
 // === DEFAULT STYLES ===
-article h2:first-of-type {
+article hr:first-of-type {
     display: none;
 }
 
-article hr:first-of-type {
-    display: none;
+// A rule inside a specimen is the example itself, not a page divider.
+article .dory-specimen hr:first-of-type {
+    display: block;
 }
 
 article img {
@@ -193,3 +194,281 @@ article img {
     border: 0px;
     box-shadow: none !important;
 }
+
+// === EDITORIAL STYLE (Dory v2) ===
+:root {
+    --dory-code-string: #b65401;
+}
+
+:root.dark {
+    --dory-code-string: #f4a261;
+}
+
+.font-heading {
+    font-family: var(--font-heading, var(--font-body, inherit));
+}
+
+.dory-page-title {
+    font-family: var(--font-heading, var(--font-body, inherit));
+    font-size: 1.625rem;
+    font-weight: 700;
+    line-height: 1.15;
+    letter-spacing: -0.025em;
+}
+
+.dory-subtitle {
+    font-family: var(--font-mono, monospace);
+    font-size: 11px;
+    letter-spacing: 0.18em;
+    color: var(--muted-foreground);
+}
+
+article {
+    counter-reset: dory-section;
+    font-size: 0.875rem;
+    line-height: 1.6;
+
+    .dory-h1 {
+        font-size: 1.625rem;
+        font-weight: 700;
+        line-height: 1.15;
+        letter-spacing: -0.025em;
+    }
+
+    .dory-h2 {
+        counter-increment: dory-section;
+        display: flex;
+        align-items: center;
+        gap: 0.625rem;
+        font-size: 1.3125rem;
+        font-weight: 700;
+        line-height: 1.2;
+        letter-spacing: -0.02em;
+
+        &::before {
+            content: counter(dory-section, decimal-leading-zero);
+            flex-shrink: 0;
+            padding: 0.0625rem 0.375rem;
+            border: 1px solid var(--border);
+            border-radius: 0.3125rem;
+            background: var(--muted);
+            font-family: var(--font-mono, monospace);
+            font-size: 0.6875rem;
+            font-weight: 400;
+            letter-spacing: 0;
+            color: var(--muted-foreground);
+        }
+
+        + p {
+            color: var(--muted-foreground);
+        }
+    }
+
+    .dory-h3 {
+        font-size: 1.0625rem;
+        font-weight: 700;
+        letter-spacing: -0.01em;
+    }
+
+    .dory-h4 {
+        font-size: 0.9375rem;
+        font-weight: 600;
+        letter-spacing: -0.005em;
+    }
+
+    // Unordered: small brand-colored squares. Ordered: mono two-digit counters.
+    .dory-ul > li::before {
+        content: "";
+        position: absolute;
+        left: 0.5rem;
+        top: 0.7em;
+        width: 0.375rem;
+        height: 0.375rem;
+        border-radius: 0.125rem;
+        background: var(--primary);
+    }
+
+    .dory-ul .dory-ul > li {
+        color: var(--muted-foreground);
+
+        &::before {
+            background: var(--muted-foreground);
+        }
+    }
+
+    .dory-ol {
+        counter-reset: dory-ol;
+
+        > li {
+            counter-increment: dory-ol;
+
+            &::before {
+                content: counter(dory-ol, decimal-leading-zero);
+                position: absolute;
+                left: 0;
+                top: 0.15em;
+                font-family: var(--font-mono, monospace);
+                font-size: 0.6875rem;
+                color: var(--primary);
+            }
+        }
+    }
+
+    // Task lists (GFM) render a checkbox as the first child, so drop the bullet.
+    li:has(> input[type="checkbox"]) {
+        padding-left: 0;
+
+        &::before {
+            display: none;
+        }
+    }
+
+    input[type="checkbox"] {
+        width: 0.9375rem;
+        height: 0.9375rem;
+        margin-right: 0.5rem;
+        vertical-align: -0.2em;
+        accent-color: var(--primary);
+    }
+
+    blockquote {
+        margin: 1.5rem 0;
+        padding-left: 1rem;
+        border-left: 2px solid var(--primary);
+        font-size: 0.9375rem;
+    }
+
+    kbd {
+        padding: 0.0625rem 0.375rem;
+        border: 1px solid var(--border);
+        border-bottom-width: 2px;
+        border-radius: 0.375rem;
+        background: var(--card);
+        font-family: var(--font-mono, monospace);
+        font-size: 0.8125em;
+    }
+
+    mark {
+        padding: 0.0625rem 0.3rem;
+        border-radius: 0.25rem;
+        background: var(--highlight);
+        color: var(--highlight-foreground);
+    }
+}
+
+// === CODE LINES ===
+// Lines bleed to the frame edges (CodeBody padding is 1rem left / 3rem right)
+// so highlighted and diff rows read as full-width bands.
+.dory-code {
+    .dory-line {
+        display: block;
+        margin: 0 -3rem 0 -1rem;
+        padding: 0 3rem 0 calc(1rem - 2px);
+        border-left: 2px solid transparent;
+    }
+
+    .dory-line-highlight {
+        background: var(--accent);
+        border-left-color: var(--primary);
+    }
+
+    .dory-line-add {
+        background: var(--success-muted);
+        border-left-color: #2f7d4a;
+    }
+
+    .dory-line-del {
+        background: color-mix(in oklch, var(--destructive) 10%, transparent);
+        border-left-color: var(--destructive);
+    }
+
+    .dory-line-number {
+        display: inline-block;
+        width: 1.25rem;
+        margin-right: 1rem;
+        color: var(--muted-foreground);
+        user-select: none;
+    }
+
+    .dory-line-marker {
+        display: inline-block;
+        width: 2rem;
+        user-select: none;
+    }
+
+    .dory-line-add .dory-line-marker {
+        color: #2f7d4a;
+    }
+
+    .dory-line-del .dory-line-marker {
+        color: var(--destructive);
+    }
+}
+
+:root.dark .dory-code .dory-line-add {
+    border-left-color: #6fbf87;
+
+    .dory-line-marker {
+        color: #6fbf87;
+    }
+}
+
+// === PDF DETAILS ===
+.dory-lead {
+    margin-top: 0.75rem;
+    font-size: 0.9375rem;
+    line-height: 1.6;
+    color: var(--foreground);
+}
+
+article .dory-h2 .dory-anchor {
+    margin-left: auto;
+    font-family: var(--font-mono, monospace);
+    font-size: 0.8125rem;
+    font-weight: 400;
+    letter-spacing: 0;
+    color: var(--muted-foreground);
+    text-decoration: none;
+
+    &:hover {
+        color: var(--primary);
+    }
+}
+
+// Optional numbering for CardGroup and AccordionGroup (numbered prop)
+.dory-cards-numbered {
+    counter-reset: dory-card;
+
+    .dory-card {
+        counter-increment: dory-card;
+
+        &::before {
+            content: counter(dory-card, decimal-leading-zero);
+            display: block;
+            margin-bottom: 1.25rem;
+            font-family: var(--font-mono, monospace);
+            font-size: 0.75rem;
+            color: var(--primary);
+        }
+    }
+}
+
+.dory-accordion-numbered {
+    counter-reset: dory-accordion;
+
+    [data-slot="accordion-item"] {
+        counter-increment: dory-accordion;
+    }
+
+    [data-slot="accordion-trigger"] > div::before {
+        content: counter(dory-accordion, decimal-leading-zero);
+        margin-right: 0.25rem;
+        font-family: var(--font-mono, monospace);
+        font-size: 0.6875rem;
+        color: var(--primary);
+    }
+}
+
+.dory-latex-inline .katex {
+    font-size: 1.05em;
+}

package/src/types/config.ts

@@ -128,7 +128,10 @@ export interface DoryConfig {
   title?: string;
   description?: string;
   image?: string;
+  /** Origin the site is published at, e.g. "https://example.com" (no base path). */
   url?: string;
+  /** Path prefix the site is served under, e.g. "/docs". Default: served at the root. */
+  basePath?: string;
   twitter?: string;
   favicon: string;
   colors?: DoryColors;

package/src/ui/header.tsx

@@ -9,6 +9,7 @@ import { ALL_NAVIGATION } from '../components/store';
 import { MobileNavigation } from './mobile-navigation';
 import { ModeToggle } from '@clidey/ux';
 import { useIsEmbedded } from '../components/hooks';
+import { assetUrl } from '../utils/base-path';
 
 const config = docsConfig as DoryConfig;
 const isThemeForced = config.theme?.mode === 'dark' || config.theme?.mode === 'light';
@@ -44,7 +45,7 @@ export function Header({ className }: { className?: string }) {
   const isEmbedded = useIsEmbedded();
 
   const { light, dark } = useMemo(() => {
-    return { light: config.logo.light, dark: config.logo.dark };
+    return { light: assetUrl(config.logo.light), dark: assetUrl(config.logo.dark) };
   }, []);
 
   useEffect(() => {
@@ -71,8 +72,8 @@ export function Header({ className }: { className?: string }) {
     >
       <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">
-          <img src={`/${light}`} alt="logo" className="w-8 hidden dark:block" />
-          <img src={`/${dark}`} alt="logo" className="w-8 block dark:hidden" />
+          <img src={light} alt="logo" className="w-8 hidden dark:block" />
+          <img src={dark} alt="logo" className="w-8 block dark:hidden" />
           <h1 className="text-base lg:text-2xl font-bold">{config.name}</h1>
         </div>
         <nav className="hidden md:block">

package/src/ui/layout.tsx

@@ -1,5 +1,5 @@
 import type { ComponentChildren } from 'preact';
-import { useCallback, useEffect, useMemo, useState } from 'preact/hooks';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks';
 import { Navigation } from '../components/navigation';
 import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, preloadFrontmatter, ALL_ASYNCAPI, isFrontmatterReady } from '../components/store';
 import docsConfig from '../../docs/dory.json' with { type: 'json' };
@@ -10,6 +10,7 @@ import { AsyncAPI } from '../mdx/async-api';
 import { Header } from './header';
 import { PrevNextLinks } from './prev-next-link';
 import { TableOfContents } from './table-of-content';
+import { PageMeta } from './page-meta';
 import { Loading } from '../components/loading';
 import Dropdown from '../components/dropdown';
 import { useNotification } from '../components/notification';
@@ -17,6 +18,7 @@ import { SparkleIcon } from 'lucide-react';
 import { useIsEmbedded } from '../components/hooks';
 import { ErrorBoundary } from '../components/error-boundary';
 import { cn } from '@clidey/ux';
+import { withBase } from '../utils/base-path';
 
 const config = docsConfig as DoryConfig;
 
@@ -24,7 +26,7 @@ interface LayoutProps {
   children: ComponentChildren;
 }
 
-const prompt = (pathname: string) => `Please read and analyze the content from this documentation page: ${window.location.origin}${pathname}.mdx\n\n` +
+const prompt = (pathname: string) => `Please read and analyze the content from this documentation page: ${window.location.origin}${withBase(pathname)}.mdx\n\n` +
   `Then, help me understand and answer any questions I have about it. ` +
   `Please provide clear, detailed explanations and examples where relevant.`;
 
@@ -44,13 +46,27 @@ export default function Layout({ children }: LayoutProps) {
   const { showNotification } = useNotification();
   const isEmbedded = useIsEmbedded();
 
+  // Client-side navigation keeps the previous scroll position, so start each new
+  // page at the top. The initial load keeps the browser's own position, and a
+  // hash means an in-page anchor is the target.
+  const isFirstRender = useRef(true);
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+    if (!window.location.hash) {
+      window.scrollTo(0, 0);
+    }
+  }, [pathname]);
+
   const handleOpenMDX = useCallback(() => {
-    window.open(`${window.location.origin}${pathname}.mdx`, '_blank');
+    window.open(`${window.location.origin}${withBase(pathname)}.mdx`, '_blank');
   }, [pathname]);
 
   const handleCopyMDX = useCallback(async () => {
     try {
-      const response = await fetch(`${pathname}.mdx`);
+      const response = await fetch(`${withBase(pathname)}.mdx`);
       if (!response.ok) throw new Error(`HTTP ${response.status}`);
       await navigator.clipboard.writeText(await response.text());
       showNotification('Copied to clipboard');
@@ -277,12 +293,14 @@ export default function Layout({ children }: LayoutProps) {
                       {group}
                     </h1>
                   )}
+                  {page?.lead && <p className="dory-lead">{page.lead}</p>}
                 </header>
                 {
                   openAPIJSON == null && asyncAPIJSON == null &&
                   <Dropdown className="gap-0" buttonLabel={<SparkleIcon className="w-4 h-4" />} items={dropdownItems} />
                 }
               </div>
+              <PageMeta meta={page?.meta} />
               <div className="flex-1 min-h-[calc(100vh-2rem)]">
                 <ErrorBoundary fallback={(error) => (
                   <div className="flex flex-col items-center justify-center py-16 px-6 text-center">

package/src/ui/page-meta.tsx

@@ -0,0 +1,37 @@
+type MetaValue = string | number | boolean | Date
+
+const isoDate = /^\d{4}-\d{2}-\d{2}(T00:00:00(\.000)?Z)?$/
+
+function formatValue(value: MetaValue): string {
+  const date = value instanceof Date ? value : typeof value === 'string' && isoDate.test(value) ? new Date(value) : null
+  if (date && !Number.isNaN(date.getTime())) {
+    return date.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' })
+  }
+  return String(value)
+}
+
+/**
+ * Label/value strip under the page title, from the frontmatter `meta` map:
+ *
+ *   meta:
+ *     Edition: Community
+ *     Updated: 2026-10-12
+ *
+ * YAML dates render as "12 Oct 2026". Renders nothing when `meta` is absent.
+ */
+export function PageMeta({ meta }: { meta?: Record<string, MetaValue> }) {
+  if (!meta || typeof meta !== 'object') return null
+  const entries = Object.entries(meta)
+  if (entries.length === 0) return null
+
+  return (
+    <dl className="dory-page-meta mb-8 grid grid-cols-2 gap-x-6 gap-y-3 border-y border-[var(--border)] py-3 sm:grid-cols-3">
+      {entries.map(([label, value]) => (
+        <div key={label}>
+          <dt className="font-mono text-[11px] uppercase tracking-[0.18em] text-muted-foreground">{label}</dt>
+          <dd className="mt-0.5 text-sm font-semibold text-foreground">{formatValue(value)}</dd>
+        </div>
+      ))}
+    </dl>
+  )
+}

package/src/ui/prev-next-link.tsx

@@ -1,4 +1,5 @@
 import { ArrowRightIcon } from "@heroicons/react/24/outline";
+import { withBase } from '../utils/base-path';
 import classNames from "classnames";
 import { ALL_NAVIGATION } from "../components/store";
 import { usePathname } from "../components/hooks";
@@ -15,15 +16,15 @@ function PageLink({
 }) {
   return (
     <div {...props}>
-      <p className="font-display text-sm font-medium">
+      <p className="font-display text-xs font-medium text-muted-foreground">
         {dir === 'next' ? 'Next' : 'Previous'}
       </p>
       <div className="mt-1">
-        <a href={href} className={classNames('flex items-center gap-x-1 text-base font-semibold hover:opacity-80', {
+        <a href={withBase(href)} className={classNames('flex items-center gap-x-1 text-sm font-semibold hover:opacity-80', {
             'flex-row-reverse': dir === 'previous',
           },
         )}>
-          <p className={classNames("flex items-center gap-x-1 text-base font-semibold hover:opacity-80", {
+          <p className={classNames("flex items-center gap-x-1 text-sm font-semibold hover:opacity-80", {
             "flex-row-reverse": dir === "previous"
           })}>
             {title}

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

@@ -41,6 +41,14 @@ export function TableOfContents() {
       const sections: Section[] = []
       let currentSection: Section | null = null
 
+      // Heading text without the trailing "#" anchor link
+      const headingText = (heading: Element) =>
+        Array.from(heading.childNodes)
+          .filter((node) => !(node instanceof Element && node.classList.contains('dory-anchor')))
+          .map((node) => node.textContent ?? '')
+          .join('')
+          .trim()
+
       headings.forEach((heading) => {
         // Check if heading is a valid Element and is visible
         if (!(heading instanceof Element)) return
@@ -48,7 +56,7 @@ export function TableOfContents() {
         if (style.display === 'none' || style.visibility === 'hidden') return
 
         // Prefer the build-time id from rehype-slug; only assign when missing
-        const id = heading.id || slugify(heading.textContent || '')
+        const id = heading.id || slugify(headingText(heading))
         if (!heading.id && id) {
           heading.id = id
         }
@@ -56,14 +64,14 @@ export function TableOfContents() {
         if (heading.tagName === 'H2') {
           currentSection = {
             id,
-            title: heading.textContent || '',
+            title: headingText(heading),
             children: []
           }
           sections.push(currentSection)
         } else if (heading.tagName === 'H3' && currentSection) {
           currentSection.children.push({
             id,
-            title: heading.textContent || ''
+            title: headingText(heading)
           })
         }
       })

package/src/utils/base-path.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { assetUrl, joinBasePath, normalizeBasePath } from './base-path';
+
+describe('normalizeBasePath', () => {
+  it('normalizes slashes', () => {
+    for (const value of ['docs', '/docs', '/docs/', ' /docs/ ', '//docs//']) {
+      expect(normalizeBasePath(value)).toBe('/docs');
+    }
+    expect(normalizeBasePath('/a/b/')).toBe('/a/b');
+  });
+
+  it('treats root and non-strings as no base', () => {
+    for (const value of ['', '/', '   ', undefined, null, 3]) {
+      expect(normalizeBasePath(value)).toBe('');
+    }
+  });
+});
+
+describe('joinBasePath', () => {
+  it('prefixes root-relative paths', () => {
+    expect(joinBasePath('/docs', '/intro')).toBe('/docs/intro');
+    expect(joinBasePath('/docs', '/')).toBe('/docs/');
+    expect(joinBasePath('/docs', '/frontmatter.json')).toBe('/docs/frontmatter.json');
+  });
+
+  it('is a no-op without a base', () => {
+    expect(joinBasePath('', '/intro')).toBe('/intro');
+  });
+
+  it('does not double-prefix or touch non-root URLs', () => {
+    expect(joinBasePath('/docs', '/docs/intro')).toBe('/docs/intro');
+    expect(joinBasePath('/docs', '/docs')).toBe('/docs');
+    expect(joinBasePath('/docs', '/docsy/intro')).toBe('/docs/docsy/intro');
+    for (const url of ['https://x.dev/a', '//cdn.dev/a', '#top', 'relative/a', 'mailto:a@b.c']) {
+      expect(joinBasePath('/docs', url)).toBe(url);
+    }
+  });
+});
+
+describe('assetUrl', () => {
+  it('strips config-style prefixes', () => {
+    expect(assetUrl('./logo/logo.png')).toBe('/logo/logo.png');
+    expect(assetUrl('logo/logo.png')).toBe('/logo/logo.png');
+    expect(assetUrl('/logo/logo.png')).toBe('/logo/logo.png');
+  });
+});

package/src/utils/base-path.ts

@@ -0,0 +1,41 @@
+/// <reference types="vite/client" />
+
+/**
+ * Normalizes a configured base path to "" (site served at the origin root) or
+ * "/segment[/more]" with a leading slash and no trailing slash. Accepts
+ * "docs", "/docs", "/docs/" and "/" interchangeably; non-strings yield "".
+ */
+export function normalizeBasePath(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim().replace(/^\/+|\/+$/g, '');
+  return trimmed ? `/${trimmed}` : '';
+}
+
+/**
+ * Prefixes a root-relative path ("/x") with `base`. Protocol URLs,
+ * protocol-relative URLs, anchors and paths already under `base` are
+ * returned unchanged.
+ */
+export function joinBasePath(base: string, path: string): string {
+  if (!base || !path.startsWith('/') || path.startsWith('//')) return path;
+  if (path === base || path.startsWith(`${base}/`)) return path;
+  return `${base}${path}`;
+}
+
+/**
+ * The base path the site is served under, from Vite's `base` (which the
+ * configs derive from `basePath` in dory.json). "" when served at the root.
+ */
+export const BASE_PATH = normalizeBasePath(
+  typeof import.meta.env !== 'undefined' ? import.meta.env.BASE_URL : ''
+);
+
+/** Prefixes a root-relative path with the configured base path. */
+export function withBase(path: string): string {
+  return joinBasePath(BASE_PATH, path);
+}
+
+/** Resolves a dory.json asset path such as "./logo/logo.png" to a site URL. */
+export function assetUrl(path: string): string {
+  return withBase(`/${path.replace(/^\.?\/*/, '')}`);
+}

package/vite.config.ssr.ts

@@ -3,11 +3,14 @@ import preact from '@preact/preset-vite';
 import mdx from '@mdx-js/rollup';
 import { unifiedMdxPreprocessor } from './src/plugins/unified-mdx-plugin';
 import { getMdxConfig } from './src/config/mdx';
+import { getBasePath, readDoryConfig } from './src/plugins/shared';
 
 // Minimal Vite config for the SSR build.
 // Only includes plugins needed for MDX compilation — no sitemap, prerender,
 // analytics, or other build-time plugins that target the client output.
 export default defineConfig({
+  // Must match vite.config.ts so SSR markup uses the same base-prefixed URLs.
+  base: `${getBasePath(readDoryConfig())}/`,
   plugins: [
     unifiedMdxPreprocessor(),
     preact(),

package/vite.config.ts

@@ -15,8 +15,11 @@ import { sitemapGenerator } from './src/plugins/sitemap-generator';
 import { robotsGenerator } from './src/plugins/robots-generator';
 import { prerender } from './src/plugins/prerender';
 import { getMdxConfig } from './src/config/mdx';
+import { getBasePath, readDoryConfig } from './src/plugins/shared';
 
 export default defineConfig(({ command }) => ({
+  // Serve and build under `basePath` from dory.json (asset URLs, import.meta.env.BASE_URL).
+  base: `${getBasePath(readDoryConfig())}/`,
   plugins: [
     // SINGLE SOURCE OF TRUTH: All MDX preprocessing happens in src/mdx/processor.ts
     htmlFilesMiddleware(), // Must be first to intercept HTML file requests