@umami/shiso 0.54.0 → 0.61.0

package/src/lib/search-index.generated.ts

@@ -0,0 +1,4 @@
+// Build-time alias target. Shiso replaces this module with the project's generated index.
+import type { SearchRecord } from '@/lib/search';
+
+export const SEARCH_INDEX: SearchRecord[] = [];

package/src/lib/search.ts

@@ -0,0 +1,100 @@
+/**
+ * Client-side search over the build-time index
+ * (see scripts/generate-search-index.mjs).
+ *
+ * Plain substring scoring, no dependencies: docs sites are small enough that
+ * scanning a few hundred sections per keystroke is cheap, and substring
+ * matches behave predictably for exact terms like config keys.
+ */
+
+export interface SearchRecord {
+  /** Base-relative route of the page. */
+  url: string;
+  /** Page title. */
+  page: string;
+  /** Section heading, absent for the page intro. */
+  heading?: string;
+  /** Heading anchor id, matching the rendered heading. */
+  id?: string;
+  /** Plain text of the section. */
+  text: string;
+}
+
+export interface SearchResult {
+  /** Route including the section anchor. */
+  url: string;
+  /** Page title. */
+  page: string;
+  /** Section heading, absent for the page intro. */
+  heading?: string;
+  /** Snippet of section text around the first match, when the text matched. */
+  snippet?: string;
+  /** Provider-specific relevance score. Use 0 when a provider does not expose one. */
+  score: number;
+}
+
+const SNIPPET_RADIUS = 60;
+
+function makeSnippet(text: string, index: number, length: number): string {
+  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 ? '…' : ''}`;
+}
+
+export function searchIndex(records: SearchRecord[], query: string, limit = 10): SearchResult[] {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+
+  if (!terms.length) {
+    return [];
+  }
+
+  const results: SearchResult[] = [];
+
+  for (const record of records) {
+    const page = record.page.toLowerCase();
+    const heading = (record.heading || '').toLowerCase();
+    const text = record.text.toLowerCase();
+
+    let score = 0;
+    let snippetAt = -1;
+    let snippetLength = 0;
+    let matched = true;
+
+    for (const term of terms) {
+      if (page.includes(term)) {
+        score += page === term ? 40 : 20;
+      } else if (heading.includes(term)) {
+        score += heading === term ? 30 : 15;
+      } else {
+        const index = text.indexOf(term);
+
+        if (index === -1) {
+          matched = false;
+          break;
+        }
+
+        score += 5;
+
+        if (snippetAt === -1) {
+          snippetAt = index;
+          snippetLength = term.length;
+        }
+      }
+    }
+
+    if (!matched || !score) {
+      continue;
+    }
+
+    results.push({
+      url: record.id ? `${record.url}#${record.id}` : record.url,
+      page: record.page,
+      heading: record.heading,
+      snippet: snippetAt >= 0 ? makeSnippet(record.text, snippetAt, snippetLength) : undefined,
+      score,
+    });
+  }
+
+  return results.sort((a, b) => b.score - a.score).slice(0, limit);
+}

package/src/lib/site-config.ts

@@ -0,0 +1,104 @@
+import rawConfig from 'virtual:shiso-docs-config';
+import { resolveDocFile } from '@/lib/content';
+import { assertDocsConfig, normalizeDocsConfig } from '@/lib/docs-config';
+import { stripBase, stripDocsPrefix } from '@/lib/paths';
+import { resolveSiteModel } from '@/lib/site-model';
+import type {
+  DocsConfig,
+  NormalizedDocsConfig,
+  NormalizedDocsPage,
+  RedirectRule,
+  SeoConfig,
+} from '@/lib/types';
+
+assertDocsConfig(rawConfig, 'docs.json');
+
+export const siteConfig: DocsConfig = rawConfig;
+
+export const docsConfig: NormalizedDocsConfig = normalizeDocsConfig(siteConfig, resolveDocFile);
+
+export const siteModel = resolveSiteModel(siteConfig, docsConfig);
+
+export const siteName = siteModel.name;
+
+/** Trailing-slash-insensitive route key for redirect matching. */
+function toRouteKey(routePath: string): string {
+  const trimmed = routePath.replace(/\/+$/, '');
+  return trimmed || '/';
+}
+
+/**
+ * Redirect rules with exact-match sources. Wildcard patterns are part of the
+ * standard but not implemented; they are skipped with a warning.
+ */
+export function getRedirects(): RedirectRule[] {
+  return (siteConfig.redirects || []).filter(rule => {
+    if (!rule?.source || !rule.destination) {
+      return false;
+    }
+
+    if (/[:*]/.test(rule.source)) {
+      console.warn(
+        `[shiso] Redirect source "${rule.source}" uses a wildcard pattern, which is not ` +
+          'implemented yet — it will be skipped.',
+      );
+      return false;
+    }
+
+    return true;
+  });
+}
+
+const redirectBySource = new Map(
+  getRedirects().map(rule => [toRouteKey(rule.source), rule.destination]),
+);
+
+/** Destination for a base-relative route covered by a redirect rule, if any. */
+export function matchRedirect(routePath: string): string | null {
+  return redirectBySource.get(toRouteKey(routePath)) || null;
+}
+
+export function getSeo(): SeoConfig {
+  const seo = siteConfig.seo || {};
+
+  return {
+    metatags: seo.metatags || {},
+    indexing: seo.indexing === 'all' ? 'all' : 'navigable',
+  };
+}
+
+/** True when the last-modified timestamp should show for a page. */
+export function showTimestamp(frontmatterValue: unknown): boolean {
+  if (typeof frontmatterValue === 'boolean') {
+    return frontmatterValue;
+  }
+
+  return siteModel.showTimestamp;
+}
+
+export function normalizeParamSlug(slug: string): string {
+  const cleaned = slug.replace(/^\/+|\/+$/g, '');
+
+  if (!cleaned) {
+    return 'index';
+  }
+
+  if (cleaned === 'index') {
+    return cleaned;
+  }
+
+  return cleaned.replace(/\/index$/, '') || 'index';
+}
+
+export function getPageByPathname(pathname: string): NormalizedDocsPage | null {
+  const slug = normalizeParamSlug(stripDocsPrefix(stripBase(pathname)));
+  return docsConfig.pageByLookupSlug[slug] || null;
+}
+
+export function getPageTitle(pageTitle?: string): string {
+  if (pageTitle && siteName) {
+    return `${pageTitle} – ${siteName}`;
+  }
+
+  return pageTitle || siteName || '';
+}

package/src/lib/site-model.ts

@@ -0,0 +1,221 @@
+import { toAbsoluteUrl, toHref } from '@/lib/paths';
+import { resolveSearchConfig } from '@/lib/search/config';
+import type {
+  ConfigLink,
+  ContextualOption,
+  ContextualOptionObject,
+  DocsConfig,
+  LinkTarget,
+  NormalizedDocsConfig,
+  NormalizedDocsPage,
+  NormalizedFooter,
+  NormalizedLink,
+  NormalizedNavbar,
+  ResolvedContextualOption,
+  SiteModel,
+  ThemeLabels,
+} from '@/lib/types';
+
+const SHISO_THEME_LABELS: ThemeLabels = {
+  menu: 'Menu',
+  documentationNavigation: 'Documentation navigation',
+  sections: 'Sections',
+  tableOfContents: 'On this page',
+  tableOfContentsNavigation: 'Table of contents',
+  searchTitle: 'Search',
+  searching: 'Searching...',
+  searchUnavailable: 'Search unavailable',
+  noResults: 'No results',
+  lastUpdated: 'Last updated on',
+  notFound: 'Page not found',
+  dismissBanner: 'Dismiss banner',
+  toggleTheme: 'Toggle theme',
+  moreOptions: 'More options',
+  copied: 'Copied',
+  expand: 'Expand',
+  collapse: 'Collapse',
+  copyPage: 'Copy page',
+  copyPageDescription: 'Copy this page as Markdown',
+  viewMarkdown: 'View as Markdown',
+  viewMarkdownDescription: 'Open this page as plain Markdown',
+  openInChatGPT: 'Open in ChatGPT',
+  openInClaude: 'Open in Claude',
+  openInPerplexity: 'Open in Perplexity',
+  askQuestionsAboutPage: 'Ask questions about this page',
+};
+
+function isInternalHref(href: string): boolean {
+  return /^(?:#|\/|\.\.?\/)/.test(href);
+}
+
+export function resolveLinkTarget(href: string, target?: LinkTarget): LinkTarget {
+  return target || (isInternalHref(href) ? '_self' : '_blank');
+}
+
+function normalizeLink(link: ConfigLink): NormalizedLink {
+  return {
+    href: link.href,
+    label: link.label?.trim() || undefined,
+    ariaLabel: link.ariaLabel?.trim() || undefined,
+    icon: link.icon?.trim() || undefined,
+    target: resolveLinkTarget(link.href, link.target),
+  };
+}
+
+function normalizeNavbar(config: DocsConfig['navbar']): NormalizedNavbar | null {
+  if (!config) {
+    return null;
+  }
+
+  const links = (config.links || []).filter(link => !!link?.href).map(normalizeLink);
+  const primary = config.primary?.href ? normalizeLink(config.primary) : undefined;
+
+  return links.length || primary ? { links, primary } : null;
+}
+
+function normalizeFooter(config: DocsConfig['footer']): NormalizedFooter | null {
+  const socials = (config?.socials || []).filter(link => !!link?.href).map(normalizeLink);
+  const links = (config?.links || [])
+    .filter(column => column?.items?.length)
+    .map(column => ({
+      ...column,
+      items: column.items.map(item => ({
+        ...item,
+        target: resolveLinkTarget(item.href, item.target),
+      })),
+    }));
+  const attribution = config?.attribution !== false;
+
+  return socials.length || links.length || attribution ? { socials, links, attribution } : null;
+}
+
+export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig): SiteModel {
+  const appearance = config.appearance || {};
+  const logo = config.logo
+    ? typeof config.logo === 'string'
+      ? { light: config.logo, dark: config.logo }
+      : {
+          light: config.logo.light || config.logo.dark,
+          dark: config.logo.dark || config.logo.light,
+          href: config.logo.href,
+          target: config.logo.href
+            ? resolveLinkTarget(config.logo.href, config.logo.target)
+            : undefined,
+        }
+    : null;
+
+  return {
+    name: config.name?.trim() || undefined,
+    logo,
+    navbar: normalizeNavbar(config.navbar),
+    footer: normalizeFooter(config.footer),
+    banner: config.banner?.content?.trim()
+      ? { content: config.banner.content.trim(), dismissible: config.banner.dismissible === true }
+      : null,
+    appearance: {
+      default:
+        appearance.default === 'light' || appearance.default === 'dark'
+          ? appearance.default
+          : 'system',
+      strict: appearance.strict === true,
+    },
+    styling: {
+      eyebrows: config.styling?.eyebrows === 'breadcrumbs' ? 'breadcrumbs' : 'section',
+    },
+    search: resolveSearchConfig(config.search),
+    contextualOptions: config.contextual?.options || [],
+    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',
+    labels: SHISO_THEME_LABELS,
+    docs,
+  };
+}
+
+function aiPrompt(mdUrl: string): string {
+  return `Read ${mdUrl} so I can ask questions about it.`;
+}
+
+export function resolveContextualOptions(
+  options: ContextualOption[],
+  page: NormalizedDocsPage,
+  labels: ThemeLabels = SHISO_THEME_LABELS,
+): ResolvedContextualOption[] {
+  const mdHref = `${toHref(page.url)}.md`;
+  const absolutePageUrl = toAbsoluteUrl(page.url);
+  const mdUrl = absolutePageUrl ? `${absolutePageUrl}.md` : undefined;
+  const resolved: ResolvedContextualOption[] = [];
+
+  for (const option of options) {
+    if (typeof option !== 'string') {
+      const custom = option as ContextualOptionObject;
+      const href = custom.href.replaceAll('$path', page.url).replaceAll('$page', mdUrl || mdHref);
+
+      resolved.push({
+        key: custom.title,
+        title: custom.title,
+        description: custom.description,
+        icon: custom.icon,
+        action: 'link',
+        href,
+        target: resolveLinkTarget(href, custom.target),
+      });
+      continue;
+    }
+
+    if (option === 'copy') {
+      resolved.push({
+        key: option,
+        title: labels.copyPage,
+        description: labels.copyPageDescription,
+        icon: 'copy',
+        action: 'copy',
+        href: mdHref,
+        target: '_self',
+      });
+    } else if (option === 'view') {
+      resolved.push({
+        key: option,
+        title: labels.viewMarkdown,
+        description: labels.viewMarkdownDescription,
+        icon: 'external-link',
+        action: 'link',
+        href: mdHref,
+        target: '_blank',
+      });
+    } else if (mdUrl && option === 'chatgpt') {
+      resolved.push({
+        key: option,
+        title: labels.openInChatGPT,
+        description: labels.askQuestionsAboutPage,
+        icon: 'external-link',
+        action: 'link',
+        href: `https://chatgpt.com/?q=${encodeURIComponent(aiPrompt(mdUrl))}`,
+        target: '_blank',
+      });
+    } else if (mdUrl && option === 'claude') {
+      resolved.push({
+        key: option,
+        title: labels.openInClaude,
+        description: labels.askQuestionsAboutPage,
+        icon: 'external-link',
+        action: 'link',
+        href: `https://claude.ai/new?q=${encodeURIComponent(aiPrompt(mdUrl))}`,
+        target: '_blank',
+      });
+    } else if (mdUrl && option === 'perplexity') {
+      resolved.push({
+        key: option,
+        title: labels.openInPerplexity,
+        description: labels.askQuestionsAboutPage,
+        icon: 'external-link',
+        action: 'link',
+        href: `https://www.perplexity.ai/search?q=${encodeURIComponent(aiPrompt(mdUrl))}`,
+        target: '_blank',
+      });
+    }
+  }
+
+  return resolved;
+}

package/src/lib/slug.ts

@@ -0,0 +1,38 @@
+import GithubSlugger, { slug as slugifyOnce } from 'github-slugger';
+
+/**
+ * The single slug algorithm in the repo.
+ *
+ * Heading anchors are produced in two independent places — `remarkToc` (which
+ * builds the on-page table of contents) and `rehype-slug` (which sets the `id`
+ * on the rendered heading). Both must agree or every TOC link breaks, so both
+ * go through github-slugger here rather than reimplementing it.
+ */
+
+/**
+ * Creates a stateful slugger. Call `.slug(text)` once per heading in document
+ * order; repeated headings get `-1`, `-2`, ... suffixes exactly as rehype-slug
+ * does, because it is the same implementation.
+ */
+export function createSlugger(): GithubSlugger {
+  return new GithubSlugger();
+}
+
+/**
+ * Stateless slugify for one-off ids that do not need de-duplication.
+ *
+ * github-slugger does not trim, so padded input would otherwise produce leading
+ * and trailing dashes. Heading text is trimmed upstream by `headingText`; this
+ * makes the guarantee hold for every other caller too.
+ */
+export function slugify(value: string): string {
+  return slugifyOnce(value.trim());
+}
+
+/**
+ * Slugifies a label into a config-level identifier (tab ids, section ids).
+ * Falls back when the value contains no slug-able characters.
+ */
+export function slugifyId(value: string, fallback: string): string {
+  return slugify(value) || fallback;
+}