@umami/shiso 1.3.0 → 1.5.0

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/declarations.d.ts

@@ -7,3 +7,10 @@ declare module 'virtual:shiso-docs-config' {
   const config: DocsConfig;
   export default config;
 }
+
+declare module 'virtual:shiso-config' {
+  import type { ResolvedShisoConfig } from '@/lib/types';
+
+  const config: ResolvedShisoConfig;
+  export default config;
+}

package/src/entry-server.tsx

@@ -12,6 +12,7 @@ import {
   getRedirects,
   getSeo,
   siteName,
+  standalonePages,
 } from '@/lib/site-config';
 
 export interface RenderResult {
@@ -28,7 +29,7 @@ export interface SitemapEntry {
 
 /** Base-relative routes for every scope. The prerenderer prepends the deploy base itself. */
 export function getRoutes(): string[] {
-  return docsSite.pages.map(page => page.url);
+  return [...docsSite.pages.map(page => page.url), ...standalonePages.map(page => page.path)];
 }
 
 /** Redirect rules with exact-match sources, for static redirect pages. */
@@ -41,12 +42,15 @@ export { getRedirects };
  * "/content/docs/index.mdx", resolved against the project root.
  */
 export function getMarkdownPages(): { route: string; filePath: string }[] {
-  return docsSite.pages.map(page => ({ route: page.url, filePath: page.filePath }));
+  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.
  */
 export function getSitemapEntries(): SitemapEntry[] {
@@ -71,6 +75,19 @@ export function getSitemapEntries(): SitemapEntry[] {
     }
   }
 
+  // Standalone pages are always navigable; only frontmatter noindex opts out.
+  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;
 }
 

package/src/lib/content.ts

@@ -1,5 +1,5 @@
 import { LAST_MODIFIED } from '@/generated/last-modified';
-import { CONTENT_DIR } from '@/lib/paths';
+import { CONTENT_DIR, PAGES_DIR } from '@/lib/paths';
 import type { DocModule } from '@/lib/types';
 
 /**
@@ -12,7 +12,7 @@ import type { DocModule } from '@/lib/types';
  * without Suspense, at the cost of bundling all pages together.
  *
  * The glob pattern must be a literal for Vite to statically analyze it, so it
- * covers all of `content/` and the configured `$shiso.contentDir` is applied at
+ * covers all of `content/` and the configured shiso.config `contentDir` is applied at
  * lookup time instead. That also lets later versioned/localized content roots
  * (`content/v2`, `content/es`) work without touching this glob.
  */
@@ -30,6 +30,14 @@ export function resolveDocFile(fileSlug: string, contentDir = CONTENT_DIR): stri
   return candidates.find(candidate => candidate in docModules);
 }
 
+/**
+ * Resolves a standalone page slug (docs.json `pages[].page`) to a module key
+ * under the fixed content/pages root.
+ */
+export function resolvePageFile(fileSlug: string): string | undefined {
+  return resolveDocFile(fileSlug, PAGES_DIR);
+}
+
 export function getDocModule(filePath: string): DocModule | undefined {
   return docModules[filePath];
 }

package/src/lib/head.ts

@@ -8,6 +8,7 @@ import {
   getPageTitle,
   getScopeByPathname,
   getSeo,
+  getStandalonePage,
   showTimestamp,
   siteConfig,
   siteModel,
@@ -49,18 +50,25 @@ function escapeJsonLd(value: string): string {
 
 export function buildHead(pathname: string): HeadTag[] {
   const page = getPageByPathname(pathname);
-  const doc = page ? getDocModule(page.filePath) : undefined;
+  const standalone = page ? null : getStandalonePage(pathname);
+  const filePath = page?.filePath || standalone?.filePath;
+  const doc = filePath ? getDocModule(filePath) : undefined;
   const frontmatter = doc?.frontmatter;
 
   const seo = getSeo();
-  const pageTitle = frontmatter?.title || page?.label;
+  const pageTitle = frontmatter?.title || standalone?.title || page?.label;
   const title = getPageTitle(pageTitle);
   const description = frontmatter?.description || siteConfig.description;
-  const canonical = page ? toAbsoluteUrl(page.url) : undefined;
+  const canonical = page
+    ? toAbsoluteUrl(page.url)
+    : standalone
+      ? toAbsoluteUrl(standalone.path)
+      : undefined;
   // `seo.indexing: "all"` opts hidden pages (and hidden versions/languages)
   // into the index; explicit per-page `noindex` frontmatter always wins.
   const hidden = !!page && (!!page.hidden || !!getScopeByPathname(pathname).hidden);
-  const noindex = !page || frontmatter?.noindex === true || (hidden && seo.indexing !== 'all');
+  const noindex =
+    (!page && !standalone) || frontmatter?.noindex === true || (hidden && seo.indexing !== 'all');
 
   const tags: HeadTag[] = [{ tag: 'title', children: title }];
 
@@ -76,9 +84,9 @@ export function buildHead(pathname: string): HeadTag[] {
     tags.push({ tag: 'meta', attrs: { name: 'robots', content: 'noindex' } });
   }
 
-  // Open Graph
+  // Open Graph. Standalone pages (home, landing) are websites, not articles.
   tags.push(
-    { tag: 'meta', attrs: { property: 'og:type', content: 'article' } },
+    { tag: 'meta', attrs: { property: 'og:type', content: standalone ? 'website' : 'article' } },
     { tag: 'meta', attrs: { property: 'og:title', content: title } },
   );
 
@@ -106,7 +114,7 @@ export function buildHead(pathname: string): HeadTag[] {
 
   // Last-modified time, when the timestamp feature is on for this page.
   const lastModified =
-    page && showTimestamp(frontmatter?.timestamp) ? getLastModified(page.filePath) : undefined;
+    filePath && showTimestamp(frontmatter?.timestamp) ? getLastModified(filePath) : undefined;
 
   if (lastModified) {
     tags.push({ tag: 'meta', attrs: { property: 'article:modified_time', content: lastModified } });

package/src/lib/locale.ts

@@ -18,7 +18,7 @@ export function isValidLocale(value: string | undefined): value is string {
 
 /**
  * Locale for a page: its scope's language code when valid, then the
- * site-wide `$shiso.locale`, then en-US.
+ * site-wide shiso.config `locale`, then en-US.
  */
 export function resolveLocale(language: string | undefined, fallback: string | undefined): string {
   if (isValidLocale(language)) {

package/src/lib/paths.ts

@@ -1,5 +1,4 @@
-import rawConfig from 'virtual:shiso-docs-config';
-import type { ShisoOptions } from '@/lib/types';
+import shiso from 'virtual:shiso-config';
 
 /**
  * All URL construction goes through this module.
@@ -14,10 +13,11 @@ import type { ShisoOptions } from '@/lib/types';
  * DOCS_PREFIX but not BASE_URL. React Router's `basename` adds BASE_URL, so
  * only code that bypasses the router (prerender output paths, canonical URLs,
  * raw <a href>) needs `toHref`.
+ *
+ * Values from `virtual:shiso-config` arrive with defaults applied and already
+ * normalized by scripts/load-shiso-config.mjs.
  */
 
-const shiso = ((rawConfig as { $shiso?: ShisoOptions }).$shiso || {}) as ShisoOptions;
-
 /** Strips trailing slashes; "/" and "" both normalize to "". */
 function normalizePrefix(value: string): string {
   const trimmed = value.trim().replace(/\/+$/, '');
@@ -31,13 +31,17 @@ function normalizePrefix(value: string): string {
 
 export const BASE_URL = normalizePrefix(import.meta.env?.BASE_URL || '/');
 
-export const DOCS_PREFIX = normalizePrefix(shiso.docsPrefix ?? '/docs');
+export const DOCS_PREFIX = shiso.docsPrefix;
 
 /** Content directory, relative to the project root, without leading/trailing slashes. */
-export const CONTENT_DIR = (shiso.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
+export const CONTENT_DIR = shiso.contentDir;
+
+/** Fixed root for standalone (non-docs) page files. Not configurable, so page
+ * slugs can never collide with the docs content tree. */
+export const PAGES_DIR = 'content/pages';
 
 /** Absolute origin used for canonical and og:url tags. Undefined when unconfigured. */
-export const SITE_URL = shiso.siteUrl?.replace(/\/+$/, '') || undefined;
+export const SITE_URL = shiso.siteUrl;
 
 /** Joins path segments with exactly one slash between them. */
 export function joinPath(...parts: (string | undefined)[]): string {

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/site-config.ts

@@ -1,5 +1,6 @@
+import shisoConfig from 'virtual:shiso-config';
 import rawConfig from 'virtual:shiso-docs-config';
-import { resolveDocFile } from '@/lib/content';
+import { resolveDocFile, resolvePageFile } from '@/lib/content';
 import {
   assertDocsConfig,
   getDefaultScope,
@@ -8,8 +9,9 @@ import {
   normalizeDocsSite,
 } from '@/lib/docs-config';
 import { getTextDirection, resolveLocale } from '@/lib/locale';
-import { stripBase } from '@/lib/paths';
+import { DOCS_PREFIX, stripBase } from '@/lib/paths';
 import { resolveSiteModel } from '@/lib/site-model';
+import { getStandalonePageByPathname, normalizeStandalonePages } from '@/lib/standalone-pages';
 import type {
   DocsConfig,
   DocsScope,
@@ -18,6 +20,7 @@ import type {
   NormalizedDocsSite,
   RedirectRule,
   SeoConfig,
+  StandalonePage,
 } from '@/lib/types';
 
 assertDocsConfig(rawConfig, 'docs.json');
@@ -33,7 +36,22 @@ export const docsConfig: NormalizedDocsConfig = getDefaultScope(docsSite).docs;
 /** Landing page of the default scope: the site-wide "docs home" URL. */
 export const docsHomeUrl = getDefaultScope(docsSite).firstPageUrl;
 
-export const siteModel = resolveSiteModel(siteConfig, docsConfig);
+export const siteModel = resolveSiteModel(siteConfig, docsConfig, shisoConfig);
+
+/** Standalone pages declared with the top-level `pages` key, e.g. a home page. */
+export const standalonePages: StandalonePage[] = normalizeStandalonePages(
+  siteConfig,
+  resolvePageFile,
+  docsSite,
+  { docsPrefix: DOCS_PREFIX },
+);
+
+/** True when a standalone page owns "/", replacing the root docs redirect. */
+export const hasRootStandalonePage = standalonePages.some(page => page.path === '/');
+
+export function getStandalonePage(pathname: string): StandalonePage | null {
+  return getStandalonePageByPathname(standalonePages, stripBase(pathname));
+}
 
 /** Scope that owns the current pathname; the default scope for unknown paths. */
 export function getScopeByPathname(pathname: string): DocsScope {

package/src/lib/site-model.ts

@@ -12,6 +12,7 @@ import type {
   NormalizedLink,
   NormalizedNavbar,
   ResolvedContextualOption,
+  ResolvedShisoConfig,
   SiteModel,
   ThemeLabels,
 } from '@/lib/types';
@@ -90,7 +91,11 @@ function normalizeFooter(config: DocsConfig['footer']): NormalizedFooter | null
   return socials.length || links.length || attribution ? { socials, links, attribution } : null;
 }
 
-export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig): SiteModel {
+export function resolveSiteModel(
+  config: DocsConfig,
+  docs: NormalizedDocsConfig,
+  shiso?: ResolvedShisoConfig,
+): SiteModel {
   const appearance = config.appearance || {};
   const logo = config.logo
     ? typeof config.logo === 'string'
@@ -128,7 +133,7 @@ export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig)
     error404: { ...config.errors?.['404'], redirect: config.errors?.['404']?.redirect !== false },
     showTimestamp: config.metadata?.timestamp === true,
     drilldown: config.interaction?.drilldown,
-    locale: config.$shiso?.locale?.trim() || 'en-US',
+    locale: shiso?.locale || 'en-US',
     labels: SHISO_THEME_LABELS,
     docs,
   };