@umami/shiso 0.55.0 → 0.61.0

package/src/lib/head.ts

@@ -0,0 +1,220 @@
+import { useEffect, useRef } from 'react';
+import { getDocModule, getLastModified } from '@/lib/content';
+import { SITE_URL, toAbsoluteUrl } from '@/lib/paths';
+import {
+  getPageByPathname,
+  getPageTitle,
+  getSeo,
+  showTimestamp,
+  siteConfig,
+  siteName,
+} from '@/lib/site-config';
+
+/**
+ * The document head is a pure function of the route.
+ *
+ * Every input — docs.json and the eagerly-globbed frontmatter — is available
+ * synchronously on both the server and the client, so there is no need for a
+ * head manager, a context provider, or a data router. `renderHeadToString` and
+ * `applyHead` consume the exact same `buildHead` output, which makes the
+ * prerendered markup and post-navigation DOM identical by construction.
+ */
+
+export interface HeadTag {
+  tag: 'title' | 'meta' | 'link' | 'script';
+  attrs?: Record<string, string>;
+  children?: string;
+}
+
+/** Marks tags this module owns, so client navigation can replace exactly its own. */
+export const HEAD_MARKER = 'data-shiso-head';
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/** JSON-LD is script content, not attribute content: only `<` and `&` need care. */
+function escapeJsonLd(value: string): string {
+  return value.replace(/</g, '\\u003c');
+}
+
+export function buildHead(pathname: string): HeadTag[] {
+  const page = getPageByPathname(pathname);
+  const doc = page ? getDocModule(page.filePath) : undefined;
+  const frontmatter = doc?.frontmatter;
+
+  const seo = getSeo();
+  const pageTitle = frontmatter?.title || page?.label;
+  const title = getPageTitle(pageTitle);
+  const description = frontmatter?.description || siteConfig.description;
+  const canonical = page ? toAbsoluteUrl(page.url) : undefined;
+  // `seo.indexing: "all"` opts hidden pages into the index; explicit
+  // per-page `noindex` frontmatter always wins.
+  const noindex =
+    !page || frontmatter?.noindex === true || (!!page.hidden && seo.indexing !== 'all');
+
+  const tags: HeadTag[] = [{ tag: 'title', children: title }];
+
+  if (description) {
+    tags.push({ tag: 'meta', attrs: { name: 'description', content: description } });
+  }
+
+  if (canonical) {
+    tags.push({ tag: 'link', attrs: { rel: 'canonical', href: canonical } });
+  }
+
+  if (noindex) {
+    tags.push({ tag: 'meta', attrs: { name: 'robots', content: 'noindex' } });
+  }
+
+  // Open Graph
+  tags.push(
+    { tag: 'meta', attrs: { property: 'og:type', content: 'article' } },
+    { tag: 'meta', attrs: { property: 'og:title', content: title } },
+  );
+
+  if (siteName) {
+    tags.push({ tag: 'meta', attrs: { property: 'og:site_name', content: siteName } });
+  }
+
+  if (description) {
+    tags.push({ tag: 'meta', attrs: { property: 'og:description', content: description } });
+  }
+
+  if (canonical) {
+    tags.push({ tag: 'meta', attrs: { property: 'og:url', content: canonical } });
+  }
+
+  // Twitter
+  tags.push(
+    { tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } },
+    { tag: 'meta', attrs: { name: 'twitter:title', content: title } },
+  );
+
+  if (description) {
+    tags.push({ tag: 'meta', attrs: { name: 'twitter:description', content: description } });
+  }
+
+  // Last-modified time, when the timestamp feature is on for this page.
+  const lastModified =
+    page && showTimestamp(frontmatter?.timestamp) ? getLastModified(page.filePath) : undefined;
+
+  if (lastModified) {
+    tags.push({ tag: 'meta', attrs: { property: 'article:modified_time', content: lastModified } });
+  }
+
+  // Site-wide meta tags from `seo.metatags`. Emitted last so authors can see
+  // them win over the generated defaults in devtools; `og:*`-style keys are
+  // property attributes, the rest are name attributes.
+  for (const [key, content] of Object.entries(seo.metatags || {})) {
+    if (key === 'title' || typeof content !== 'string') {
+      continue;
+    }
+
+    const attribute = /^(og|article|fb|profile|book|music|video):/.test(key) ? 'property' : 'name';
+    tags.push({ tag: 'meta', attrs: { [attribute]: key, content } });
+  }
+
+  // Structured data. Only emitted with an absolute origin, since both
+  // TechArticle.url and BreadcrumbList items require resolvable URLs.
+  if (page && canonical && SITE_URL) {
+    const breadcrumbs = [
+      siteName ? { name: siteName, url: toAbsoluteUrl('/') } : null,
+      page.tabLabel && page.section !== page.tabLabel ? { name: page.tabLabel } : null,
+      page.section ? { name: page.section } : null,
+      { name: page.label, url: canonical },
+    ].filter((item): item is { name: string; url?: string } => !!item);
+
+    tags.push({
+      tag: 'script',
+      attrs: { type: 'application/ld+json' },
+      children: JSON.stringify([
+        {
+          '@context': 'https://schema.org',
+          '@type': 'TechArticle',
+          headline: pageTitle || page.label,
+          description,
+          url: canonical,
+          ...(siteName ? { isPartOf: { '@type': 'WebSite', name: siteName, url: SITE_URL } } : {}),
+        },
+        {
+          '@context': 'https://schema.org',
+          '@type': 'BreadcrumbList',
+          itemListElement: breadcrumbs.map((item, index) => ({
+            '@type': 'ListItem',
+            position: index + 1,
+            name: item.name,
+            ...(item.url ? { item: item.url } : {}),
+          })),
+        },
+      ]),
+    });
+  }
+
+  return tags;
+}
+
+export function renderHeadToString(tags: HeadTag[]): string {
+  return tags
+    .map(({ tag, attrs, children }) => {
+      const attributes = Object.entries(attrs || {})
+        .map(([key, value]) => ` ${key}="${escapeHtml(value)}"`)
+        .join('');
+
+      if (tag === 'meta' || tag === 'link') {
+        return `<${tag}${attributes} ${HEAD_MARKER} />`;
+      }
+
+      const content = tag === 'script' ? escapeJsonLd(children || '') : escapeHtml(children || '');
+
+      return `<${tag}${attributes} ${HEAD_MARKER}>${content}</${tag}>`;
+    })
+    .join('\n    ');
+}
+
+export function applyHead(tags: HeadTag[]) {
+  const { head } = document;
+
+  head.querySelectorAll(`[${HEAD_MARKER}]`).forEach(node => {
+    node.remove();
+  });
+
+  for (const { tag, attrs, children } of tags) {
+    const element = document.createElement(tag);
+
+    for (const [key, value] of Object.entries(attrs || {})) {
+      element.setAttribute(key, value);
+    }
+
+    if (children !== undefined) {
+      element.textContent = children;
+    }
+
+    element.setAttribute(HEAD_MARKER, '');
+    head.append(element);
+  }
+}
+
+/**
+ * Applies the head for the current route on client navigation.
+ *
+ * The first render after hydration is skipped: the prerendered head is already
+ * correct, and rewriting it would tear down and recreate every tag on load.
+ */
+export function useHead(pathname: string) {
+  const hydratedPath = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (hydratedPath.current === null) {
+      hydratedPath.current = pathname;
+      return;
+    }
+
+    applyHead(buildHead(pathname));
+  }, [pathname]);
+}

package/src/lib/icon-registry.generated.ts

@@ -0,0 +1,4 @@
+// Build-time alias target. Shiso replaces this module with the project's generated registry.
+import type { IconComponent } from '@/lib/icons';
+
+export const ICON_REGISTRY: Record<string, IconComponent> = {};

package/src/lib/icons.ts

@@ -0,0 +1,29 @@
+import type { ComponentType, SVGProps } from 'react';
+import { ICON_REGISTRY } from '@/lib/icon-registry.generated';
+
+export type IconComponent = ComponentType<SVGProps<SVGSVGElement> & { size?: number | string }>;
+
+/** `circle-check`, `circle_check`, `CircleCheck` all resolve to the same icon. */
+export function normalizeIconName(name: string): string {
+  return name
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Looks up an author-supplied icon name. The registry is generated at build time from
+ * the names found in content, so an icon only resolves after it appears in a source file.
+ */
+export function getIcon(name: string): IconComponent | undefined {
+  const icon = ICON_REGISTRY[normalizeIconName(name)];
+
+  if (!icon && import.meta.env?.DEV) {
+    console.warn(`Unknown icon "${name}". Check the name against the lucide icon set.`);
+  }
+
+  return icon;
+}

package/src/lib/inline-markdown.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Renders the small markdown subset allowed in config strings (banner content,
+ * error page descriptions): links, bold, italic, and inline code. Custom
+ * components are deliberately not supported — these strings come from
+ * docs.json, not MDX.
+ */
+
+interface InlinePattern {
+  regex: RegExp;
+  render: (match: RegExpExecArray, key: number) => ReactNode;
+}
+
+const PATTERNS: InlinePattern[] = [
+  {
+    // [label](https://example.com)
+    regex: /\[([^\]]+)\]\(([^)\s]+)\)/,
+    render: (match, key) => {
+      const external = /^https?:\/\//.test(match[2]);
+
+      return (
+        <a
+          key={key}
+          href={match[2]}
+          target={external ? '_blank' : undefined}
+          rel={external ? 'noreferrer' : undefined}
+        >
+          {renderInlineMarkdown(match[1])}
+        </a>
+      );
+    },
+  },
+  {
+    // **bold**
+    regex: /\*\*([^*]+)\*\*/,
+    render: (match, key) => <strong key={key}>{renderInlineMarkdown(match[1])}</strong>,
+  },
+  {
+    // *italic* (single asterisk, not part of **)
+    regex: /(?<!\*)\*([^*]+)\*(?!\*)/,
+    render: (match, key) => <em key={key}>{renderInlineMarkdown(match[1])}</em>,
+  },
+  {
+    // _italic_
+    regex: /_([^_]+)_/,
+    render: (match, key) => <em key={key}>{renderInlineMarkdown(match[1])}</em>,
+  },
+  {
+    // `code` — contents render verbatim
+    regex: /`([^`]+)`/,
+    render: (match, key) => <code key={key}>{match[1]}</code>,
+  },
+];
+
+export function renderInlineMarkdown(text: string): ReactNode[] {
+  const nodes: ReactNode[] = [];
+  let remaining = text;
+  let key = 0;
+
+  while (remaining) {
+    let earliest: { index: number; match: RegExpExecArray; pattern: InlinePattern } | null = null;
+
+    for (const pattern of PATTERNS) {
+      const match = pattern.regex.exec(remaining);
+
+      if (match && (!earliest || match.index < earliest.index)) {
+        earliest = { index: match.index, match, pattern };
+      }
+    }
+
+    if (!earliest) {
+      nodes.push(remaining);
+      break;
+    }
+
+    if (earliest.index > 0) {
+      nodes.push(remaining.slice(0, earliest.index));
+    }
+
+    nodes.push(earliest.pattern.render(earliest.match, key++));
+    remaining = remaining.slice(earliest.index + earliest.match[0].length);
+  }
+
+  return nodes;
+}

package/src/lib/mdast.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal mdast helpers shared by the remark plugins and the search extractor.
+ *
+ * These are deliberately structural rather than typed against `@types/mdast`:
+ * the trees we walk contain MDX-specific nodes (`mdxjsEsm`, `mdxJsxFlowElement`)
+ * and we only ever read `type`, `depth`, `value`, and `children`.
+ */
+
+export interface MdNode {
+  type?: string;
+  depth?: number;
+  value?: string;
+  lang?: string;
+  meta?: string;
+  children?: MdNode[];
+  data?: Record<string, unknown>;
+  /**
+   * The walker is also pointed at hast trees (where nodes carry `tagName` and
+   * `properties`), so callers can read node-kind-specific fields without a cast.
+   */
+  [key: string]: unknown;
+}
+
+/** Depth-first pre-order walk, visiting the node itself first. */
+export function walkTree(node: MdNode | undefined, visitor: (node: MdNode) => void) {
+  if (!node || typeof node !== 'object') {
+    return;
+  }
+
+  visitor(node);
+  node.children?.forEach(child => {
+    walkTree(child, visitor);
+  });
+}
+
+/**
+ * Concatenates the text content of a node. JSX elements contribute their text
+ * children (so `<Tooltip>API key</Tooltip>` reads as "API key"), which is what
+ * both heading anchors and the search index want.
+ */
+export function toText(node: MdNode | undefined): string {
+  if (!node) {
+    return '';
+  }
+
+  if (typeof node.value === 'string') {
+    return node.value;
+  }
+
+  return (node.children || []).map(toText).join('');
+}
+
+/** Text of a heading node, trimmed. */
+export function headingText(node: MdNode): string {
+  return toText(node).trim();
+}

package/src/lib/paths.ts

@@ -0,0 +1,86 @@
+import rawConfig from 'virtual:shiso-docs-config';
+import type { ShisoOptions } from '@/lib/types';
+
+/**
+ * All URL construction goes through this module.
+ *
+ * Two separate prefixes are involved and they are easy to confuse:
+ * - BASE_URL is Vite's `base` — where the whole site is mounted on the host
+ *   (e.g. "/my-docs" when deployed to a subpath). Baked in at build time.
+ * - DOCS_PREFIX is where docs pages live *within* the site (default "/docs").
+ *   Set "" to serve docs at the site root.
+ *
+ * Routes stored in the normalized config are base-relative: they include
+ * 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`.
+ */
+
+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(/\/+$/, '');
+
+  if (!trimmed || trimmed === '/') {
+    return '';
+  }
+
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+export const BASE_URL = normalizePrefix(import.meta.env?.BASE_URL || '/');
+
+export const DOCS_PREFIX = normalizePrefix(shiso.docsPrefix ?? '/docs');
+
+/** Content directory, relative to the project root, without leading/trailing slashes. */
+export const CONTENT_DIR = (shiso.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
+
+/** Absolute origin used for canonical and og:url tags. Undefined when unconfigured. */
+export const SITE_URL = shiso.siteUrl?.replace(/\/+$/, '') || undefined;
+
+/** Joins path segments with exactly one slash between them. */
+export function joinPath(...parts: (string | undefined)[]): string {
+  const joined = parts
+    .filter((part): part is string => !!part)
+    .join('/')
+    .replace(/\/{2,}/g, '/');
+
+  return joined.startsWith('/') ? joined : `/${joined}`;
+}
+
+/** Converts a base-relative route to a host-absolute href (prepends BASE_URL). */
+export function toHref(routePath: string): string {
+  if (isExternalHref(routePath)) {
+    return routePath;
+  }
+
+  return joinPath(BASE_URL, routePath);
+}
+
+/** Converts a base-relative route to a fully qualified URL, when SITE_URL is set. */
+export function toAbsoluteUrl(routePath: string): string | undefined {
+  return SITE_URL ? `${SITE_URL}${toHref(routePath)}` : undefined;
+}
+
+/** Removes BASE_URL from an incoming pathname, yielding a base-relative route. */
+export function stripBase(pathname: string): string {
+  if (BASE_URL && pathname.startsWith(BASE_URL)) {
+    return pathname.slice(BASE_URL.length) || '/';
+  }
+
+  return pathname;
+}
+
+/** Removes DOCS_PREFIX from a base-relative route, yielding a bare page slug path. */
+export function stripDocsPrefix(routePath: string): string {
+  if (DOCS_PREFIX && routePath.startsWith(DOCS_PREFIX)) {
+    return routePath.slice(DOCS_PREFIX.length);
+  }
+
+  return routePath;
+}
+
+export function isExternalHref(href: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');
+}

package/src/lib/remark-toc.ts

@@ -0,0 +1,71 @@
+/**
+ * Remark plugin that collects headings from the document and injects
+ * `export const toc = [{ name, id, size }, ...]` into the compiled MDX module.
+ *
+ * Anchor ids come from `src/lib/slug.ts`, the same github-slugger instance
+ * `rehype-slug` uses, so TOC links always match the rendered heading ids.
+ */
+import { valueToEstree } from 'estree-util-value-to-estree';
+// Relative imports: this module is also loaded by vite.config.ts, which esbuild
+// bundles without applying the "@/" resolve alias.
+import { headingText, type MdNode, walkTree } from './mdast.ts';
+import { createSlugger } from './slug.ts';
+import type { TocEntry } from './types.ts';
+
+function tocExportNode(toc: TocEntry[]): MdNode {
+  return {
+    type: 'mdxjsEsm',
+    value: '',
+    data: {
+      estree: {
+        type: 'Program',
+        sourceType: 'module',
+        body: [
+          {
+            type: 'ExportNamedDeclaration',
+            specifiers: [],
+            declaration: {
+              type: 'VariableDeclaration',
+              kind: 'const',
+              declarations: [
+                {
+                  type: 'VariableDeclarator',
+                  id: { type: 'Identifier', name: 'toc' },
+                  init: valueToEstree(toc),
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  };
+}
+
+/** Extracts the heading outline from an mdast tree. Shared with the search indexer. */
+export function collectToc(tree: MdNode): TocEntry[] {
+  const toc: TocEntry[] = [];
+  const slugger = createSlugger();
+
+  walkTree(tree, node => {
+    if (node.type !== 'heading' || typeof node.depth !== 'number') {
+      return;
+    }
+
+    const name = headingText(node);
+
+    if (!name) {
+      return;
+    }
+
+    toc.push({ name, id: slugger.slug(name), size: node.depth });
+  });
+
+  return toc;
+}
+
+export function remarkToc() {
+  return (tree: MdNode) => {
+    tree.children?.unshift(tocExportNode(collectToc(tree)));
+  };
+}

package/src/lib/search/config.ts

@@ -0,0 +1,43 @@
+import type { SearchConfig } from '@/lib/types';
+
+export const DEFAULT_SEARCH_PROMPT = 'Search...';
+export const DEFAULT_SEARCH_PROVIDER = 'local';
+export const DEFAULT_SEARCH_SHORTCUT = 'k';
+export const DEFAULT_SEARCH_SHORTCUT_LABEL = 'Ctrl K';
+
+export interface ResolvedSearchConfig {
+  enabled: boolean;
+  prompt: string;
+  provider: string;
+  options: Record<string, unknown>;
+  shortcut: string | false;
+  shortcutLabel: string;
+}
+
+/** Normalizes docs.json search settings for both the UI and provider loader. */
+export function resolveSearchConfig(
+  config: false | SearchConfig | undefined,
+): ResolvedSearchConfig {
+  if (config === false) {
+    return {
+      enabled: false,
+      prompt: DEFAULT_SEARCH_PROMPT,
+      provider: DEFAULT_SEARCH_PROVIDER,
+      options: {},
+      shortcut: false,
+      shortcutLabel: DEFAULT_SEARCH_SHORTCUT_LABEL,
+    };
+  }
+
+  return {
+    enabled: true,
+    prompt: config?.prompt?.trim() || DEFAULT_SEARCH_PROMPT,
+    provider: config?.provider?.trim().toLowerCase() || DEFAULT_SEARCH_PROVIDER,
+    options: config?.options || {},
+    shortcut:
+      config?.shortcut === false
+        ? false
+        : config?.shortcut?.trim().toLowerCase() || DEFAULT_SEARCH_SHORTCUT,
+    shortcutLabel: config?.shortcutLabel?.trim() || DEFAULT_SEARCH_SHORTCUT_LABEL,
+  };
+}

package/src/lib/search/provider.ts

@@ -0,0 +1,80 @@
+import type { SearchResult } from '@/lib/search';
+
+export interface SearchProvider {
+  search(query: string, limit?: number): Promise<SearchResult[]>;
+}
+
+export type SearchProviderFactory = (
+  options: Record<string, unknown>,
+) => SearchProvider | Promise<SearchProvider>;
+
+export interface ResolvedSearchProvider {
+  provider: SearchProvider;
+  providerId: string;
+  fellBack: boolean;
+}
+
+const factories = new Map<string, SearchProviderFactory>();
+
+function normalizeProviderId(id: string): string {
+  return id.trim().toLowerCase();
+}
+
+/**
+ * Registers a runtime search provider. Call this before rendering the app.
+ * The returned cleanup function only removes this exact registration.
+ */
+export function registerSearchProvider(id: string, factory: SearchProviderFactory): () => void {
+  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.',
+    );
+  }
+
+  factories.set(providerId, factory);
+
+  return () => {
+    if (factories.get(providerId) === factory) {
+      factories.delete(providerId);
+    }
+  };
+}
+
+async function createLocalProvider(options: Record<string, unknown>): Promise<SearchProvider> {
+  const { createLocalSearchProvider } = await import('@/lib/search/providers/local');
+  return createLocalSearchProvider(options);
+}
+
+/** Resolves a configured provider, falling back to local for unknown ids. */
+export async function resolveSearchProvider(
+  id: string,
+  options: Record<string, unknown> = {},
+): Promise<ResolvedSearchProvider> {
+  const requestedId = normalizeProviderId(id) || 'local';
+
+  if (requestedId === 'local') {
+    return {
+      provider: await createLocalProvider(options),
+      providerId: 'local',
+      fellBack: false,
+    };
+  }
+
+  const factory = factories.get(requestedId);
+
+  if (factory) {
+    return {
+      provider: await factory(options),
+      providerId: requestedId,
+      fellBack: false,
+    };
+  }
+
+  return {
+    provider: await createLocalProvider({}),
+    providerId: 'local',
+    fellBack: true,
+  };
+}

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

@@ -0,0 +1,15 @@
+import type { SearchRecord } from '@/lib/search';
+import { searchIndex } from '@/lib/search';
+import type { SearchProvider } from '@/lib/search/provider';
+
+/** Built-in provider backed by the section index generated during the build. */
+export function createLocalSearchProvider(_options: Record<string, unknown> = {}): SearchProvider {
+  let records: Promise<SearchRecord[]> | null = null;
+
+  return {
+    async search(query, limit) {
+      records ||= import('@/lib/search-index.generated').then(module => module.SEARCH_INDEX);
+      return searchIndex(await records, query, limit);
+    },
+  };
+}