svelte-docsmith 0.6.0 → 0.8.0

package/README.md

@@ -3,6 +3,10 @@
 [![NPM version](https://img.shields.io/npm/v/svelte-docsmith.svg?style=flat)](https://www.npmjs.com/package/svelte-docsmith)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/geodask/svelte-docsmith/master/.github/assets/hero.png" alt="Svelte DocSmith: craft documentation worthy of legend" width="100%" />
+</p>
+
 The documentation framework for Svelte 5 library authors whose interactive
 examples need to live inside one real, stateful SvelteKit app, not sandboxed as
 isolated islands.
@@ -169,8 +173,8 @@ plugin you already added:
 
 ## Themes
 
-Eleven presets ship in the box. Pick one with a single import after the base
-contract:
+Eleven presets ship in the box. **Darkmatter** is the default, applied by
+`theme.css`; import any other preset after it to switch:
 
 ```css
 @import 'svelte-docsmith/theme.css';

package/dist/buildtime/vite/collect.js

@@ -4,6 +4,34 @@ import { listPageFiles } from './pages.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { extractLlmsContent, extractSearchText, extractToc, readingMinutes } from './extract.js';
 import { lastCommitDate } from './git.js';
+/**
+ * Read a page's `section` frontmatter: a string is one level, an array is a
+ * nested group path. Non-string array members are dropped; anything else is
+ * treated as no section.
+ */
+function readSection(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        const segs = value.filter((s) => typeof s === 'string');
+        return segs.length ? segs : undefined;
+    }
+    return undefined;
+}
+/** The most-specific (last) group segment, for the compact search-result pill. */
+function sectionLabel(value) {
+    const section = readSection(value);
+    if (section === undefined)
+        return undefined;
+    return Array.isArray(section) ? section[section.length - 1] : section;
+}
+/** The full group path joined, so nested pages group under one llms.txt heading. */
+function sectionKey(value) {
+    const section = readSection(value);
+    if (section === undefined)
+        return undefined;
+    return Array.isArray(section) ? section.join(' / ') : section;
+}
 /**
  * Walk every nav-worthy page under `contentDir` once: a page is nav-worthy when
  * its frontmatter has a string `title`. Yields the raw source, parsed
@@ -39,7 +67,7 @@ export function collectDocs(contentDir, routesDir) {
             title,
             path: url,
             description: typeof front.description === 'string' ? front.description : undefined,
-            section: typeof front.section === 'string' ? front.section : undefined,
+            section: readSection(front.section),
             order: typeof front.order === 'number' ? front.order : undefined,
             sourcePath: path.relative(process.cwd(), file).split(path.sep).join('/'),
             lastUpdated: lastCommitDate(file),
@@ -69,7 +97,7 @@ export function collectSearchDocs(contentDir, routesDir) {
         docs.push({
             path: url,
             title,
-            section: typeof front.section === 'string' ? front.section : undefined,
+            section: sectionLabel(front.section),
             description: typeof front.description === 'string' ? front.description : undefined,
             headings: extractToc(source).map((entry) => entry.title),
             text: extractSearchText(source)
@@ -91,7 +119,7 @@ export function collectLlmsDocs(contentDir, routesDir) {
         docs.push({
             path: url,
             title,
-            section: typeof front.section === 'string' ? front.section : undefined,
+            section: sectionKey(front.section),
             order: typeof front.order === 'number' ? front.order : undefined,
             description: typeof front.description === 'string' ? front.description : undefined,
             content: extractLlmsContent(source, title)

package/dist/components/chrome/announcement-bar.svelte

@@ -0,0 +1,188 @@
+<script lang="ts">
+	import { BROWSER } from 'esm-env';
+	import X from '@lucide/svelte/icons/x';
+	import ArrowRight from '@lucide/svelte/icons/arrow-right';
+	import type { DocsmithAnnouncement } from '../../core/index.js';
+
+	const { announcement }: { announcement: DocsmithAnnouncement } = $props();
+
+	const dismissible = $derived(announcement.dismissible ?? true);
+	const storageKey = $derived('docsmith-announcement:' + (announcement.id ?? announcement.text));
+
+	// Rendered visible on the server; the dismissal is read after mount so the
+	// first client render matches the server and there's no hydration mismatch.
+	// The blocking <head> script below is what actually prevents the flash on a
+	// reload — this effect just removes the (already-hidden) element from the DOM.
+	let dismissed = $state(false);
+	$effect(() => {
+		if (!dismissible) return;
+		try {
+			dismissed = localStorage.getItem(storageKey) === '1';
+		} catch {
+			// storage unavailable; treat as not dismissed
+		}
+	});
+
+	function dismiss() {
+		dismissed = true;
+		if (BROWSER) {
+			try {
+				localStorage.setItem(storageKey, '1');
+			} catch {
+				// storage unavailable; dismissal holds for this session only
+			}
+		}
+	}
+
+	// A blocking snippet run in <head> before first paint: if this bar was
+	// already dismissed, hide it via an injected style so it is never painted
+	// and can't shift the layout when hydration removes it. Targets a stable
+	// class (not the scoped one) so it also works in dev, where component CSS is
+	// injected after paint. localStorage is read here because it isn't available
+	// during SSR.
+	const preventFlashScript = $derived(
+		`(function(){try{if(localStorage.getItem(${JSON.stringify(storageKey)})==="1"){` +
+			`var s=document.createElement("style");` +
+			`s.textContent=".docsmith-announcement{display:none!important}";` +
+			`document.head.appendChild(s)}}catch(e){}})()`
+	);
+</script>
+
+<svelte:head>
+	{#if dismissible}
+		<!-- The `<\/script>` escape keeps the Svelte parser from ending the tag early. -->
+		<!-- eslint-disable-next-line svelte/no-at-html-tags, no-useless-escape -->
+		{@html `<script>${preventFlashScript}<\/script>`}
+	{/if}
+</svelte:head>
+
+{#if !dismissed}
+	<div class="announcement docsmith-announcement" role="region" aria-label="Announcement">
+		{#if announcement.href}
+			<a
+				class="announcement-body announcement-link"
+				href={announcement.href}
+				target={announcement.external ? '_blank' : undefined}
+				rel={announcement.external ? 'noopener noreferrer' : undefined}
+			>
+				{#if announcement.tag}<span class="announcement-tag">{announcement.tag}</span>{/if}
+				<span class="announcement-text">{announcement.text}</span>
+				<ArrowRight class="announcement-arrow size-3.5" aria-hidden="true" />
+			</a>
+		{:else}
+			<div class="announcement-body">
+				{#if announcement.tag}<span class="announcement-tag">{announcement.tag}</span>{/if}
+				<span class="announcement-text">{announcement.text}</span>
+			</div>
+		{/if}
+
+		{#if dismissible}
+			<button
+				type="button"
+				class="announcement-dismiss"
+				onclick={dismiss}
+				aria-label="Dismiss announcement"
+			>
+				<X class="size-3.5" aria-hidden="true" />
+			</button>
+		{/if}
+	</div>
+{/if}
+
+<style>
+	/* A thin bar above the header. The warm accent is spent on a solid tag, not
+	   a full-width wash, so it reads as a deliberate mark; text stays on
+	   --foreground for AA contrast. */
+	.announcement {
+		position: relative;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		min-height: 2.5rem;
+		padding: 0.4rem 2.75rem;
+		background: color-mix(in oklch, var(--primary) 6%, var(--background));
+		border-bottom: 1px solid color-mix(in oklch, var(--primary) 20%, var(--border));
+		color: var(--foreground);
+		font-size: 0.8125rem;
+		line-height: 1.4;
+		text-align: center;
+	}
+
+	.announcement-body {
+		display: inline-flex;
+		flex-wrap: wrap;
+		align-items: center;
+		justify-content: center;
+		gap: 0.3rem 0.55rem;
+		min-width: 0;
+		color: var(--foreground);
+		text-decoration: none;
+	}
+
+	/* Solid brand pill — the sanctioned primary-foreground-on-primary pairing, so
+	   it stays legible in both themes and matches the props-table "required" pill. */
+	.announcement-tag {
+		flex-shrink: 0;
+		background: var(--primary);
+		color: var(--primary-foreground);
+		font-family: var(--font-mono, ui-monospace, monospace);
+		font-size: 0.625rem;
+		font-weight: 700;
+		letter-spacing: 0.04em;
+		text-transform: uppercase;
+		padding: 0.15rem 0.5rem;
+		border-radius: 9999px;
+		line-height: 1.5;
+	}
+
+	.announcement-text {
+		color: var(--foreground);
+	}
+
+	.announcement-link :global(.announcement-arrow) {
+		flex-shrink: 0;
+		color: var(--primary);
+		transition: transform 0.2s ease-out;
+	}
+	.announcement-link:hover :global(.announcement-arrow) {
+		transform: translateX(2px);
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.announcement-link :global(.announcement-arrow) {
+			transition: none;
+		}
+	}
+
+	/* Dismiss sits at the trailing edge, inside the bar's padding. */
+	.announcement-dismiss {
+		position: absolute;
+		top: 50%;
+		right: 0.5rem;
+		transform: translateY(-50%);
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		padding: 0.35rem;
+		border: 0;
+		background: transparent;
+		border-radius: 0.375rem;
+		color: var(--muted-foreground);
+		cursor: pointer;
+		transition:
+			color 0.15s ease-out,
+			background-color 0.15s ease-out;
+	}
+	.announcement-dismiss:hover {
+		color: var(--foreground);
+		background: color-mix(in oklch, var(--foreground) 8%, transparent);
+	}
+	.announcement-dismiss:focus-visible {
+		outline: 2px solid var(--primary);
+		outline-offset: 1px;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.announcement-dismiss {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/chrome/announcement-bar.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { DocsmithAnnouncement } from '../../core/index.js';
+type $$ComponentProps = {
+    announcement: DocsmithAnnouncement;
+};
+declare const AnnouncementBar: import("svelte").Component<$$ComponentProps, {}, "">;
+type AnnouncementBar = ReturnType<typeof AnnouncementBar>;
+export default AnnouncementBar;

package/dist/components/docs/tabs-sync.svelte.d.ts

@@ -0,0 +1,10 @@
+/** The current selection for a sync key, or `undefined` if none is stored. */
+export declare function syncedValue(key: string): string | undefined;
+/** Record a selection for a sync key and persist it. Client-only. */
+export declare function setSyncedValue(key: string, value: string): void;
+/**
+ * Load a key's persisted selection into the reactive store, once, on the
+ * client. Called from an effect (after hydration) so the first client render
+ * still matches the server's default and there is no hydration mismatch.
+ */
+export declare function hydrateSyncedValue(key: string): void;

package/dist/components/docs/tabs-sync.svelte.js

@@ -0,0 +1,59 @@
+import { BROWSER } from 'esm-env';
+// Cross-instance tab sync. Every <Tabs syncKey="x"> reads and writes the same
+// entry here, so choosing "pnpm" in one code block selects it in every block
+// with that key, and the choice survives reloads and navigation.
+//
+// The store is a module singleton. It is only ever written on the client (all
+// writers below are BROWSER-guarded), so on the server it stays empty and each
+// request falls back to the default tab — no cross-request state leakage.
+const PREFIX = 'docsmith-tabs:';
+const selections = $state({});
+let listening = false;
+function listenForOtherWindows() {
+    if (listening || !BROWSER)
+        return;
+    listening = true;
+    // Mirror choices made in other tabs/windows of the same site.
+    window.addEventListener('storage', (event) => {
+        if (event.key?.startsWith(PREFIX) && event.newValue !== null) {
+            selections[event.key.slice(PREFIX.length)] = event.newValue;
+        }
+    });
+}
+/** The current selection for a sync key, or `undefined` if none is stored. */
+export function syncedValue(key) {
+    return selections[key];
+}
+/** Record a selection for a sync key and persist it. Client-only. */
+export function setSyncedValue(key, value) {
+    if (!BROWSER || selections[key] === value)
+        return;
+    selections[key] = value;
+    try {
+        localStorage.setItem(PREFIX + key, value);
+    }
+    catch {
+        // Storage can be unavailable (private mode, quota); sync stays in-memory
+        // for this session rather than throwing.
+    }
+}
+/**
+ * Load a key's persisted selection into the reactive store, once, on the
+ * client. Called from an effect (after hydration) so the first client render
+ * still matches the server's default and there is no hydration mismatch.
+ */
+export function hydrateSyncedValue(key) {
+    if (!BROWSER)
+        return;
+    listenForOtherWindows();
+    if (key in selections)
+        return;
+    try {
+        const stored = localStorage.getItem(PREFIX + key);
+        if (stored !== null)
+            selections[key] = stored;
+    }
+    catch {
+        // ignore unreadable storage
+    }
+}

package/dist/components/docs/tabs.svelte

@@ -22,29 +22,65 @@
 	import { setContext, type Snippet } from 'svelte';
 	import * as TabsPrimitive from '../shadcn/tabs/index.js';
 	import TabsPhaseScope from './tabs-phase.svelte';
+	import { syncedValue, setSyncedValue, hydrateSyncedValue } from './tabs-sync.svelte.js';
 
 	const {
 		value,
+		syncKey,
 		children
 	}: {
 		/** Value/label of the tab selected by default. Defaults to the first tab. */
 		value?: string;
+		/**
+		 * Sync group. Every `<Tabs>` with the same `syncKey` shares its selection
+		 * (e.g. `"pkg"` for npm/pnpm/yarn blocks), and the choice is remembered
+		 * across reloads and navigation.
+		 */
+		syncKey?: string;
 		children: Snippet;
 	} = $props();
 
-	// The first <TabItem> to register wins the default selection. Captured during
-	// the collect pass, which renders (below) before <Tabs.Root> reads it — so the
-	// correct panel is already selected in the server-rendered HTML.
-	let firstValue = $state<string | undefined>();
+	// Each <TabItem> registers its value during the collect pass, which renders
+	// (below) before <Tabs.Root> reads them — so the right panel is already
+	// selected in the server-rendered HTML. The first registered value is the
+	// default; the full list validates a restored sync choice against this block.
+	let values = $state<string[]>([]);
 	setContext<TabsContext>(TABS_CTX, {
-		register: (v) => (firstValue ??= v)
+		register: (v) => {
+			if (!values.includes(v)) values.push(v);
+		}
 	});
+	const firstValue = $derived<string | undefined>(values[0]);
+
+	// Restore a persisted selection after mount (client-only), so it does not
+	// diverge from the server's default render until hydration is done. `ready`
+	// gates persistence until then, so any value event the tab primitive fires
+	// while mounting can't overwrite the reader's stored choice before we read it.
+	let ready = $state(false);
+	$effect(() => {
+		if (syncKey) hydrateSyncedValue(syncKey);
+		ready = true;
+	});
+
+	// A restored sync choice (valid for this block) wins, then the explicit
+	// `value`, then the first tab. Reactive, so a sibling group's change or a
+	// storage restore switches this instance too.
+	const selected = $derived.by(() => {
+		const fallback = value ?? firstValue ?? '';
+		if (!syncKey) return fallback;
+		const stored = syncedValue(syncKey);
+		return stored && values.includes(stored) ? stored : fallback;
+	});
+
+	function handleValueChange(next: string) {
+		if (ready && syncKey && next) setSyncedValue(syncKey, next);
+	}
 </script>
 
 <!-- collect: registers each TabItem's value; renders nothing. -->
 <TabsPhaseScope phase="collect">{@render children()}</TabsPhaseScope>
 
-<TabsPrimitive.Root value={value ?? firstValue ?? ''} class="my-6">
+<TabsPrimitive.Root value={selected} onValueChange={handleValueChange} class="my-6">
 	<TabsPrimitive.List class="not-prose mb-3">
 		<TabsPhaseScope phase="list">{@render children()}</TabsPhaseScope>
 	</TabsPrimitive.List>

package/dist/components/docs/tabs.svelte.d.ts

@@ -11,6 +11,12 @@ import { type Snippet } from 'svelte';
 type $$ComponentProps = {
     /** Value/label of the tab selected by default. Defaults to the first tab. */
     value?: string;
+    /**
+     * Sync group. Every `<Tabs>` with the same `syncKey` shares its selection
+     * (e.g. `"pkg"` for npm/pnpm/yarn blocks), and the choice is remembered
+     * across reloads and navigation.
+     */
+    syncKey?: string;
     children: Snippet;
 };
 declare const Tabs: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/layouts/docs-shell.svelte

@@ -3,6 +3,8 @@
 	import { afterNavigate } from '$app/navigation';
 	import {
 		navFromContent,
+		flattenNav,
+		navTrail,
 		type DocsContentItem,
 		type DocsmithConfig,
 		type SearchDoc
@@ -13,6 +15,7 @@
 	import Search from '../chrome/search.svelte';
 	import BackgroundPattern from '../chrome/background-pattern.svelte';
 	import ThemeProvider from '../chrome/theme-provider.svelte';
+	import AnnouncementBar from '../chrome/announcement-bar.svelte';
 	import DocsHeader from './docs-header.svelte';
 	import DocsFooter from './docs-footer.svelte';
 	import DocsMobileHeader from './docs-mobile-header.svelte';
@@ -128,8 +131,8 @@
 		readingTime && currentEntry?.readingTime ? `${currentEntry.readingTime} min read` : undefined
 	);
 
-	// Ordered flat page list drives the prev/next links.
-	const flatNav = $derived(nav.flatMap((group) => group.items));
+	// Ordered flat page list (leaves in sidebar reading order) drives prev/next.
+	const flatNav = $derived(flattenNav(nav));
 	const pageIndex = $derived(flatNav.findIndex((item) => item.url === pathname));
 	const prev = $derived(pageIndex > 0 ? flatNav[pageIndex - 1] : undefined);
 	const next = $derived(
@@ -137,13 +140,10 @@
 	);
 	const currentTitle = $derived(pageIndex >= 0 ? flatNav[pageIndex].title : config.title);
 
-	// Breadcrumb trail: the current page's sidebar group, then the page itself.
-	const currentGroup = $derived(
-		nav.find((group) => group.items.some((item) => item.url === pathname))
-	);
+	// Breadcrumb trail: the current page's sidebar group path, then the page
+	// itself (so a nested page reads e.g. Guides > Advanced > Middleware).
 	const breadcrumbs = $derived.by(() => {
-		const crumbs: Crumb[] = [];
-		if (currentGroup) crumbs.push({ title: currentGroup.title });
+		const crumbs: Crumb[] = (navTrail(nav, pathname) ?? []).map((title) => ({ title }));
 		if (pageIndex >= 0) crumbs.push({ title: currentTitle });
 		return crumbs;
 	});
@@ -189,6 +189,12 @@
 		<BackgroundPattern />
 	{/if}
 
+	<!-- Announcement bar (if configured) sits above the sticky header, so it
+	     scrolls away while the header stays pinned. -->
+	{#if config.announcement}
+		<AnnouncementBar announcement={config.announcement} />
+	{/if}
+
 	<!-- One header system everywhere: DocsHeader on desktop, DocsMobileHeader
 	     below lg. The `page` layout just omits the sidebar nav and in-page TOC. -->
 	<DocsHeader {config} {logo} {actions} />

package/dist/components/layouts/docs-sidebar.svelte

@@ -1,35 +1,69 @@
 <script lang="ts">
 	import { page } from '$app/state';
+	import ChevronRight from '@lucide/svelte/icons/chevron-right';
 	import { cn } from '../../utils/cn.js';
 	import { normalizePath } from '../../utils/normalize-path.js';
-	import type { NavGroup } from '../../core/index.js';
+	import { isNavGroup, type NavGroup, type NavNode } from '../../core/index.js';
 
 	const { nav, class: className = '' }: { nav: NavGroup[]; class?: string } = $props();
+
+	const current = $derived(normalizePath(page.url.pathname));
+
+	// Whether a subtree contains the current page — drives which nested groups
+	// start open. Recomputes on navigation, so navigating into a collapsed branch
+	// (e.g. via prev/next) opens it, while manual toggles on other branches stick.
+	function containsCurrent(node: NavNode): boolean {
+		return isNavGroup(node) ? node.items.some(containsCurrent) : node.url === current;
+	}
 </script>
 
+{#snippet tree(items: NavNode[])}
+	<ul class="space-y-1">
+		{#each items as node (isNavGroup(node) ? 'g:' + node.title : node.url)}
+			{#if isNavGroup(node)}
+				<li>
+					<details class="group/nav" open={containsCurrent(node)}>
+						<summary
+							class="text-muted-foreground hover:text-foreground flex cursor-pointer list-none items-center gap-2 rounded-md px-2 py-1.5 text-sm font-medium transition-colors select-none [&::-webkit-details-marker]:hidden"
+						>
+							<span class="truncate">{node.title}</span>
+							<ChevronRight
+								class="ml-auto size-3.5 shrink-0 opacity-70 transition-transform duration-200 ease-out group-open/nav:rotate-90 motion-reduce:transition-none"
+								aria-hidden="true"
+							/>
+						</summary>
+						<div class="border-border/60 mt-1 ml-2 border-l pl-3">
+							{@render tree(node.items)}
+						</div>
+					</details>
+				</li>
+			{:else}
+				<li>
+					<a
+						href={node.url}
+						aria-current={current === node.url ? 'page' : undefined}
+						class={cn(
+							'hover:text-primary hover:bg-primary/20 block rounded-md px-2 py-1.5 text-sm transition-colors',
+							current === node.url
+								? 'text-primary bg-primary/20 font-medium'
+								: 'text-muted-foreground'
+						)}
+					>
+						{node.title}
+					</a>
+				</li>
+			{/if}
+		{/each}
+	</ul>
+{/snippet}
+
 <aside class={cn('sticky top-24 hidden h-screen w-56 shrink-0 bg-transparent lg:block', className)}>
 	<div class="max-h-[calc(100vh-10rem)] overflow-y-auto px-4">
 		<nav aria-label="Documentation" class="space-y-6">
 			{#each nav as group (group.title)}
 				<div class="space-y-3">
 					<h4 class="text-foreground px-2 text-sm font-semibold">{group.title}</h4>
-					<ul class="space-y-1">
-						{#each group.items as item (item.url)}
-							<li>
-								<a
-									href={item.url}
-									class={cn(
-										'hover:text-primary hover:bg-primary/20 block rounded-md px-2 py-1.5 text-sm transition-colors',
-										normalizePath(page.url.pathname) === item.url
-											? 'text-primary bg-primary/20 font-medium'
-											: 'text-muted-foreground'
-									)}
-								>
-									{item.title}
-								</a>
-							</li>
-						{/each}
-					</ul>
+					{@render tree(group.items)}
 				</div>
 			{/each}
 		</nav>

package/dist/components/layouts/docs-sidebar.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { NavGroup } from '../../core/index.js';
+import { type NavGroup } from '../../core/index.js';
 type $$ComponentProps = {
     nav: NavGroup[];
     class?: string;

package/dist/core/config.d.ts

@@ -14,6 +14,25 @@ export type DocsmithFooterColumn = {
     title: string;
     links: DocsmithLink[];
 };
+/** A thin announcement bar shown at the top of every page. */
+export type DocsmithAnnouncement = {
+    /** The message text. */
+    text: string;
+    /** Optional leading pill label, e.g. `'New'`, `'Beta'`, or a version. */
+    tag?: string;
+    /** Optional link the bar points to. */
+    href?: string;
+    /** Open the link in a new tab with `rel="noopener"`. */
+    external?: boolean;
+    /**
+     * Dismissal key. A dismissed bar stays dismissed until this value changes, so
+     * bump it (or edit `text`) when you post a new announcement. Defaults to the
+     * text itself.
+     */
+    id?: string;
+    /** Let readers dismiss the bar. Defaults to `true`. */
+    dismissible?: boolean;
+};
 export type DocsmithConfig = {
     /** Site title, shown in the header/sidebar and in the `<title>` suffix. */
     title: string;
@@ -42,6 +61,8 @@ export type DocsmithConfig = {
     version?: string;
     /** Optional logo image src; falls back to the built-in book mark. */
     logo?: string;
+    /** Optional announcement bar shown at the top of every page. */
+    announcement?: DocsmithAnnouncement;
     /** Top-level header navigation links. */
     nav?: DocsmithLink[];
     /** Footer content, driven by data. */

package/dist/core/config.js

@@ -23,6 +23,25 @@ export function defineConfig(config) {
             throw new Error(`[svelte-docsmith] config.${key} must be a string when set.`);
         }
     }
+    if (config.announcement !== undefined) {
+        const a = config.announcement;
+        if (typeof a !== 'object' || a === null) {
+            throw new Error('[svelte-docsmith] config.announcement must be an object ({ text, href?, id?, external?, dismissible? }).');
+        }
+        if (typeof a.text !== 'string' || a.text.trim() === '') {
+            throw new Error('[svelte-docsmith] config.announcement.text is required and must be a string.');
+        }
+        for (const key of ['tag', 'href', 'id']) {
+            if (a[key] !== undefined && typeof a[key] !== 'string') {
+                throw new Error(`[svelte-docsmith] config.announcement.${key} must be a string when set.`);
+            }
+        }
+        for (const key of ['external', 'dismissible']) {
+            if (a[key] !== undefined && typeof a[key] !== 'boolean') {
+                throw new Error(`[svelte-docsmith] config.announcement.${key} must be a boolean when set.`);
+            }
+        }
+    }
     if (config.nav !== undefined) {
         if (!Array.isArray(config.nav)) {
             throw new Error('[svelte-docsmith] config.nav must be an array of { label, href } links.');

package/dist/core/content.d.ts

@@ -13,7 +13,12 @@
 export type DocsContentItem = {
     title: string;
     path: string;
-    section?: string;
+    /**
+     * Sidebar group. A string places the page in a single top-level group; an
+     * array names a nested group path (e.g. `['Guides', 'Advanced']`), building
+     * collapsible subsections. Omitted pages fall under "Docs".
+     */
+    section?: string | string[];
     order?: number;
     description?: string;
     /** Source file path relative to the app cwd, for the "Edit this page" link. */

package/dist/core/index.d.ts

@@ -1,3 +1,3 @@
-export { defineConfig, type DocsmithConfig, type DocsmithLink, type DocsmithFooterColumn } from './config.js';
+export { defineConfig, type DocsmithConfig, type DocsmithLink, type DocsmithFooterColumn, type DocsmithAnnouncement } from './config.js';
 export type { DocsContentItem, SearchDoc, LlmsDoc } from './content.js';
-export { navFromContent, type NavItem, type NavGroup } from './nav.js';
+export { navFromContent, flattenNav, navTrail, isNavGroup, type NavItem, type NavGroup, type NavNode } from './nav.js';

package/dist/core/index.js

@@ -3,4 +3,4 @@
 // several of these (e.g. the shell) import from here; the public surface is
 // re-exported through `src/lib/index.ts`.
 export { defineConfig } from './config.js';
-export { navFromContent } from './nav.js';
+export { navFromContent, flattenNav, navTrail, isNavGroup } from './nav.js';

package/dist/core/nav.d.ts

@@ -1,17 +1,34 @@
 import type { DocsContentItem } from './content.js';
-/** A single sidebar link. */
+/** A single sidebar link (a leaf). */
 export type NavItem = {
     title: string;
     url: string;
 };
-/** A titled group of sidebar links. */
+/** A titled group of sidebar entries, which may themselves be nested groups. */
 export type NavGroup = {
     title: string;
-    items: NavItem[];
+    items: NavNode[];
 };
+/** A sidebar entry: either a link or a nested group. */
+export type NavNode = NavItem | NavGroup;
+/** Narrow a {@link NavNode} to a {@link NavGroup} (an entry with children). */
+export declare function isNavGroup(node: NavNode): node is NavGroup;
 /**
- * Derive sidebar nav from a content collection: group by `section`, order by
- * `order` within a group, and order groups by the smallest `order` they
- * contain. Entries without a `section` fall under "Docs".
+ * Derive sidebar nav from a content collection. Each page's `section` (a string
+ * or a nested path) places it in the tree; within every level, entries order by
+ * `order` (then title), and a group inherits the smallest `order` of its
+ * descendants so groups sort by their earliest child. Top-level entries are
+ * always groups; pages without a section fall under "Docs".
  */
 export declare function navFromContent(content: DocsContentItem[]): NavGroup[];
+/**
+ * Flatten the nav tree to its leaf links in sidebar reading order (depth-first),
+ * for the prev/next pager.
+ */
+export declare function flattenNav(nodes: NavNode[]): NavItem[];
+/**
+ * The trail of group titles leading to the page at `url` (top group first,
+ * excluding the page itself), or `undefined` if the page is not in the tree.
+ * Drives the breadcrumb trail.
+ */
+export declare function navTrail(nodes: NavNode[], url: string): string[] | undefined;

package/dist/core/nav.js

@@ -1,22 +1,101 @@
+/** Narrow a {@link NavNode} to a {@link NavGroup} (an entry with children). */
+export function isNavGroup(node) {
+    return 'items' in node;
+}
+/**
+ * Normalize a page's `section` to a group path. A string is a single level; an
+ * array is a nested path; blank or missing sections fall under "Docs". Empty
+ * strings inside an array are dropped so a stray `['Guides', '']` stays sane.
+ */
+function sectionPath(section) {
+    const segs = Array.isArray(section) ? section : section ? [section] : [];
+    const clean = segs.filter((s) => typeof s === 'string' && s.trim() !== '');
+    return clean.length ? clean : ['Docs'];
+}
+function makeBuilder(title) {
+    return { title, order: Infinity, groups: new Map(), leaves: [] };
+}
+/**
+ * Emit a group's children (nested groups and leaf links) as one list, sorted by
+ * `order` and then title. The title tiebreak keeps the output deterministic when
+ * pages share an order (e.g. all default to 0), instead of depending on the
+ * filesystem scan order.
+ */
+function emitItems(node) {
+    const entries = [];
+    for (const leaf of node.leaves) {
+        entries.push({
+            order: leaf.order,
+            title: leaf.title,
+            node: { title: leaf.title, url: leaf.url }
+        });
+    }
+    for (const group of node.groups.values()) {
+        entries.push({
+            order: group.order,
+            title: group.title,
+            node: { title: group.title, items: emitItems(group) }
+        });
+    }
+    entries.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+    return entries.map((e) => e.node);
+}
 /**
- * Derive sidebar nav from a content collection: group by `section`, order by
- * `order` within a group, and order groups by the smallest `order` they
- * contain. Entries without a `section` fall under "Docs".
+ * Derive sidebar nav from a content collection. Each page's `section` (a string
+ * or a nested path) places it in the tree; within every level, entries order by
+ * `order` (then title), and a group inherits the smallest `order` of its
+ * descendants so groups sort by their earliest child. Top-level entries are
+ * always groups; pages without a section fall under "Docs".
  */
 export function navFromContent(content) {
-    const groups = new Map();
+    const root = makeBuilder('');
     for (const item of content) {
-        const section = item.section ?? 'Docs';
         const order = item.order ?? 0;
-        const group = groups.get(section) ?? { minOrder: Infinity, items: [] };
-        group.items.push({ title: item.title, url: item.path, order });
-        group.minOrder = Math.min(group.minOrder, order);
-        groups.set(section, group);
+        let node = root;
+        for (const seg of sectionPath(item.section)) {
+            let child = node.groups.get(seg);
+            if (!child) {
+                child = makeBuilder(seg);
+                node.groups.set(seg, child);
+            }
+            child.order = Math.min(child.order, order);
+            node = child;
+        }
+        node.leaves.push({ title: item.title, url: item.path, order });
+    }
+    // The root only ever holds groups (every page has at least one path segment),
+    // so its emitted items are all NavGroups.
+    return emitItems(root);
+}
+/**
+ * Flatten the nav tree to its leaf links in sidebar reading order (depth-first),
+ * for the prev/next pager.
+ */
+export function flattenNav(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        if (isNavGroup(node))
+            out.push(...flattenNav(node.items));
+        else
+            out.push(node);
+    }
+    return out;
+}
+/**
+ * The trail of group titles leading to the page at `url` (top group first,
+ * excluding the page itself), or `undefined` if the page is not in the tree.
+ * Drives the breadcrumb trail.
+ */
+export function navTrail(nodes, url) {
+    for (const node of nodes) {
+        if (isNavGroup(node)) {
+            const inner = navTrail(node.items, url);
+            if (inner)
+                return [node.title, ...inner];
+        }
+        else if (node.url === url) {
+            return [];
+        }
     }
-    return [...groups.entries()]
-        .sort((a, b) => a[1].minOrder - b[1].minOrder)
-        .map(([title, group]) => ({
-        title,
-        items: group.items.sort((a, b) => a.order - b.order).map(({ title, url }) => ({ title, url }))
-    }));
+    return undefined;
 }

package/dist/theme.css

@@ -107,38 +107,38 @@
 
 @layer base {
 	:root {
-		--background: oklch(0.9383 0.0042 236.4993);
-		--foreground: oklch(0.3211 0 0);
+		--background: oklch(1 0 0);
+		--foreground: oklch(0.2101 0.0318 264.6645);
 		--card: oklch(1 0 0);
-		--card-foreground: oklch(0.3211 0 0);
+		--card-foreground: oklch(0.2101 0.0318 264.6645);
 		--popover: oklch(1 0 0);
-		--popover-foreground: oklch(0.3211 0 0);
-		--primary: oklch(0.6397 0.172 36.4421);
+		--popover-foreground: oklch(0.2101 0.0318 264.6645);
+		--primary: oklch(0.6716 0.1368 48.513);
 		--primary-foreground: oklch(1 0 0);
-		--secondary: oklch(0.967 0.0029 264.5419);
-		--secondary-foreground: oklch(0.4461 0.0263 256.8018);
-		--muted: oklch(0.9846 0.0017 247.8389);
+		--secondary: oklch(0.536 0.0398 196.028);
+		--secondary-foreground: oklch(1 0 0);
+		--muted: oklch(0.967 0.0029 264.5419);
 		--muted-foreground: oklch(0.551 0.0234 264.3637);
-		--accent: oklch(0.9119 0.0222 243.8174);
-		--accent-foreground: oklch(0.3791 0.1378 265.5222);
+		--accent: oklch(0.9491 0 0);
+		--accent-foreground: oklch(0.2101 0.0318 264.6645);
 		--destructive: oklch(0.6368 0.2078 25.3313);
-		--destructive-foreground: oklch(1 0 0);
-		--border: oklch(0.9022 0.0052 247.8822);
-		--input: oklch(0.97 0.0029 264.542);
-		--ring: oklch(0.6397 0.172 36.4421);
-		--chart-1: oklch(0.7156 0.0605 248.6845);
-		--chart-2: oklch(0.7875 0.0917 35.9616);
-		--chart-3: oklch(0.5778 0.0759 254.1573);
-		--chart-4: oklch(0.5016 0.0849 259.4902);
-		--chart-5: oklch(0.4241 0.0952 264.0306);
-		--sidebar: oklch(0.903 0.0046 258.3257);
-		--sidebar-foreground: oklch(0.3211 0 0);
-		--sidebar-primary: oklch(0.6397 0.172 36.4421);
+		--destructive-foreground: oklch(0.9851 0 0);
+		--border: oklch(0.9276 0.0058 264.5313);
+		--input: oklch(0.9276 0.0058 264.5313);
+		--ring: oklch(0.6716 0.1368 48.513);
+		--chart-1: oklch(0.594 0.0443 196.0233);
+		--chart-2: oklch(0.7214 0.1337 49.9802);
+		--chart-3: oklch(0.8721 0.0864 68.5474);
+		--chart-4: oklch(0.6268 0 0);
+		--chart-5: oklch(0.683 0 0);
+		--sidebar: oklch(0.967 0.0029 264.5419);
+		--sidebar-foreground: oklch(0.2101 0.0318 264.6645);
+		--sidebar-primary: oklch(0.6716 0.1368 48.513);
 		--sidebar-primary-foreground: oklch(1 0 0);
-		--sidebar-accent: oklch(0.9119 0.0222 243.8174);
-		--sidebar-accent-foreground: oklch(0.3791 0.1378 265.5222);
+		--sidebar-accent: oklch(1 0 0);
+		--sidebar-accent-foreground: oklch(0.2101 0.0318 264.6645);
 		--sidebar-border: oklch(0.9276 0.0058 264.5313);
-		--sidebar-ring: oklch(0.6397 0.172 36.4421);
+		--sidebar-ring: oklch(0.6716 0.1368 48.513);
 		--font-sans: Inter, sans-serif;
 		--font-serif: Source Serif 4, serif;
 		--font-mono: JetBrains Mono, monospace;
@@ -165,38 +165,38 @@
 	}
 
 	.dark {
-		--background: oklch(0.2598 0.0306 262.6666);
-		--foreground: oklch(0.9219 0 0);
-		--card: oklch(0.3106 0.0301 268.6365);
-		--card-foreground: oklch(0.9219 0 0);
-		--popover: oklch(0.29 0.0249 268.3986);
-		--popover-foreground: oklch(0.9219 0 0);
-		--primary: oklch(0.6397 0.172 36.4421);
-		--primary-foreground: oklch(1 0 0);
-		--secondary: oklch(0.3095 0.0266 266.7132);
-		--secondary-foreground: oklch(0.9219 0 0);
-		--muted: oklch(0.3095 0.0266 266.7132);
-		--muted-foreground: oklch(0.7155 0 0);
-		--accent: oklch(0.338 0.0589 267.5867);
-		--accent-foreground: oklch(0.8823 0.0571 254.1284);
-		--destructive: oklch(0.6368 0.2078 25.3313);
-		--destructive-foreground: oklch(1 0 0);
-		--border: oklch(0.3843 0.0301 269.7337);
-		--input: oklch(0.3843 0.0301 269.7337);
-		--ring: oklch(0.6397 0.172 36.4421);
-		--chart-1: oklch(0.7156 0.0605 248.6845);
-		--chart-2: oklch(0.7693 0.0876 34.1875);
-		--chart-3: oklch(0.5778 0.0759 254.1573);
-		--chart-4: oklch(0.5016 0.0849 259.4902);
-		--chart-5: oklch(0.4241 0.0952 264.0306);
-		--sidebar: oklch(0.31 0.0283 267.7408);
-		--sidebar-foreground: oklch(0.9219 0 0);
-		--sidebar-primary: oklch(0.6397 0.172 36.4421);
-		--sidebar-primary-foreground: oklch(1 0 0);
-		--sidebar-accent: oklch(0.338 0.0589 267.5867);
-		--sidebar-accent-foreground: oklch(0.8823 0.0571 254.1284);
-		--sidebar-border: oklch(0.3843 0.0301 269.7337);
-		--sidebar-ring: oklch(0.6397 0.172 36.4421);
+		--background: oklch(0.1797 0.0043 308.1928);
+		--foreground: oklch(0.8109 0 0);
+		--card: oklch(0.1822 0 0);
+		--card-foreground: oklch(0.8109 0 0);
+		--popover: oklch(0.1797 0.0043 308.1928);
+		--popover-foreground: oklch(0.8109 0 0);
+		--primary: oklch(0.7214 0.1337 49.9802);
+		--primary-foreground: oklch(0.1797 0.0043 308.1928);
+		--secondary: oklch(0.594 0.0443 196.0233);
+		--secondary-foreground: oklch(0.1797 0.0043 308.1928);
+		--muted: oklch(0.252 0 0);
+		--muted-foreground: oklch(0.6268 0 0);
+		--accent: oklch(0.3211 0 0);
+		--accent-foreground: oklch(0.8109 0 0);
+		--destructive: oklch(0.7106 0.1661 22.2162);
+		--destructive-foreground: oklch(0.1797 0.0043 308.1928);
+		--border: oklch(0.252 0 0);
+		--input: oklch(0.252 0 0);
+		--ring: oklch(0.7214 0.1337 49.9802);
+		--chart-1: oklch(0.594 0.0443 196.0233);
+		--chart-2: oklch(0.7214 0.1337 49.9802);
+		--chart-3: oklch(0.8721 0.0864 68.5474);
+		--chart-4: oklch(0.6268 0 0);
+		--chart-5: oklch(0.683 0 0);
+		--sidebar: oklch(0.1822 0 0);
+		--sidebar-foreground: oklch(0.8109 0 0);
+		--sidebar-primary: oklch(0.7214 0.1337 49.9802);
+		--sidebar-primary-foreground: oklch(0.1797 0.0043 308.1928);
+		--sidebar-accent: oklch(0.3211 0 0);
+		--sidebar-accent-foreground: oklch(0.8109 0 0);
+		--sidebar-border: oklch(0.252 0 0);
+		--sidebar-ring: oklch(0.7214 0.1337 49.9802);
 	}
 
 	* {

package/dist/themes/darkmatter.css

@@ -1,8 +1,10 @@
 /*
- * svelte-docsmith theme — Darkmatter (based on the tweakcn preset).
+ * svelte-docsmith theme — Darkmatter. The built-in default (based on the tweakcn
+ * preset): theme.css already ships these tokens, so you only import this file to
+ * return to Darkmatter after choosing another preset.
  *
- * A near-monochrome shell with a warm orange primary and a muted teal
- * secondary; light mode is crisp white, dark mode is deep near-black.
+ * A near-monochrome shell with a warm orange primary and a muted teal secondary;
+ * light mode is crisp white, dark mode is deep near-black.
  *
  *   @import 'svelte-docsmith/theme.css';
  *   @import 'svelte-docsmith/themes/darkmatter.css';
@@ -63,7 +65,7 @@
 	--border: oklch(0.252 0 0);
 	--input: oklch(0.252 0 0);
 	--ring: oklch(0.7214 0.1337 49.9802);
-	--destructive: oklch(0.594 0.0443 196.0233);
+	--destructive: oklch(0.7106 0.1661 22.2162);
 	--destructive-foreground: oklch(0.1797 0.0043 308.1928);
 	--chart-1: oklch(0.594 0.0443 196.0233);
 	--chart-2: oklch(0.7214 0.1337 49.9802);

package/dist/themes/tangerine.css

@@ -1,13 +1,10 @@
 /*
- * svelte-docsmith theme — Tangerine (the default).
- *
- * These are the same tokens baked into theme.css, extracted as a named preset
- * so you can re-apply the default explicitly or use it as a starting point:
+ * svelte-docsmith theme — Tangerine. A warm terracotta primary on calm,
+ * faintly-cool neutrals. Import it after theme.css to swap the default Darkmatter
+ * tokens for this palette:
  *
  *   @import 'svelte-docsmith/theme.css';
  *   @import 'svelte-docsmith/themes/tangerine.css';
- *
- * Warm terracotta primary on calm, faintly-cool neutrals.
  */
 
 :root {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-docsmith",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A framework for building beautiful documentation sites with Svelte.",
   "author": {
     "name": "George Daskalakis",
@@ -104,9 +104,17 @@
   },
   "keywords": [
     "svelte",
+    "sveltekit",
+    "svelte5",
+    "docs",
+    "documentation",
+    "documentation-generator",
+    "docs-site",
+    "markdown",
+    "mdsvex",
+    "shiki",
     "ui",
-    "component",
-    "docs"
+    "components"
   ],
   "scripts": {
     "dev": "vite dev",