@umami/shiso 1.2.0 → 1.4.0

package/bin/shiso.mjs

@@ -116,6 +116,7 @@ async function main() {
       projectRoot,
     );
     run(process.execPath, [path.join(PACKAGE_ROOT, 'scripts/prerender.mjs')], projectRoot);
+    run(process.execPath, [path.join(PACKAGE_ROOT, 'scripts/pagefind-index.mjs')], projectRoot);
     return;
   }
 

package/dist/chunks/App.js

@@ -25967,7 +25967,7 @@ function CommandGroup({ className, ...props }) {
 function CommandItem({ className, children, ...props }) {
 	return /* @__PURE__ */ jsxs(_e.Item, {
 		"data-slot": "command-item",
-		className: cn("group/command-item relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-lg! data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-selected:bg-muted data-selected:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-selected:*:[svg]:text-foreground", className),
+		className: cn("group/command-item relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-lg! data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-muted data-[selected=true]:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[selected=true]:*:[svg]:text-foreground", className),
 		...props,
 		children: [children, /* @__PURE__ */ jsx(Check$1, { className: "ml-auto opacity-0 group-has-data-[slot=command-shortcut]/command-item:hidden group-data-[checked=true]/command-item:opacity-100" })]
 	});
@@ -25975,6 +25975,21 @@ function CommandItem({ className, children, ...props }) {
 
 //#endregion
 //#region src/components/Search.tsx
+/** Enough results to make the list scroll; the dialog caps its own height. */
+const RESULT_LIMIT = 30;
+/**
+* Renders a snippet, turning provider-supplied `<mark>` tags into highlight
+* elements. Snippets are parsed — never injected as HTML — so any other
+* markup in the text renders literally.
+*/
+function renderSnippet(snippet) {
+	const parts = snippet.split(/<mark>(.*?)<\/mark>/g);
+	if (parts.length === 1) return snippet;
+	return parts.map((part, index) => index % 2 ? /* @__PURE__ */ jsx("mark", {
+		className: "rounded-xs bg-primary/15 px-px text-primary",
+		children: part
+	}, index) : part);
+}
 /**
 * Provider-neutral search dialog. The selected provider and its index or
 * client are loaded on demand, so search stays out of the initial bundle.
@@ -26011,7 +26026,7 @@ function Search({ config, labels }) {
 		try {
 			const activeProvider = await loadProvider();
 			const scope = getScopeByPathname(pathname);
-			const nextResults = await activeProvider.search(value, void 0, {
+			const nextResults = await activeProvider.search(value, RESULT_LIMIT, {
 				scopeId: scope.id,
 				language: scope.language,
 				version: scope.version
@@ -26113,7 +26128,7 @@ function Search({ config, labels }) {
 								children: [result.page, result.heading ? ` › ${result.heading}` : ""]
 							}), result.snippet && /* @__PURE__ */ jsx("div", {
 								className: "mt-[0.15rem] line-clamp-2 text-[0.8rem] text-muted-foreground",
-								children: result.snippet
+								children: renderSnippet(result.snippet)
 							})]
 						}, result.url))
 					}) : null]
@@ -26651,7 +26666,8 @@ function resolveRelated(entries) {
 	return links;
 }
 function DocContent({ page, doc, site }) {
-	const pagerPages = getScopeForPage(docsSite, page).docs.pages.filter((item) => !item.hidden);
+	const scope = getScopeForPage(docsSite, page);
+	const pagerPages = scope.docs.pages.filter((item) => !item.hidden);
 	const pageIndex = pagerPages.findIndex((item) => item.slug === page.slug);
 	const prev = pageIndex > 0 ? pagerPages[pageIndex - 1] : void 0;
 	const next = pageIndex >= 0 ? pagerPages[pageIndex + 1] : void 0;
@@ -26666,8 +26682,16 @@ function DocContent({ page, doc, site }) {
 		dateStyle: "medium",
 		timeZone: "UTC"
 	});
+	const pagefindAttrs = page.hidden || scope.hidden ? {} : {
+		"data-pagefind-body": "",
+		...page.scopeId !== "default" ? {
+			"data-pagefind-filter": "scope[data-scope]",
+			"data-scope": page.scopeId
+		} : {}
+	};
 	return /* @__PURE__ */ jsxs("article", {
 		className: "min-w-0 grow",
+		...pagefindAttrs,
 		children: [
 			eyebrow && /* @__PURE__ */ jsx("div", {
 				className: "text-sm font-bold text-primary",
@@ -26705,11 +26729,12 @@ function DocContent({ page, doc, site }) {
 			related.length > 0 && /* @__PURE__ */ jsxs("nav", {
 				className: "mt-8",
 				"aria-label": site.labels.relatedTopics,
+				"data-pagefind-ignore": true,
 				children: [/* @__PURE__ */ jsx("div", {
 					className: "text-sm text-muted-foreground",
 					children: site.labels.relatedTopics
 				}), /* @__PURE__ */ jsx("ul", {
-					className: "mt-3 flex flex-col gap-2",
+					className: "mt-3 flex flex-col gap-2 text-sm",
 					children: related.map(({ href, title, external }) => /* @__PURE__ */ jsxs("li", {
 						className: "flex items-center gap-2",
 						children: [/* @__PURE__ */ jsx(FileText, {
@@ -26731,6 +26756,7 @@ function DocContent({ page, doc, site }) {
 			}),
 			/* @__PURE__ */ jsxs("div", {
 				className: "mt-8 flex items-center justify-between",
+				"data-pagefind-ignore": true,
 				children: [/* @__PURE__ */ jsx(NavigationButton, {
 					...prev,
 					isPrev: true

package/dist/chunks/local.js

@@ -8,10 +8,19 @@ function filterRecordsByScope(records, context) {
 	return records.filter((record) => !record.scopeId || record.scopeId === context.scopeId);
 }
 const SNIPPET_RADIUS = 60;
-function makeSnippet(text, index, length) {
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Wraps every term occurrence in `<mark>` so the dialog can highlight it. */
+function highlightTerms(snippet, terms) {
+	if (!terms.length) return snippet;
+	const pattern = new RegExp([...terms].sort((a, b) => b.length - a.length).map(escapeRegExp).join("|"), "gi");
+	return snippet.replace(pattern, "<mark>$&</mark>");
+}
+function makeSnippet(text, index, length, terms) {
 	const start = Math.max(0, index - SNIPPET_RADIUS);
 	const end = Math.min(text.length, index + length + SNIPPET_RADIUS);
-	return `${start > 0 ? "…" : ""}${text.slice(start, end).trim()}${end < text.length ? "…" : ""}`;
+	return highlightTerms(`${start > 0 ? "…" : ""}${text.slice(start, end).trim()}${end < text.length ? "…" : ""}`, terms);
 }
 function searchIndex(records, query, limit = 10) {
 	const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
@@ -44,7 +53,7 @@ function searchIndex(records, query, limit = 10) {
 			url: record.id ? `${record.url}#${record.id}` : record.url,
 			page: record.page,
 			heading: record.heading,
-			snippet: snippetAt >= 0 ? makeSnippet(record.text, snippetAt, snippetLength) : void 0,
+			snippet: snippetAt >= 0 ? makeSnippet(record.text, snippetAt, snippetLength, terms) : void 0,
 			score
 		});
 	}

package/dist/chunks/pagefind.js

@@ -0,0 +1,100 @@
+//#region src/lib/search/providers/pagefind.ts
+const DEFAULT_LIMIT = 10;
+/**
+* Sanitizes a Pagefind excerpt: keeps the `<mark>` highlight tags (rendered
+* as highlights by the search dialog, never as raw HTML), strips every other
+* tag, and decodes basic HTML entities.
+*/
+function sanitizePagefindExcerpt(excerpt) {
+	return excerpt.replace(/<(?!\/?mark>)[^>]*>/g, "").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&amp;/g, "&").trim();
+}
+/** Converts a Pagefind result URL into a router-relative path: strips a
+* trailing `/index.html` and trailing slash while preserving `#anchor`. */
+function normalizePagefindUrl(url) {
+	const hashIndex = url.indexOf("#");
+	const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
+	let pathname = hashIndex === -1 ? url : url.slice(0, hashIndex);
+	pathname = pathname.replace(/\/index\.html$/, "/");
+	if (pathname.length > 1) pathname = pathname.replace(/\/+$/, "") || "/";
+	return `${pathname}${hash}`;
+}
+/** Maps loaded Pagefind fragments to `SearchResult`s. Each sub-result (a
+* heading-bounded section) becomes its own result; duplicate URLs are
+* dropped because the search dialog keys items by URL. */
+function mapPagefindResults(fragments, limit) {
+	const results = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const { fragment, score } of fragments) {
+		const page = fragment.meta?.title || fragment.url;
+		const subResults = fragment.sub_results?.length ? fragment.sub_results : [{
+			url: fragment.url,
+			excerpt: fragment.excerpt
+		}];
+		for (const subResult of subResults) {
+			const url = normalizePagefindUrl(subResult.url);
+			if (seen.has(url)) continue;
+			seen.add(url);
+			const heading = url.includes("#") && subResult.title && subResult.title !== page ? subResult.title : void 0;
+			const excerpt = subResult.excerpt || fragment.excerpt;
+			results.push({
+				url,
+				page,
+				heading,
+				snippet: excerpt ? sanitizePagefindExcerpt(excerpt) : void 0,
+				score: score ?? 0
+			});
+			if (results.length >= limit) return results;
+		}
+	}
+	return results;
+}
+/**
+* Built-in provider backed by a Pagefind index generated during `shiso build`.
+* When the Pagefind bundle is unavailable (for example in dev, where no
+* prerendered HTML exists), it falls back to the local provider.
+*/
+function createPagefindSearchProvider(options = {}) {
+	let backend = null;
+	async function loadBackend() {
+		const base = (import.meta.env?.BASE_URL || "/").trim().replace(/\/+$/, "");
+		try {
+			const api = await import(
+				/* @vite-ignore */
+				`${base}/pagefind/pagefind.js`
+);
+			const ranking = options.ranking;
+			await api.options({
+				baseUrl: "/",
+				...ranking && typeof ranking === "object" ? { ranking } : {}
+			});
+			await api.init();
+			return {
+				kind: "pagefind",
+				api
+			};
+		} catch (error) {
+			console.warn("[shiso] Pagefind bundle not found — falling back to local search. This is expected in dev; run \"shiso build\" to generate the Pagefind index.", error);
+			const { createLocalSearchProvider } = await import("./local.js");
+			return {
+				kind: "local",
+				provider: createLocalSearchProvider({})
+			};
+		}
+	}
+	return { async search(query, limit = DEFAULT_LIMIT, context) {
+		backend ||= loadBackend();
+		const resolved = await backend;
+		if (resolved.kind === "local") return resolved.provider.search(query, limit, context);
+		const filters = context?.scopeId && context.scopeId !== "default" ? { filters: { scope: context.scopeId } } : void 0;
+		const response = await resolved.api.search(query, filters);
+		const fragments = [];
+		for (const result of response.results.slice(0, limit)) fragments.push({
+			fragment: await result.data(),
+			score: result.score
+		});
+		return mapPagefindResults(fragments, limit);
+	} };
+}
+
+//#endregion
+export { createPagefindSearchProvider };

package/dist/search.js

@@ -1,5 +1,6 @@
 //#region src/lib/search/provider.ts
 const factories = /* @__PURE__ */ new Map();
+const BUILTIN_PROVIDERS = /* @__PURE__ */ new Set(["local", "pagefind"]);
 function normalizeProviderId(id) {
 	return id.trim().toLowerCase();
 }
@@ -9,7 +10,7 @@ function normalizeProviderId(id) {
 */
 function registerSearchProvider(id, factory) {
 	const providerId = normalizeProviderId(id);
-	if (!providerId || providerId === "local") throw new Error("Search provider ids must be non-empty and cannot replace the built-in \"local\" provider.");
+	if (!providerId || BUILTIN_PROVIDERS.has(providerId)) throw new Error("Search provider ids must be non-empty and cannot replace the built-in providers (\"local\", \"pagefind\").");
 	factories.set(providerId, factory);
 	return () => {
 		if (factories.get(providerId) === factory) factories.delete(providerId);
@@ -27,6 +28,14 @@ async function resolveSearchProvider(id, options = {}) {
 		providerId: "local",
 		fellBack: false
 	};
+	if (requestedId === "pagefind") {
+		const { createPagefindSearchProvider } = await import("./chunks/pagefind.js");
+		return {
+			provider: createPagefindSearchProvider(options),
+			providerId: "pagefind",
+			fellBack: false
+		};
+	}
 	const factory = factories.get(requestedId);
 	if (factory) return {
 		provider: await factory(options),

package/docs.schema.json

@@ -274,7 +274,7 @@
             },
             "provider": {
               "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
-              "description": "Registered search provider id. Defaults to local."
+              "description": "Search provider id: \"local\" (default), \"pagefind\", or a provider registered at runtime."
             },
             "options": {
               "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umami/shiso",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {
@@ -89,6 +89,9 @@
     "unified": "^11.0.5",
     "vite": "^8.2.0"
   },
+  "optionalDependencies": {
+    "pagefind": "^1.4.0"
+  },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/scripts/check-package.mjs

@@ -10,6 +10,7 @@ for (const relativeFile of [
   'dist/search.js',
   'docs.schema.json',
   'scripts/lib/mdast.mjs',
+  'scripts/pagefind-index.mjs',
   'scripts/lib/slug.mjs',
   'src/styles/global.css',
   'types/client.d.ts',

package/scripts/generate-icon-registry.mjs

@@ -18,8 +18,18 @@ const DEFAULT_ROOT = process.cwd();
 const SCAN_DIRS = ['content', 'src'];
 const SCAN_EXTENSIONS = new Set(['.md', '.mdx', '.tsx']);
 
-// Icons used by the docs component library itself, so pages always have a baseline set.
-const ALWAYS_INCLUDE = ['rocket', 'code', 'book-open', 'circle-check', 'circle-alert'];
+// Icons used by the docs component library itself, so pages always have a baseline
+// set. `copy` and `external-link` back the built-in contextual menu options, whose
+// names are assigned in site-model.ts rather than as `icon="..."` attributes.
+const ALWAYS_INCLUDE = [
+  'rocket',
+  'code',
+  'book-open',
+  'circle-check',
+  'circle-alert',
+  'copy',
+  'external-link',
+];
 
 const ICON_ATTRIBUTE = /\bicon\s*=\s*["']([^"'{}\n]+)["']/g;
 

package/scripts/pagefind-index.mjs

@@ -0,0 +1,127 @@
+/**
+ * Generates a Pagefind index over the prerendered HTML.
+ *
+ * Runs after `prerender.mjs` as the final step of `shiso build`, from the
+ * project root. It is a no-op unless docs.json resolves `search.provider`
+ * to "pagefind". Only pages carrying `data-pagefind-body` (the doc
+ * `<article>`) are indexed, so redirect stubs and the 404 page are skipped
+ * automatically.
+ *
+ * The base subdirectory of dist/client is indexed (not dist/client itself)
+ * so the recorded URLs are base-relative — the runtime provider hands them
+ * to a router whose `basename` re-applies the deploy base.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+import { loadDocsConfig } from './load-docs-config.mjs';
+
+const root = process.cwd();
+const clientDir = path.join(root, 'dist', 'client');
+
+const { config } = await loadDocsConfig({ root });
+
+const search = config.search;
+const provider =
+  search === false
+    ? ''
+    : String(search?.provider || 'local')
+        .trim()
+        .toLowerCase();
+
+if (provider !== 'pagefind') {
+  process.exit(0);
+}
+
+let pagefind;
+
+try {
+  pagefind = await import('pagefind');
+} catch (error) {
+  if (error?.code === 'ERR_MODULE_NOT_FOUND') {
+    console.error(
+      'search.provider is "pagefind" but the "pagefind" package is not installed.\n' +
+        'It is an optional dependency of @umami/shiso — install it in your project:\n\n' +
+        '  pnpm add -D pagefind\n',
+    );
+    process.exit(1);
+  }
+
+  throw error;
+}
+
+/** Vite's `base`, normalized to "" or "/prefix". Mirrors prerender.mjs. */
+function readBase(template) {
+  const match = template.match(/<script[^>]+src="([^"]*)\/assets\//);
+  const base = match?.[1] ?? '';
+  return base === '/' ? '' : base;
+}
+
+const template = await readFile(path.join(clientDir, 'index.html'), 'utf8');
+const base = readBase(template);
+const indexRoot = path.join(clientDir, ...base.split('/').filter(Boolean));
+const outputPath = path.join(indexRoot, 'pagefind');
+
+// The permalink "#" appended to every heading (rehype-autolink-headings in
+// mdx.config.ts) must not leak into indexed titles and excerpts.
+const DEFAULT_EXCLUDE_SELECTORS = ['.heading-anchor'];
+
+const searchOptions = search && typeof search === 'object' ? search.options || {} : {};
+const excludeSelectors = [
+  ...DEFAULT_EXCLUDE_SELECTORS,
+  ...(Array.isArray(searchOptions.excludeSelectors) ? searchOptions.excludeSelectors : []),
+];
+
+const { index, errors: createErrors } = await pagefind.createIndex({ excludeSelectors });
+
+if (!index) {
+  console.error(`Pagefind index creation failed:\n${(createErrors || []).join('\n')}`);
+  process.exit(1);
+}
+
+const { page_count, errors } = await index.addDirectory({ path: indexRoot, glob: '**/*.html' });
+
+if (errors?.length) {
+  console.error(`Pagefind indexing failed:\n${errors.join('\n')}`);
+  await pagefind.close();
+  process.exit(1);
+}
+
+if (!page_count) {
+  console.error(
+    'Pagefind indexed 0 pages. Expected prerendered pages with a data-pagefind-body attribute ' +
+      `under ${path.relative(root, indexRoot)}.`,
+  );
+  await pagefind.close();
+  process.exit(1);
+}
+
+const { errors: writeErrors } = await index.writeFiles({ outputPath });
+
+if (writeErrors?.length) {
+  console.error(`Pagefind bundle write failed:\n${writeErrors.join('\n')}`);
+  await pagefind.close();
+  process.exit(1);
+}
+
+await pagefind.close();
+
+// `addDirectory` counts scanned files; the entry manifest counts pages that
+// actually carried `data-pagefind-body` and made it into the index.
+const entry = JSON.parse(await readFile(path.join(outputPath, 'pagefind-entry.json'), 'utf8'));
+const indexedPages = Object.values(entry.languages || {}).reduce(
+  (total, language) => total + (language.page_count || 0),
+  0,
+);
+
+if (!indexedPages) {
+  console.error(
+    'Pagefind indexed 0 pages. Expected prerendered pages with a data-pagefind-body attribute ' +
+      `under ${path.relative(root, indexRoot)}.`,
+  );
+  process.exit(1);
+}
+
+console.log(`Pagefind indexed ${indexedPages} pages into ${path.relative(root, outputPath)}`);

package/src/components/DocContent.tsx

@@ -59,8 +59,9 @@ export interface DocContentProps {
 }
 
 export function DocContent({ page, doc, site }: DocContentProps) {
+  const scope = getScopeForPage(docsSite, page);
   // Prev/next paging never crosses a version or language boundary.
-  const pagerPages = getScopeForPage(docsSite, page).docs.pages.filter(item => !item.hidden);
+  const pagerPages = scope.docs.pages.filter(item => !item.hidden);
   const pageIndex = pagerPages.findIndex(item => item.slug === page.slug);
   const prev = pageIndex > 0 ? pagerPages[pageIndex - 1] : undefined;
   const next = pageIndex >= 0 ? pagerPages[pageIndex + 1] : undefined;
@@ -85,8 +86,21 @@ export function DocContent({ page, doc, site }: DocContentProps) {
     timeZone: 'UTC',
   });
 
+  // Pagefind indexing markers on the prerendered HTML. Inert unless the site
+  // uses the pagefind provider. Hidden pages/scopes mirror the local index's
+  // search visibility rules; the scope filter matches the id Search.tsx sends.
+  const pagefindAttrs =
+    page.hidden || scope.hidden
+      ? {}
+      : {
+          'data-pagefind-body': '',
+          ...(page.scopeId !== 'default'
+            ? { 'data-pagefind-filter': 'scope[data-scope]', 'data-scope': page.scopeId }
+            : {}),
+        };
+
   return (
-    <article className="min-w-0 grow">
+    <article className="min-w-0 grow" {...pagefindAttrs}>
       {eyebrow && <div className="text-sm font-bold text-primary">{eyebrow}</div>}
       <div className="flex items-start justify-between gap-4">
         {title && (
@@ -107,9 +121,9 @@ export function DocContent({ page, doc, site }: DocContentProps) {
         </div>
       )}
       {related.length > 0 && (
-        <nav className="mt-8" aria-label={site.labels.relatedTopics}>
+        <nav className="mt-8" aria-label={site.labels.relatedTopics} data-pagefind-ignore>
           <div className="text-sm text-muted-foreground">{site.labels.relatedTopics}</div>
-          <ul className="mt-3 flex flex-col gap-2">
+          <ul className="mt-3 flex flex-col gap-2 text-sm">
             {related.map(({ href, title, external }) => (
               <li key={href} className="flex items-center gap-2">
                 <FileText size={14} className="shrink-0 text-muted-foreground" />
@@ -132,7 +146,7 @@ export function DocContent({ page, doc, site }: DocContentProps) {
           </ul>
         </nav>
       )}
-      <div className="mt-8 flex items-center justify-between">
+      <div className="mt-8 flex items-center justify-between" data-pagefind-ignore>
         <NavigationButton {...prev} isPrev />
         <NavigationButton {...next} />
       </div>

package/src/components/Search.tsx

@@ -17,6 +17,33 @@ import { resolveSearchProvider, type SearchProvider } from '@/lib/search/provide
 import { getScopeByPathname } from '@/lib/site-config';
 import type { ThemeLabels } from '@/lib/types';
 
+/** Enough results to make the list scroll; the dialog caps its own height. */
+const RESULT_LIMIT = 30;
+
+/**
+ * Renders a snippet, turning provider-supplied `<mark>` tags into highlight
+ * elements. Snippets are parsed — never injected as HTML — so any other
+ * markup in the text renders literally.
+ */
+function renderSnippet(snippet: string) {
+  const parts = snippet.split(/<mark>(.*?)<\/mark>/g);
+
+  if (parts.length === 1) {
+    return snippet;
+  }
+
+  return parts.map((part, index) =>
+    index % 2 ? (
+      // biome-ignore lint/suspicious/noArrayIndexKey: parts are positional and never reorder.
+      <mark key={index} className="rounded-xs bg-primary/15 px-px text-primary">
+        {part}
+      </mark>
+    ) : (
+      part
+    ),
+  );
+}
+
 /**
  * Provider-neutral search dialog. The selected provider and its index or
  * client are loaded on demand, so search stays out of the initial bundle.
@@ -71,7 +98,7 @@ export function Search({ config, labels }: { config: ResolvedSearchConfig; label
         // Search stays inside the version/language scope being browsed.
         // Providers that predate the context argument simply ignore it.
         const scope = getScopeByPathname(pathname);
-        const nextResults = await activeProvider.search(value, undefined, {
+        const nextResults = await activeProvider.search(value, RESULT_LIMIT, {
           scopeId: scope.id,
           language: scope.language,
           version: scope.version,
@@ -202,7 +229,7 @@ export function Search({ config, labels }: { config: ResolvedSearchConfig; label
                     </div>
                     {result.snippet && (
                       <div className="mt-[0.15rem] line-clamp-2 text-[0.8rem] text-muted-foreground">
-                        {result.snippet}
+                        {renderSnippet(result.snippet)}
                       </div>
                     )}
                   </CommandItem>

package/src/components/ui/command.tsx

@@ -136,7 +136,7 @@ function CommandItem({
     <CommandPrimitive.Item
       data-slot="command-item"
       className={cn(
-        "group/command-item relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-lg! data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-selected:bg-muted data-selected:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-selected:*:[svg]:text-foreground",
+        "group/command-item relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-lg! data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-muted data-[selected=true]:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[selected=true]:*:[svg]:text-foreground",
         className,
       )}
       {...props}
@@ -152,7 +152,7 @@ function CommandShortcut({ className, ...props }: React.ComponentProps<'span'>)
     <span
       data-slot="command-shortcut"
       className={cn(
-        'ml-auto text-xs tracking-widest text-muted-foreground group-data-selected/command-item:text-foreground',
+        'ml-auto text-xs tracking-widest text-muted-foreground group-data-[selected=true]/command-item:text-foreground',
         className,
       )}
       {...props}

package/src/lib/search/provider.ts

@@ -21,6 +21,8 @@ export interface ResolvedSearchProvider {
 
 const factories = new Map<string, SearchProviderFactory>();
 
+const BUILTIN_PROVIDERS = new Set(['local', 'pagefind']);
+
 function normalizeProviderId(id: string): string {
   return id.trim().toLowerCase();
 }
@@ -32,9 +34,9 @@ function normalizeProviderId(id: string): string {
 export function registerSearchProvider(id: string, factory: SearchProviderFactory): () => void {
   const providerId = normalizeProviderId(id);
 
-  if (!providerId || providerId === 'local') {
+  if (!providerId || BUILTIN_PROVIDERS.has(providerId)) {
     throw new Error(
-      'Search provider ids must be non-empty and cannot replace the built-in "local" provider.',
+      'Search provider ids must be non-empty and cannot replace the built-in providers ("local", "pagefind").',
     );
   }
 
@@ -67,6 +69,15 @@ export async function resolveSearchProvider(
     };
   }
 
+  if (requestedId === 'pagefind') {
+    const { createPagefindSearchProvider } = await import('@/lib/search/providers/pagefind');
+    return {
+      provider: createPagefindSearchProvider(options),
+      providerId: 'pagefind',
+      fellBack: false,
+    };
+  }
+
   const factory = factories.get(requestedId);
 
   if (factory) {

package/src/lib/search/providers/pagefind.ts

@@ -0,0 +1,180 @@
+import type { SearchContext, SearchResult } from '@/lib/search';
+import type { SearchProvider } from '@/lib/search/provider';
+
+/** Subset of the Pagefind browser API used by this provider. The types are
+ * declared locally because the `pagefind` package is an optional dependency
+ * and its browser bundle only exists in built output. */
+interface PagefindSubResult {
+  title?: string;
+  url: string;
+  excerpt?: string;
+}
+
+export interface PagefindFragment {
+  url: string;
+  excerpt?: string;
+  meta?: { title?: string };
+  sub_results?: PagefindSubResult[];
+}
+
+export interface PagefindResult {
+  id: string;
+  score?: number;
+  data(): Promise<PagefindFragment>;
+}
+
+interface PagefindApi {
+  options(options: Record<string, unknown>): Promise<void>;
+  init(): Promise<void>;
+  search(query: string, options?: Record<string, unknown>): Promise<{ results: PagefindResult[] }>;
+}
+
+type Backend = { kind: 'pagefind'; api: PagefindApi } | { kind: 'local'; provider: SearchProvider };
+
+const DEFAULT_LIMIT = 10;
+
+/**
+ * Sanitizes a Pagefind excerpt: keeps the `<mark>` highlight tags (rendered
+ * as highlights by the search dialog, never as raw HTML), strips every other
+ * tag, and decodes basic HTML entities.
+ */
+export function sanitizePagefindExcerpt(excerpt: string): string {
+  return excerpt
+    .replace(/<(?!\/?mark>)[^>]*>/g, '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&')
+    .trim();
+}
+
+/** Converts a Pagefind result URL into a router-relative path: strips a
+ * trailing `/index.html` and trailing slash while preserving `#anchor`. */
+export function normalizePagefindUrl(url: string): string {
+  const hashIndex = url.indexOf('#');
+  const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
+  let pathname = hashIndex === -1 ? url : url.slice(0, hashIndex);
+
+  pathname = pathname.replace(/\/index\.html$/, '/');
+
+  if (pathname.length > 1) {
+    pathname = pathname.replace(/\/+$/, '') || '/';
+  }
+
+  return `${pathname}${hash}`;
+}
+
+/** Maps loaded Pagefind fragments to `SearchResult`s. Each sub-result (a
+ * heading-bounded section) becomes its own result; duplicate URLs are
+ * dropped because the search dialog keys items by URL. */
+export function mapPagefindResults(
+  fragments: { fragment: PagefindFragment; score?: number }[],
+  limit: number,
+): SearchResult[] {
+  const results: SearchResult[] = [];
+  const seen = new Set<string>();
+
+  for (const { fragment, score } of fragments) {
+    const page = fragment.meta?.title || fragment.url;
+    const subResults = fragment.sub_results?.length
+      ? fragment.sub_results
+      : [{ url: fragment.url, excerpt: fragment.excerpt }];
+
+    for (const subResult of subResults) {
+      const url = normalizePagefindUrl(subResult.url);
+
+      if (seen.has(url)) {
+        continue;
+      }
+
+      seen.add(url);
+
+      const hasAnchor = url.includes('#');
+      const heading =
+        hasAnchor && subResult.title && subResult.title !== page ? subResult.title : undefined;
+      const excerpt = subResult.excerpt || fragment.excerpt;
+
+      results.push({
+        url,
+        page,
+        heading,
+        snippet: excerpt ? sanitizePagefindExcerpt(excerpt) : undefined,
+        score: score ?? 0,
+      });
+
+      if (results.length >= limit) {
+        return results;
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Built-in provider backed by a Pagefind index generated during `shiso build`.
+ * When the Pagefind bundle is unavailable (for example in dev, where no
+ * prerendered HTML exists), it falls back to the local provider.
+ */
+export function createPagefindSearchProvider(
+  options: Record<string, unknown> = {},
+): SearchProvider {
+  let backend: Promise<Backend> | null = null;
+
+  async function loadBackend(): Promise<Backend> {
+    // Mirrors the BASE_URL normalization in `@/lib/paths` without importing
+    // it — that module depends on `virtual:shiso-docs-config`, which is not
+    // available to the standalone `@umami/shiso/search` bundle.
+    const base = (import.meta.env?.BASE_URL || '/').trim().replace(/\/+$/, '');
+
+    try {
+      const api: PagefindApi = await import(/* @vite-ignore */ `${base}/pagefind/pagefind.js`);
+      const ranking = options.ranking;
+
+      await api.options({
+        baseUrl: '/',
+        ...(ranking && typeof ranking === 'object' ? { ranking } : {}),
+      });
+      await api.init();
+
+      return { kind: 'pagefind', api };
+    } catch (error) {
+      console.warn(
+        '[shiso] Pagefind bundle not found — falling back to local search. ' +
+          'This is expected in dev; run "shiso build" to generate the Pagefind index.',
+        error,
+      );
+
+      const { createLocalSearchProvider } = await import('@/lib/search/providers/local');
+
+      return { kind: 'local', provider: createLocalSearchProvider({}) };
+    }
+  }
+
+  return {
+    async search(query: string, limit = DEFAULT_LIMIT, context?: SearchContext) {
+      backend ||= loadBackend();
+      const resolved = await backend;
+
+      if (resolved.kind === 'local') {
+        return resolved.provider.search(query, limit, context);
+      }
+
+      const filters =
+        context?.scopeId && context.scopeId !== 'default'
+          ? { filters: { scope: context.scopeId } }
+          : undefined;
+      const response = await resolved.api.search(query, filters);
+      const fragments: { fragment: PagefindFragment; score?: number }[] = [];
+
+      // Hydrate fragments lazily; each page yields at least one result, so
+      // `limit` pages is always enough to fill `limit` results.
+      for (const result of response.results.slice(0, limit)) {
+        fragments.push({ fragment: await result.data(), score: result.score });
+      }
+
+      return mapPagefindResults(fragments, limit);
+    },
+  };
+}

package/src/lib/search.ts

@@ -55,7 +55,11 @@ export interface SearchResult {
   page: string;
   /** Section heading, absent for the page intro. */
   heading?: string;
-  /** Snippet of section text around the first match, when the text matched. */
+  /**
+   * Snippet of section text around the first match, when the text matched.
+   * Matched terms may be wrapped in `<mark>` tags; the search dialog renders
+   * them as highlights (never as raw HTML).
+   */
   snippet?: string;
   /** Provider-specific relevance score. Use 0 when a provider does not expose one. */
   score: number;
@@ -63,11 +67,34 @@ export interface SearchResult {
 
 const SNIPPET_RADIUS = 60;
 
-function makeSnippet(text: string, index: number, length: number): string {
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Wraps every term occurrence in `<mark>` so the dialog can highlight it. */
+export function highlightTerms(snippet: string, terms: string[]): string {
+  if (!terms.length) {
+    return snippet;
+  }
+
+  // Longer terms first, so overlapping terms highlight the longest match.
+  const pattern = new RegExp(
+    [...terms]
+      .sort((a, b) => b.length - a.length)
+      .map(escapeRegExp)
+      .join('|'),
+    'gi',
+  );
+
+  return snippet.replace(pattern, '<mark>$&</mark>');
+}
+
+function makeSnippet(text: string, index: number, length: number, terms: string[]): string {
   const start = Math.max(0, index - SNIPPET_RADIUS);
   const end = Math.min(text.length, index + length + SNIPPET_RADIUS);
+  const excerpt = `${start > 0 ? '…' : ''}${text.slice(start, end).trim()}${end < text.length ? '…' : ''}`;
 
-  return `${start > 0 ? '…' : ''}${text.slice(start, end).trim()}${end < text.length ? '…' : ''}`;
+  return highlightTerms(excerpt, terms);
 }
 
 export function searchIndex(records: SearchRecord[], query: string, limit = 10): SearchResult[] {
@@ -119,7 +146,8 @@ export function searchIndex(records: SearchRecord[], query: string, limit = 10):
       url: record.id ? `${record.url}#${record.id}` : record.url,
       page: record.page,
       heading: record.heading,
-      snippet: snippetAt >= 0 ? makeSnippet(record.text, snippetAt, snippetLength) : undefined,
+      snippet:
+        snippetAt >= 0 ? makeSnippet(record.text, snippetAt, snippetLength, terms) : undefined,
       score,
     });
   }

package/src/lib/types.ts

@@ -219,7 +219,7 @@ export interface FontsConfig extends FontSpec {
 export interface SearchConfig {
   /** Placeholder text for the search input. */
   prompt?: string;
-  /** Registered provider id. Defaults to the built-in local provider. */
+  /** Provider id: "local" (default), "pagefind", or a runtime-registered id. */
   provider?: string;
   /** Provider-specific configuration. */
   options?: Record<string, unknown>;

package/src/styles/global.css

@@ -146,25 +146,46 @@
     font-size: 0.875rem;
   }
 
+  /* Styled to match the PropertiesTable component: rounded outer border,
+     horizontal row separators only, and no header fill. */
   .docs-markdown table {
     width: 100%;
-    border-collapse: collapse;
     margin: 1rem 0;
     font-size: 0.875rem;
+    border-collapse: separate;
+    border-spacing: 0;
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
   }
 
   .docs-markdown th,
   .docs-markdown td {
-    border: 1px solid var(--border);
-    padding: 0.5rem 0.75rem;
+    border: none;
+    border-bottom: 1px solid var(--border);
+    padding: 0.6rem 0.75rem;
     text-align: left;
+    vertical-align: top;
+  }
+
+  .docs-markdown th:first-child,
+  .docs-markdown td:first-child {
+    padding-left: 1.5rem;
+  }
+
+  .docs-markdown th:last-child,
+  .docs-markdown td:last-child {
+    padding-right: 1.5rem;
   }
 
   .docs-markdown th {
-    background: var(--card);
+    background: transparent;
     font-weight: 600;
   }
 
+  .docs-markdown tbody tr:last-child td {
+    border-bottom: none;
+  }
+
   .docs-markdown table code:not(pre code) {
     font-size: 0.75rem;
   }

package/types/search.d.ts

@@ -3,6 +3,10 @@ export interface SearchResult {
   page: string;
   score: number;
   heading?: string;
+  /**
+   * Matched terms may be wrapped in `<mark>` tags; the search dialog renders
+   * them as highlights (never as raw HTML).
+   */
   snippet?: string;
 }
 
@@ -24,4 +28,9 @@ export type SearchProviderFactory = (
   options: Record<string, unknown>,
 ) => SearchProvider | Promise<SearchProvider>;
 
+/**
+ * Registers a runtime search provider. Call this before rendering the app.
+ * The ids "local" and "pagefind" are reserved for the built-in providers.
+ * The returned cleanup function only removes this exact registration.
+ */
 export function registerSearchProvider(id: string, factory: SearchProviderFactory): () => void;

package/vite.config.ts

@@ -1,3 +1,4 @@
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import tailwindcss from '@tailwindcss/vite';
@@ -281,6 +282,75 @@ function shisoHtml(getDocsConfig: () => DocsConfig): Plugin {
   };
 }
 
+/**
+ * Serves the raw markdown source for `<route>.md` URLs during development,
+ * mirroring the `.md` copies the prerenderer publishes next to every page in
+ * production builds. The contextual menu's copy/view options and AI links
+ * depend on these URLs.
+ */
+function shisoMarkdownDev(getDocsConfig: () => DocsConfig, root: string): Plugin {
+  return {
+    name: 'shiso-markdown-dev',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(async (req, res, next) => {
+        const url = (req.url || '').split('?')[0];
+
+        if ((req.method !== 'GET' && req.method !== 'HEAD') || !url.endsWith('.md')) {
+          return next();
+        }
+
+        const shiso =
+          (getDocsConfig() as { $shiso?: { docsPrefix?: string; contentDir?: string } }).$shiso ||
+          {};
+        const contentDir = (shiso.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
+        const prefixValue = (shiso.docsPrefix ?? '/docs').trim().replace(/\/+$/, '');
+        const docsPrefix =
+          !prefixValue || prefixValue === '/'
+            ? ''
+            : prefixValue.startsWith('/')
+              ? prefixValue
+              : `/${prefixValue}`;
+
+        let route = decodeURIComponent(url).slice(0, -'.md'.length);
+        const base = server.config.base.replace(/\/+$/, '');
+
+        if (base && route.startsWith(base)) {
+          route = route.slice(base.length);
+        }
+
+        if (docsPrefix && route.startsWith(docsPrefix)) {
+          route = route.slice(docsPrefix.length);
+        }
+
+        const slug = route.replace(/^\/+/, '') || 'index';
+        const contentRoot = path.resolve(root, contentDir);
+        const candidates = [`${slug}.mdx`, `${slug}.md`, `${slug}/index.mdx`, `${slug}/index.md`];
+
+        for (const candidate of candidates) {
+          const filePath = path.resolve(contentRoot, candidate);
+
+          // Never read outside the content directory.
+          if (!filePath.startsWith(contentRoot + path.sep)) {
+            break;
+          }
+
+          try {
+            const source = await readFile(filePath, 'utf8');
+            res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+            res.end(source);
+            return;
+          } catch {
+            // Try the next candidate.
+          }
+        }
+
+        next();
+      });
+    },
+  };
+}
+
 const MDX_REACT_ENTRY = fileURLToPath(import.meta.resolve('@mdx-js/react'));
 const LUCIDE_REACT_ENTRY = path.join(
   path.dirname(fileURLToPath(import.meta.resolve('lucide-react/package.json'))),
@@ -319,6 +389,7 @@ export default defineConfig(async () => {
         path.join(generatedRoot, 'search-index.generated.ts'),
       ),
       shisoHtml(getDocsConfig),
+      shisoMarkdownDev(getDocsConfig, projectRoot),
       shisoMdx(),
       react({ include: /\.(mdx|md|tsx|ts|jsx|js)$/ }),
     ],