svelte-docsmith 0.2.0 → 0.4.0

package/README.md

@@ -4,30 +4,39 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 The documentation framework for Svelte 5 library authors whose interactive
-examples need to live inside one real, stateful SvelteKit app — not sandboxed as
+examples need to live inside one real, stateful SvelteKit app, not sandboxed as
 isolated islands.
 
 Write a markdown file under `src/routes/docs/` and you get a styled page with
 syntax highlighting, heading anchors, a sidebar derived from your content, and a
-live table of contents — no per-page wiring, no content collection to configure.
+live table of contents. No per-page wiring, no content collection to configure.
 
 > **Status: pre-1.0.** Published to npm and usable today. The public API is still
 > stabilising, so minor releases may include breaking changes until v1.0.
 
 ## Install
 
+The fastest way to start a new docs site is the scaffolder, which wires up
+everything below for you:
+
+```bash
+npm create svelte-docsmith@latest my-docs
+```
+
+To add DocSmith to an existing SvelteKit app, install the package instead:
+
 ```bash
 npm install svelte-docsmith
 ```
 
-Peer dependencies: Svelte 5, SvelteKit 2, and Tailwind v4 — set up the standard
+Peer dependencies: Svelte 5, SvelteKit 2, and Tailwind v4, set up the standard
 way in your app.
 
 ## Setup
 
 Three small pieces, once.
 
-**1. The markdown pipeline** — in `svelte.config.js`. One call bundles mdsvex,
+**1. The markdown pipeline.** In `svelte.config.js`, one call bundles mdsvex,
 Shiki highlighting (dual light/dark themes, a generous language set, plain-text
 fallback for unknown languages), heading anchors, and the packaged page layout:
 
@@ -44,9 +53,9 @@ export default {
 };
 ```
 
-**2. The Vite plugin** — in `vite.config.ts`. It scans your doc pages'
-frontmatter into the `svelte-docsmith/content` module (so the sidebar is derived
-from content, never hand-written) and powers `LiveExample`:
+**2. The Vite plugin.** In `vite.config.ts`, it scans your doc pages' frontmatter
+into the `svelte-docsmith/content` module (so the sidebar is derived from
+content, never hand-written), builds the search index, and powers `LiveExample`:
 
 ```ts
 // vite.config.ts
@@ -63,9 +72,9 @@ export default defineConfig({
 By default it scans `src/routes/docs`; pass `docsmith({ content: 'src/routes/guide' })`
 to point elsewhere.
 
-**3. The stylesheet** — in your root `app.css`. Your app needs Tailwind v4 set up
-the standard way (`tailwindcss` + the `@tailwindcss/vite` plugin, stylesheet
-imported in the root layout). After that the whole style contract is one import:
+**3. The stylesheet.** In your root `app.css`, once Tailwind v4 is set up the
+standard way (`tailwindcss` + the `@tailwindcss/vite` plugin, stylesheet imported
+in the root layout), the whole style contract is one import:
 
 ```css
 @import 'tailwindcss';
@@ -75,13 +84,14 @@ imported in the root layout). After that the whole style contract is one import:
 `theme.css` makes Tailwind scan the package, defines the shadcn theme tokens
 (`--background`, `--primary`, `--radius`, …) for `:root` and `.dark`, and pulls
 in the typography and animation plugins. Override any token by redefining it
-after the import.
+after the import, or import a preset (see [Themes](#themes)).
 
 ## The shell
 
 Add `DocsShell` once, in `src/routes/docs/+layout.svelte`. It composes the
 header, sidebar, content area, and table of contents. `docs` is the generated
-content index — no import of a content collection, no alias to configure:
+content index, so there is no content collection to import and no alias to
+configure:
 
 ```svelte
 <script lang="ts">
@@ -103,7 +113,7 @@ content index — no import of a content collection, no alias to configure:
 ## Doc pages
 
 Each page is a `+page.md` under `src/routes/docs/`. Frontmatter drives the
-sidebar; the body is markdown:
+sidebar and the `<h1>`; the body is markdown, starting at `##`:
 
 ````md
 ---
@@ -122,12 +132,12 @@ npm install my-library
 
 `title` names the page. `section` groups pages in the sidebar; `order` sorts
 within a group (and orders the groups by their smallest `order`). Add the file
-and it appears in the sidebar — styled, highlighted, with a table of contents.
+and it appears in the sidebar, styled, highlighted, with a table of contents.
 
 ## Live examples
 
 `LiveExample` renders a real, interactive component next to its own
-syntax-highlighted source — one file, imported twice, so the demo and its code
+syntax-highlighted source: one file, imported twice, so the demo and its code
 can never drift. The `?source` import is served by the same `docsmith()` Vite
 plugin you already added:
 
@@ -143,20 +153,51 @@ plugin you already added:
 </LiveExample>
 ```
 
+## Batteries included
+
+- **Search.** A ⌘K / Ctrl-K command palette over a build-time full-text index, no
+  service to host. Pass a `search` loader to `DocsShell`:
+  `search={() => import('svelte-docsmith/search').then((m) => m.docs)}`.
+- **SEO.** `DocsShell` writes `<title>`, meta description, canonical, and Open
+  Graph / Twitter tags for every page from its frontmatter, no per-page wiring.
+- **Error pages.** `ErrorPage` gives a styled 404 that keeps the site chrome;
+  drop it into a SvelteKit `+error.svelte`.
+- **Components.** `Callout`, `Tabs`, `Steps`, `Card`, `Accordion`, `Badge`,
+  `Kbd`, `FileTree`, `PropsTable`, and more, authored right inside markdown.
+- Heading anchors, a scroll-spy table of contents, and one-click copy on every
+  code block, wired up for you.
+
+## Themes
+
+Eleven presets ship in the box. Pick one with a single import after the base
+contract:
+
+```css
+@import 'svelte-docsmith/theme.css';
+@import 'svelte-docsmith/themes/amethyst.css';
+```
+
+Available: `darkmatter`, `tangerine`, `amethyst`, `graphite`, `evergreen`,
+`rose`, `ocean`, `nord`, `claude`, `bubblegum`, `mono`. Or skip the preset and
+override the tokens yourself.
+
 ## What's exported
 
-| Entry point                  | What it is                                                                                               |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `svelte-docsmith`            | `DocsShell`, `LiveExample`, `Tabs`, `TabItem`, `defineConfig` + `DocsmithConfig`/`DocsContentItem` types |
-| `svelte-docsmith/preprocess` | `docsmith()` — the mdsvex/Shiki pipeline (Node, config time)                                             |
-| `svelte-docsmith/vite`       | `docsmith()` — content index + `?source` (Node, build time)                                              |
-| `svelte-docsmith/content`    | `docs` — the generated sidebar content index                                                             |
-| `svelte-docsmith/theme.css`  | the style contract                                                                                       |
+| Entry point                    | What it is                                                                                                                               |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `svelte-docsmith`              | All components (`DocsShell`, `ErrorPage`, `LiveExample`, `Callout`, `Tabs`, …), plus `defineConfig`, `createSearchEngine`, and the types |
+| `svelte-docsmith/preprocess`   | `docsmith()`, the mdsvex/Shiki pipeline (Node, config time)                                                                              |
+| `svelte-docsmith/vite`         | `docsmith()`, the content index, search index, and `?source` transform (Node, build)                                                     |
+| `svelte-docsmith/content`      | `docs`, the generated sidebar content index                                                                                              |
+| `svelte-docsmith/search`       | `docs`, the generated full-text search index (lazy-load it)                                                                              |
+| `svelte-docsmith/theme.css`    | the base style contract                                                                                                                  |
+| `svelte-docsmith/themes/*.css` | the eleven theme presets                                                                                                                 |
 
 The vendored shadcn primitives and internal helpers (the TOC engine, clipboard
-utility, markdown renderer map) are **not** part of the public API — they can
-change between releases. Get buttons, cards, etc. from `shadcn-svelte` directly.
+utility, markdown renderer map) are **not** part of the public API; they can
+change between releases. Get buttons, cards, and the like from `shadcn-svelte`
+directly.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/dist/clipboard.svelte.d.ts

@@ -1,6 +1,6 @@
 export declare function useClipboard(timeout?: number): {
     readText: (node: HTMLElement) => void;
-    copy: () => void;
+    copy: () => Promise<void>;
     readonly currentText: string;
     readonly copied: boolean;
 };

package/dist/clipboard.svelte.js

@@ -4,14 +4,21 @@ export function useClipboard(timeout = 1500) {
     function readText(node) {
         text = node.innerText.trim();
     }
-    function copy() {
-        if (text) {
-            navigator.clipboard.writeText(text).then(() => {
-                copied = true;
-                setTimeout(() => {
-                    copied = false;
-                }, timeout);
-            });
+    async function copy() {
+        if (!text)
+            return;
+        // `navigator.clipboard` is undefined in insecure (non-HTTPS) contexts, and
+        // writeText can reject when the page lacks clipboard permission. Fail quietly
+        // so a copy button never throws an unhandled rejection.
+        try {
+            await navigator.clipboard.writeText(text);
+            copied = true;
+            setTimeout(() => {
+                copied = false;
+            }, timeout);
+        }
+        catch (error) {
+            console.warn('[svelte-docsmith] copy to clipboard failed', error);
         }
     }
     return {

package/dist/config.d.ts

@@ -15,8 +15,20 @@ export type DocsmithFooterColumn = {
     links: DocsmithLink[];
 };
 export type DocsmithConfig = {
-    /** Site title, shown in the header/sidebar. */
+    /** Site title, shown in the header/sidebar and in the `<title>` suffix. */
     title: string;
+    /**
+     * Default meta description, used for pages whose frontmatter has none (and
+     * as the site's social-share description).
+     */
+    description?: string;
+    /**
+     * Canonical site origin, e.g. `https://docs.example.com`. When set, DocsShell
+     * emits `<link rel="canonical">` and absolute Open Graph URLs.
+     */
+    url?: string;
+    /** Default social-share image (absolute URL, or a path resolved against `url`). */
+    ogImage?: string;
     /** Optional GitHub URL; renders a link in the header when set. */
     github?: string;
     /** Optional version string, shown in the header (e.g. your library version). */
@@ -46,8 +58,9 @@ export type DocsmithConfig = {
 export declare function defineConfig(config: DocsmithConfig): DocsmithConfig;
 /**
  * The minimal shape `DocsShell` needs from each content entry to build the
- * sidebar. A velite `docs` collection with title/section/order/path frontmatter
- * satisfies this structurally.
+ * sidebar. The generated `svelte-docsmith/content` module produces these from
+ * your pages' frontmatter; any source with matching title/path/section/order
+ * fields satisfies it structurally.
  */
 export type DocsContentItem = {
     title: string;
@@ -66,6 +79,23 @@ export type DocsContentItem = {
         depth: 2 | 3;
     }[];
 };
+/**
+ * One page's searchable record, emitted at build time by the `docsmith()` vite
+ * plugin as the `svelte-docsmith/search` virtual module. `text` is the page's
+ * prose and headings reduced to plain text (frontmatter, `<script>` blocks,
+ * fenced code, tags, and markdown punctuation stripped) so a client-side search
+ * index can be built over it without shipping raw markdown.
+ */
+export type SearchDoc = {
+    path: string;
+    title: string;
+    section?: string;
+    description?: string;
+    /** The page's `h2`/`h3` heading text, for weighting title/heading matches. */
+    headings: string[];
+    /** Plain-text body: prose and headings, code and markup removed. */
+    text: string;
+};
 /** A single sidebar link. */
 export type NavItem = {
     title: string;
@@ -77,8 +107,8 @@ export type NavGroup = {
     items: NavItem[];
 };
 /**
- * Derive sidebar nav from a content collection (PLAN.md §2.6): 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: 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".
  */
 export declare function navFromContent(content: DocsContentItem[]): NavGroup[];

package/dist/config.js

@@ -10,7 +10,7 @@ export function defineConfig(config) {
     if (typeof config.title !== 'string' || config.title.trim() === '') {
         throw new Error('[svelte-docsmith] config.title is required — the site title shown in the sidebar header.');
     }
-    for (const key of ['github', 'version', 'logo']) {
+    for (const key of ['github', 'version', 'logo', 'description', 'url', 'ogImage']) {
         if (config[key] !== undefined && typeof config[key] !== 'string') {
             throw new Error(`[svelte-docsmith] config.${key} must be a string when set.`);
         }
@@ -25,16 +25,42 @@ export function defineConfig(config) {
             }
         }
     }
-    if (config.footer !== undefined &&
-        (typeof config.footer !== 'object' || config.footer === null)) {
-        throw new Error('[svelte-docsmith] config.footer must be an object ({ copyright?, columns? }).');
+    if (config.footer !== undefined) {
+        if (typeof config.footer !== 'object' || config.footer === null) {
+            throw new Error('[svelte-docsmith] config.footer must be an object ({ copyright?, columns?, poweredBy? }).');
+        }
+        const { copyright, columns, poweredBy } = config.footer;
+        if (copyright !== undefined && typeof copyright !== 'string') {
+            throw new Error('[svelte-docsmith] config.footer.copyright must be a string when set.');
+        }
+        if (poweredBy !== undefined && typeof poweredBy !== 'boolean') {
+            throw new Error('[svelte-docsmith] config.footer.poweredBy must be a boolean when set.');
+        }
+        if (columns !== undefined) {
+            if (!Array.isArray(columns)) {
+                throw new Error('[svelte-docsmith] config.footer.columns must be an array of { title, links } columns.');
+            }
+            for (const column of columns) {
+                if (typeof column?.title !== 'string') {
+                    throw new Error('[svelte-docsmith] each config.footer.columns entry needs a string `title`.');
+                }
+                if (!Array.isArray(column.links)) {
+                    throw new Error(`[svelte-docsmith] config.footer column "${column.title}" needs a \`links\` array.`);
+                }
+                for (const link of column.links) {
+                    if (typeof link?.label !== 'string' || typeof link?.href !== 'string') {
+                        throw new Error(`[svelte-docsmith] each link in config.footer column "${column.title}" needs a string \`label\` and \`href\`.`);
+                    }
+                }
+            }
+        }
     }
     return config;
 }
 /**
- * Derive sidebar nav from a content collection (PLAN.md §2.6): 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: 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".
  */
 export function navFromContent(content) {
     const groups = new Map();

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { default as DocsShell } from './ui/layouts/docs-shell.svelte';
+export { default as ErrorPage } from './ui/layouts/error-page.svelte';
 export { default as ThemeProvider } from './ui/theme-provider.svelte';
 export { default as ThemeToggle } from './ui/theme-toggle.svelte';
 export { default as LiveExample } from './ui/live-example.svelte';
 export { default as Tabs } from './ui/tabs.svelte';
 export { default as TabItem } from './ui/tab-item.svelte';
-export { default as Callout } from './ui/callout.svelte';
+export { default as Callout, type CalloutVariant } from './ui/callout.svelte';
 export { default as Steps } from './ui/steps.svelte';
 export { default as Step } from './ui/step.svelte';
 export { default as Card } from './ui/card.svelte';
@@ -17,4 +18,5 @@ export { default as FileTree } from './ui/file-tree.svelte';
 export { default as FileTreeItem } from './ui/file-tree-item.svelte';
 export { default as PropsTable } from './ui/props-table.svelte';
 export { default as Prop } from './ui/prop.svelte';
-export { defineConfig, type DocsmithConfig, type DocsContentItem } from './config.js';
+export { defineConfig, type DocsmithConfig, type DocsContentItem, type SearchDoc } from './config.js';
+export { createSearchEngine, type SearchEngine, type SearchResult } from './search/create-search.js';

package/dist/index.js

@@ -3,6 +3,7 @@
 // renderer map — is internal and may change between releases.
 // Chrome
 export { default as DocsShell } from './ui/layouts/docs-shell.svelte';
+export { default as ErrorPage } from './ui/layouts/error-page.svelte';
 export { default as ThemeProvider } from './ui/theme-provider.svelte';
 export { default as ThemeToggle } from './ui/theme-toggle.svelte';
 // Docs components (authored inside markdown or composed in pages)
@@ -24,3 +25,6 @@ export { default as PropsTable } from './ui/props-table.svelte';
 export { default as Prop } from './ui/prop.svelte';
 // Config
 export { defineConfig } from './config.js';
+// Search engine (framework-agnostic; for building a custom search UI over the
+// generated `svelte-docsmith/search` index)
+export { createSearchEngine } from './search/create-search.js';

package/dist/markdown-layout.svelte

@@ -13,9 +13,22 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 
-	const { children }: { children: Snippet } = $props();
+	// mdsvex passes each frontmatter field to the layout as a prop, so the page's
+	// `<h1>` (and lead subtitle) come from `title`/`description` — authored once in
+	// frontmatter, never repeated in the body. Pages start their content at `##`.
+	const {
+		title,
+		description,
+		children
+	}: { title?: string; description?: string; children: Snippet } = $props();
 </script>
 
 <article class="prose prose-base dark:prose-invert max-w-none pb-16">
+	{#if title}
+		<h1>{title}</h1>
+	{/if}
+	{#if description}
+		<p class="lead">{description}</p>
+	{/if}
 	{@render children()}
 </article>

package/dist/markdown-layout.svelte.d.ts

@@ -11,6 +11,8 @@ export declare const table: import("svelte").Component<{
 }, {}, "">;
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
+    title?: string;
+    description?: string;
     children: Snippet;
 };
 declare const MarkdownLayout: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/preprocess.d.ts

@@ -24,10 +24,9 @@ export interface DocsmithPreprocessOptions {
     rehypePlugins?: MdsvexOptions['rehypePlugins'];
 }
 /**
- * Build the svelte-docsmith preprocessor: mdsvex with Shiki highlighting
- * (raw-code `highlight` hook — the correct mdsvex integration point, see the
- * repo's PLAN.md §4.5), heading slugs/anchor sections, and the packaged doc
- * layout. Unknown code-fence languages fall back to plain text instead of
- * failing the build.
+ * Build the svelte-docsmith preprocessor: mdsvex with Shiki highlighting (via
+ * the raw-code `highlight` hook, the correct mdsvex integration point), heading
+ * slugs/anchor sections, and the packaged doc layout. Unknown code-fence
+ * languages fall back to plain text instead of failing the build.
  */
 export declare function docsmith(options?: DocsmithPreprocessOptions): PreprocessorGroup;

package/dist/preprocess.js

@@ -6,17 +6,16 @@
  * doesn't care where it's registered). It must never import component code.
  */
 import rehypeSectionize from '@hbsnow/rehype-sectionize';
-import { transformerNotationHighlight } from '@shikijs/transformers';
+import { transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight, transformerNotationWordHighlight } from '@shikijs/transformers';
 import { escapeSvelte, mdsvex } from 'mdsvex';
 import { fileURLToPath } from 'node:url';
 import rehypeSlug from 'rehype-slug';
 import { DEFAULT_LANGS, DEFAULT_THEMES, lazyHighlighter } from './highlight.js';
 /**
- * Build the svelte-docsmith preprocessor: mdsvex with Shiki highlighting
- * (raw-code `highlight` hook — the correct mdsvex integration point, see the
- * repo's PLAN.md §4.5), heading slugs/anchor sections, and the packaged doc
- * layout. Unknown code-fence languages fall back to plain text instead of
- * failing the build.
+ * Build the svelte-docsmith preprocessor: mdsvex with Shiki highlighting (via
+ * the raw-code `highlight` hook, the correct mdsvex integration point), heading
+ * slugs/anchor sections, and the packaged doc layout. Unknown code-fence
+ * languages fall back to plain text instead of failing the build.
  */
 export function docsmith(options = {}) {
     const themes = options.themes ?? DEFAULT_THEMES;
@@ -40,7 +39,16 @@ export function docsmith(options = {}) {
                 const html = escapeSvelte(highlighter.codeToHtml(code, {
                     lang: language,
                     themes,
-                    transformers: [transformerNotationHighlight()]
+                    // Comment-driven annotations authors write inside the fence:
+                    // line highlight, diff (++/--), focus, error/warning, and
+                    // word highlight. Each strips its own marker comment.
+                    transformers: [
+                        transformerNotationHighlight(),
+                        transformerNotationDiff(),
+                        transformerNotationFocus(),
+                        transformerNotationErrorLevel(),
+                        transformerNotationWordHighlight()
+                    ]
                 }));
                 // Without a layout there is no `Components.pre` to render through —
                 // keep Shiki's own <pre> as-is.

package/dist/search/context.svelte.d.ts

@@ -0,0 +1,7 @@
+export declare class SearchState {
+    open: boolean;
+}
+/** Create the search state and publish it on context. Call in `DocsShell`. */
+export declare function createSearchState(): SearchState;
+/** Read the search state, or `undefined` when search is not enabled. */
+export declare function useSearch(): SearchState | undefined;

package/dist/search/context.svelte.js

@@ -0,0 +1,20 @@
+/**
+ * Shared open-state for the search palette. `DocsShell` creates it once; the
+ * header/mobile-header triggers and the single `<Search>` dialog read it through
+ * context, so one keyboard shortcut and one dialog serve every trigger.
+ */
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('docsmith-search');
+export class SearchState {
+    open = $state(false);
+}
+/** Create the search state and publish it on context. Call in `DocsShell`. */
+export function createSearchState() {
+    const state = new SearchState();
+    setContext(KEY, state);
+    return state;
+}
+/** Read the search state, or `undefined` when search is not enabled. */
+export function useSearch() {
+    return getContext(KEY);
+}

package/dist/search/create-search.d.ts

@@ -0,0 +1,14 @@
+import type { SearchDoc } from '../config.js';
+/** One result row: enough to render a link and a preview. */
+export type SearchResult = {
+    path: string;
+    title: string;
+    section?: string;
+    snippet: string;
+};
+export type SearchEngine = {
+    /** Ranked results for `query`, at most `limit` (default 8). */
+    search(query: string, limit?: number): SearchResult[];
+};
+/** Build a search engine over `docs`. Indexing is synchronous and one-time. */
+export declare function createSearchEngine(docs: SearchDoc[]): SearchEngine;

package/dist/search/create-search.js

@@ -0,0 +1,56 @@
+/**
+ * The client-side search engine. Builds a FlexSearch document index over the
+ * generated `svelte-docsmith/search` records (title, headings, description, and
+ * plain-text body) and returns a `search()` that maps hits back to page links
+ * with a context snippet. Framework-agnostic on purpose so it can be unit-tested
+ * without a DOM; the `<Search>` component lazy-loads both this and the index.
+ */
+import { Document } from 'flexsearch';
+import { buildSnippet } from './snippet.js';
+/** Build a search engine over `docs`. Indexing is synchronous and one-time. */
+export function createSearchEngine(docs) {
+    const index = new Document({
+        tokenize: 'forward',
+        document: {
+            id: 'id',
+            // Title and headings first so their matches outrank body matches.
+            index: [
+                { field: 'title' },
+                { field: 'headings' },
+                { field: 'description' },
+                { field: 'text' }
+            ]
+        }
+    });
+    docs.forEach((doc, id) => {
+        index.add({
+            id,
+            title: doc.title,
+            headings: doc.headings.join(' '),
+            description: doc.description ?? '',
+            text: doc.text
+        });
+    });
+    return {
+        search(query, limit = 8) {
+            const trimmed = query.trim();
+            if (!trimmed)
+                return [];
+            // `merge: true` returns unified, unique ids ranked across fields.
+            const hits = index.search(trimmed, { limit, merge: true });
+            const results = [];
+            for (const { id } of hits) {
+                const doc = docs[id];
+                if (!doc)
+                    continue;
+                results.push({
+                    path: doc.path,
+                    title: doc.title,
+                    section: doc.section,
+                    snippet: buildSnippet(doc.text || doc.description || '', trimmed)
+                });
+            }
+            return results;
+        }
+    };
+}

package/dist/search/snippet.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Build a short plain-text excerpt of `text` centered on the first matching
+ * query term, for showing context under a search result. Falls back to the head
+ * of the text when nothing matches. Word boundaries are respected so the excerpt
+ * never starts or ends mid-word, and elisions are marked with an ellipsis.
+ */
+export declare function buildSnippet(text: string, query: string, maxLength?: number): string;

package/dist/search/snippet.js

@@ -0,0 +1,43 @@
+/**
+ * Build a short plain-text excerpt of `text` centered on the first matching
+ * query term, for showing context under a search result. Falls back to the head
+ * of the text when nothing matches. Word boundaries are respected so the excerpt
+ * never starts or ends mid-word, and elisions are marked with an ellipsis.
+ */
+export function buildSnippet(text, query, maxLength = 160) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    if (!clean)
+        return '';
+    const haystack = clean.toLowerCase();
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    let match = -1;
+    for (const term of terms) {
+        const i = haystack.indexOf(term);
+        if (i !== -1 && (match === -1 || i < match))
+            match = i;
+    }
+    if (match === -1) {
+        return clean.length > maxLength ? clean.slice(0, maxLength).trimEnd() + '…' : clean;
+    }
+    // Window the text around the match, then snap the edges to word boundaries.
+    const half = Math.floor(maxLength / 2);
+    let end = Math.min(clean.length, Math.max(match + half, maxLength));
+    let start = Math.max(0, end - maxLength);
+    end = Math.min(clean.length, start + maxLength);
+    if (start > 0) {
+        const space = clean.indexOf(' ', start);
+        if (space !== -1 && space < match)
+            start = space + 1;
+    }
+    if (end < clean.length) {
+        const space = clean.lastIndexOf(' ', end);
+        if (space > match)
+            end = space;
+    }
+    let snippet = clean.slice(start, end).trim();
+    if (start > 0)
+        snippet = '…' + snippet;
+    if (end < clean.length)
+        snippet = snippet + '…';
+    return snippet;
+}

package/dist/search.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `svelte-docsmith/search` — the generated search index.
+ *
+ * At build time the `docsmith()` Vite plugin (in `vite.config.ts`) intercepts
+ * this import and replaces it with your doc pages' plain-text bodies. This file
+ * is only the fallback that runs when the plugin is missing — it exists so the
+ * import type-checks and fails with a clear message instead of a mystery.
+ */
+import type { SearchDoc } from './config.js';
+export declare const docs: SearchDoc[];

package/dist/search.js

@@ -0,0 +1,4 @@
+export const docs = [];
+throw new Error("[svelte-docsmith] 'svelte-docsmith/search' requires the docsmith() plugin. " +
+    "Add it to your vite.config: import { docsmith } from 'svelte-docsmith/vite'; " +
+    'plugins: [docsmith(), tailwindcss(), sveltekit()]');