@umami/shiso 1.3.0 → 1.5.0

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/entry-client.js

@@ -1,4 +1,4 @@
-import { h as BrowserRouter, p as BASE_URL, t as App } from "./chunks/App.js";
+import { g as BrowserRouter, m as BASE_URL, t as App } from "./chunks/App.js";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/entry-client.tsx

package/dist/entry-server.js

@@ -1,4 +1,4 @@
-import { _ as createPath, a as docsSite, c as getSeo, d as getLastModified, f as getScopeForPage, g as Router, i as docsHomeUrl, l as siteName, m as toAbsoluteUrl, n as buildHead, o as getLocaleByPathname, p as BASE_URL, r as renderHeadToString, s as getRedirects, t as App, u as getDocModule, v as parsePath, y as ABSOLUTE_URL_REGEX } from "./chunks/App.js";
+import { _ as Router, a as docsSite, b as ABSOLUTE_URL_REGEX, c as getSeo, d as getDocModule, f as getLastModified, h as toAbsoluteUrl, i as docsHomeUrl, l as siteName, m as BASE_URL, n as buildHead, o as getLocaleByPathname, p as getScopeForPage, r as renderHeadToString, s as getRedirects, t as App, u as standalonePages, v as createPath, y as parsePath } from "./chunks/App.js";
 import * as React$1 from "react";
 import { jsx } from "react/jsx-runtime";
 import { renderToString } from "react-dom/server";
@@ -88,7 +88,7 @@ function encodeLocation(to) {
 //#region src/entry-server.tsx
 /** Base-relative routes for every scope. The prerenderer prepends the deploy base itself. */
 function getRoutes() {
-	return docsSite.pages.map((page) => page.url);
+	return [...docsSite.pages.map((page) => page.url), ...standalonePages.map((page) => page.path)];
 }
 /**
 * Source file for every routed page, so the prerenderer can publish raw
@@ -97,14 +97,17 @@ function getRoutes() {
 * "/content/docs/index.mdx", resolved against the project root.
 */
 function getMarkdownPages() {
-	return docsSite.pages.map((page) => ({
+	return [...docsSite.pages.map((page) => ({
 		route: page.url,
 		filePath: page.filePath
-	}));
+	})), ...standalonePages.map((page) => ({
+		route: page.path,
+		filePath: page.filePath
+	}))];
 }
 /**
 * Absolute URLs for the sitemap, honoring `seo.indexing` and per-page
-* noindex. Empty when `$shiso.siteUrl` is not configured, since a sitemap
+* noindex. Empty when the shiso.config `siteUrl` is not configured, since a sitemap
 * of relative URLs is invalid.
 */
 function getSitemapEntries() {
@@ -119,6 +122,14 @@ function getSitemapEntries() {
 			lastmod: getLastModified(page.filePath)
 		});
 	}
+	for (const page of standalonePages) {
+		if (getDocModule(page.filePath)?.frontmatter?.noindex === true) continue;
+		const url = toAbsoluteUrl(page.path);
+		if (url) entries.push({
+			url,
+			lastmod: getLastModified(page.filePath)
+		});
+	}
 	return entries;
 }
 function render(url) {

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

@@ -14,32 +14,6 @@
       "allOf": [{ "$ref": "#/definitions/stringValue" }],
       "description": "Path or URL to this schema, for editor autocomplete."
     },
-    "$shiso": {
-      "type": "object",
-      "description": "Shiso-only options. Namespaced so the rest of the file stays portable.",
-      "additionalProperties": false,
-      "properties": {
-        "$ref": { "$ref": "#/definitions/configRef" },
-        "docsPrefix": {
-          "allOf": [{ "$ref": "#/definitions/stringValue" }],
-          "description": "Route prefix for docs pages. Defaults to \"/docs\"; use \"\" to serve docs at the site root.",
-          "default": "/docs"
-        },
-        "contentDir": {
-          "allOf": [{ "$ref": "#/definitions/stringValue" }],
-          "description": "Content directory relative to the project root.",
-          "default": "content/docs"
-        },
-        "siteUrl": {
-          "allOf": [{ "$ref": "#/definitions/stringValue" }],
-          "description": "Absolute site origin (e.g. \"https://docs.example.com\"). Required for canonical, og:url, and structured data."
-        },
-        "locale": {
-          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
-          "description": "Locale used for dates and theme-provided interface copy. Defaults to en-US."
-        }
-      }
-    },
     "name": {
       "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
       "description": "Site name, shown in the header and the page title."
@@ -101,6 +75,35 @@
       "allOf": [{ "$ref": "#/definitions/stringValue" }],
       "description": "Path to the favicon, relative to the public directory."
     },
+    "pages": {
+      "type": ["array", "object"],
+      "if": { "type": "object" },
+      "then": { "$ref": "#/definitions/configRefValue" },
+      "description": "Standalone pages outside the docs navigation, such as a landing page. Each entry maps a route path to a file under content/pages.",
+      "items": {
+        "type": "object",
+        "anyOf": [{ "required": ["$ref"] }, { "required": ["path", "page"] }],
+        "additionalProperties": false,
+        "properties": {
+          "$ref": { "$ref": "#/definitions/configRef" },
+          "path": {
+            "anyOf": [
+              { "type": "string", "pattern": "^/[^*:]*$" },
+              { "$ref": "#/definitions/configRefValue" }
+            ],
+            "description": "Route path starting with \"/\". Use \"/\" for the site home page."
+          },
+          "page": {
+            "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+            "description": "File slug under content/pages, e.g. \"home\" for content/pages/home.mdx."
+          },
+          "title": {
+            "allOf": [{ "$ref": "#/definitions/stringValue" }],
+            "description": "Page title used in the document head. Frontmatter title wins."
+          }
+        }
+      }
+    },
     "navigation": {
       "type": "object",
       "description": "Site navigation. Define exactly one of: tabs, dropdowns, versions, languages, or top-level groups/pages.",
@@ -274,7 +277,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,12 +1,16 @@
 {
   "name": "@umami/shiso",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {
     "shiso": "./bin/shiso.mjs"
   },
   "exports": {
+    "./config": {
+      "types": "./types/config.d.ts",
+      "default": "./config.js"
+    },
     "./client": {
       "types": "./types/client.d.ts",
       "default": "./dist/entry-client.js"
@@ -22,6 +26,7 @@
   },
   "files": [
     "bin",
+    "config.js",
     "dist",
     "scripts",
     "src",
@@ -72,6 +77,7 @@
     "estree-util-value-to-estree": "^3.5.0",
     "github-slugger": "^2.0.0",
     "highlight.js": "^11.11.1",
+    "jiti": "^2.4.0",
     "lucide-react": "^1.28.0",
     "react-router": "^8.3.0",
     "rehype-autolink-headings": "^7.1.0",
@@ -89,6 +95,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/build-runtime.mjs

@@ -12,6 +12,7 @@ const projectModules = new Set([
   '@/lib/icon-registry.generated',
   '@/lib/search-index.generated',
   'virtual:shiso-docs-config',
+  'virtual:shiso-config',
 ]);
 
 const peerModules = new Set(['react', 'react-dom']);

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/generate-search-index.mjs

@@ -24,6 +24,7 @@ import { unified } from 'unified';
 import { headingText } from './lib/mdast.mjs';
 import { createSlugger, slugifyId } from './lib/slug.mjs';
 import { loadDocsConfig } from './load-docs-config.mjs';
+import { loadShisoConfig } from './load-shiso-config.mjs';
 
 const DEFAULT_ROOT = process.cwd();
 
@@ -197,15 +198,15 @@ function collectSections(tree) {
     .filter(section => section.heading || section.text);
 }
 
-/** @param {{ config?: object, root?: string, output?: string }} [options] */
+/** @param {{ config?: object, shiso?: object, root?: string, output?: string }} [options] */
 export async function generateSearchIndex({
   config,
+  shiso,
   root = DEFAULT_ROOT,
   output = path.join(root, '.shiso/search-index.generated.ts'),
 } = {}) {
   const docsJson = config ?? (await loadDocsConfig({ root })).config;
-  const docsPrefix = (docsJson.$shiso?.docsPrefix ?? '/docs').replace(/\/+$/, '');
-  const contentDir = (docsJson.$shiso?.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
+  const { docsPrefix, contentDir } = shiso ?? (await loadShisoConfig({ root })).config;
 
   const seen = new Set();
   const records = [];

package/scripts/load-shiso-config.mjs

@@ -0,0 +1,167 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createJiti } from 'jiti';
+
+/**
+ * Loads the optional project code config (shiso.config.ts/.mjs/.js).
+ *
+ * docs.json stays declarative data; this file holds engine settings that may
+ * grow programmatic forms later (env logic, plugins). The user's file is
+ * evaluated with jiti so TypeScript works without Node type stripping; this
+ * loader itself stays plain JS per the scripts constraint.
+ */
+
+/** Candidate filenames in precedence order. Exactly one may exist. */
+export const SHISO_CONFIG_FILES = ['shiso.config.ts', 'shiso.config.mjs', 'shiso.config.js'];
+
+const KNOWN_KEYS = ['docsPrefix', 'contentDir', 'siteUrl', 'locale'];
+
+let importGeneration = 0;
+
+/** Error raised while locating, evaluating, or validating shiso.config. */
+export class ShisoConfigLoadError extends Error {
+  constructor(message, { cause, code, sourcePath } = {}) {
+    super(message, { cause });
+    this.name = 'ShisoConfigLoadError';
+    this.code = code;
+    this.sourcePath = sourcePath;
+  }
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Strips trailing slashes; "/" and "" both normalize to "". */
+function normalizePrefix(value) {
+  const trimmed = value.trim().replace(/\/+$/, '');
+
+  if (!trimmed || trimmed === '/') {
+    return '';
+  }
+
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+function assertStringOption(raw, key, sourcePath) {
+  if (raw[key] !== undefined && typeof raw[key] !== 'string') {
+    throw new ShisoConfigLoadError(
+      `Shiso config option "${key}" must be a string, received ${Array.isArray(raw[key]) ? 'array' : typeof raw[key]}.`,
+      { code: 'INVALID_OPTION', sourcePath },
+    );
+  }
+}
+
+/**
+ * Applies defaults and normalization. Single source of truth for resolved
+ * values, so runtime and build-time consumers never re-implement defaulting.
+ */
+export function resolveShisoConfig(raw = {}, sourcePath = null) {
+  for (const key of KNOWN_KEYS) {
+    assertStringOption(raw, key, sourcePath);
+  }
+
+  return {
+    docsPrefix: normalizePrefix(raw.docsPrefix ?? '/docs'),
+    contentDir: (raw.contentDir ?? 'content/docs').trim().replace(/^\/+|\/+$/g, ''),
+    siteUrl: raw.siteUrl?.trim().replace(/\/+$/, '') || undefined,
+    locale: raw.locale?.trim() || 'en-US',
+  };
+}
+
+async function findConfigFiles(projectRoot) {
+  const found = [];
+
+  for (const name of SHISO_CONFIG_FILES) {
+    const candidate = path.resolve(projectRoot, name);
+
+    try {
+      const stats = await fs.stat(candidate);
+
+      if (stats.isFile()) {
+        found.push(candidate);
+      }
+    } catch {
+      // Missing candidate; the config file is optional.
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Loads and resolves the project shiso config.
+ *
+ * Absent file yields resolved defaults with a null sourcePath, keeping
+ * zero-config projects zero-config.
+ */
+export async function loadShisoConfig({ root = process.cwd() } = {}) {
+  const projectRoot = path.resolve(root);
+  const found = await findConfigFiles(projectRoot);
+
+  if (found.length > 1) {
+    throw new ShisoConfigLoadError(
+      `Multiple shiso config files found in "${projectRoot}": ${found.map(item => path.basename(item)).join(', ')}. Keep exactly one.`,
+      { code: 'MULTIPLE_CONFIGS', sourcePath: found[0] },
+    );
+  }
+
+  if (found.length === 0) {
+    return { config: resolveShisoConfig(), raw: {}, projectRoot, sourcePath: null, sourcePaths: [] };
+  }
+
+  const sourcePath = found[0];
+  let raw;
+
+  try {
+    if (!sourcePath.endsWith('.mjs')) {
+      // .ts and .js go through jiti, which transpiles TypeScript and handles
+      // ESM syntax in .js files regardless of the project's package type.
+      // No module or filesystem cache: nothing is written into (possibly
+      // missing) node_modules, and dev-server hot updates re-evaluate a fresh
+      // copy of the transpiled file.
+      const jiti = createJiti(import.meta.url, {
+        interopDefault: true,
+        moduleCache: false,
+        fsCache: false,
+      });
+      raw = await jiti.import(pathToFileURL(sourcePath).href, { default: true });
+    } else {
+      // Plain .mjs goes through Node's own loader; the unique cache-busting
+      // query defeats the permanent ESM module registry so edits are picked up.
+      importGeneration += 1;
+      raw = (await import(`${pathToFileURL(sourcePath).href}?v=${importGeneration}.${Date.now()}`))
+        .default;
+    }
+  } catch (error) {
+    throw new ShisoConfigLoadError(
+      `Shiso config "${sourcePath}" failed to load: ${error.message}`,
+      { cause: error, code: 'LOAD_FAILED', sourcePath },
+    );
+  }
+
+  if (!isPlainObject(raw)) {
+    throw new ShisoConfigLoadError(
+      `Shiso config "${sourcePath}" must default-export a plain object.`,
+      { code: 'INVALID_CONFIG', sourcePath },
+    );
+  }
+
+  const unknownKeys = Object.keys(raw).filter(key => !KNOWN_KEYS.includes(key));
+
+  if (unknownKeys.length > 0) {
+    throw new ShisoConfigLoadError(
+      `Shiso config "${sourcePath}" has unknown ${unknownKeys.length === 1 ? 'key' : 'keys'} ${unknownKeys.map(key => `"${key}"`).join(', ')}. Supported keys: ${KNOWN_KEYS.join(', ')}.`,
+      { code: 'UNKNOWN_OPTION', sourcePath },
+    );
+  }
+
+  return {
+    config: resolveShisoConfig(raw, sourcePath),
+    raw,
+    projectRoot,
+    sourcePath,
+    sourcePaths: [sourcePath],
+  };
+}