@umami/shiso 0.55.0 → 0.61.0

package/scripts/generate-search-index.mjs

@@ -0,0 +1,252 @@
+/**
+ * Generates the project-local .shiso/search-index.generated.ts cache.
+ *
+ * Client-side search needs the plain text of every page, which only exists in
+ * the MDX sources at build time. Each navigable page is parsed to mdast and
+ * split into heading-bounded sections; headings share the slug algorithm with
+ * rehype-slug (src/lib/slug.ts), so result anchors always match rendered ids.
+ *
+ * Pages marked `hidden` in navigation are excluded, matching their exclusion
+ * from the sidebar and sitemap.
+ *
+ * Run via `pnpm search:index`, or automatically by the Vite plugin in
+ * vite.config.ts. The generated module is dynamically imported by the search
+ * dialog, so Vite splits it out of the initial bundle.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { headingText } from '../src/lib/mdast.ts';
+import { createSlugger } from '../src/lib/slug.ts';
+import { loadDocsConfig } from './load-docs-config.mjs';
+
+const DEFAULT_ROOT = process.cwd();
+
+const parser = unified().use(remarkParse).use(remarkMdx).use(remarkFrontmatter).use(remarkGfm);
+
+/** Mirrors normalizePageReference in src/lib/docs-config.ts. */
+function normalizePageReference(pageRef) {
+  const value = pageRef
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .replace(/^docs\//, '')
+    .replace(/\.mdx?$/, '')
+    .replace(/\/+$/, '');
+
+  if (!value) {
+    return { fileSlug: 'index', slug: 'index' };
+  }
+
+  return {
+    fileSlug: value,
+    slug: value === 'index' ? 'index' : value.replace(/\/index$/, '') || 'index',
+  };
+}
+
+/**
+ * Collects `{ fileSlug, slug }` for every non-hidden page in the navigation
+ * tree. A simplified mirror of the config walker: search only needs page refs
+ * and hidden inheritance, not labels or ordering.
+ */
+function collectVisiblePages(container, pages = [], hidden = false) {
+  const items = [
+    ...(container.pages || []),
+    ...(container.groups || []),
+    ...(container.tabs || []),
+    ...(container.dropdowns || []),
+  ];
+
+  // Versions and languages collapse to their default entry, like the app does.
+  for (const key of ['versions', 'languages']) {
+    const entries = container[key];
+
+    if (Array.isArray(entries) && entries.length) {
+      items.push(entries.find(entry => entry.default) || entries[0]);
+    }
+  }
+
+  for (const item of items) {
+    if (typeof item === 'string') {
+      if (!hidden) {
+        pages.push(normalizePageReference(item));
+      }
+      continue;
+    }
+
+    if (!item || typeof item !== 'object') {
+      continue;
+    }
+
+    const itemHidden = hidden || item.hidden === true;
+
+    if (typeof item.page === 'string') {
+      if (!itemHidden) {
+        pages.push(normalizePageReference(item.page));
+      }
+      continue;
+    }
+
+    if (typeof item.root === 'string' && !itemHidden) {
+      pages.push(normalizePageReference(item.root));
+    }
+
+    collectVisiblePages(item, pages, itemHidden);
+  }
+
+  return pages;
+}
+
+/** Frontmatter is YAML, but search only needs the title line. */
+function frontmatterTitle(tree) {
+  const yaml = tree.children?.find(node => node.type === 'yaml');
+  const match = yaml?.value?.match(/^title:\s*(.+)$/m);
+  return match ? match[1].trim().replace(/^["']|["']$/g, '') : undefined;
+}
+
+/** Node types whose children are separate blocks, so their text needs a space between. */
+const BLOCK_TYPES = new Set([
+  'root',
+  'list',
+  'listItem',
+  'table',
+  'tableRow',
+  'tableCell',
+  'blockquote',
+  'mdxJsxFlowElement',
+]);
+
+/** Like toText in src/lib/mdast.ts, but block children are space-separated. */
+function blockText(node) {
+  if (typeof node.value === 'string') {
+    return node.value;
+  }
+
+  const separator = BLOCK_TYPES.has(node.type) ? ' ' : '';
+  return (node.children || []).map(blockText).join(separator);
+}
+
+/** Splits a document into heading-bounded sections of plain text. */
+function collectSections(tree) {
+  const slugger = createSlugger();
+  const sections = [{ heading: undefined, id: undefined, parts: [] }];
+
+  for (const node of tree.children || []) {
+    if (node.type === 'yaml' || node.type === 'mdxjsEsm') {
+      continue;
+    }
+
+    if (node.type === 'heading') {
+      const heading = headingText(node);
+      sections.push({ heading, id: slugger.slug(heading), parts: [] });
+      continue;
+    }
+
+    const text = blockText(node).replace(/\s+/g, ' ').trim();
+
+    if (text) {
+      sections.at(-1).parts.push(text);
+    }
+  }
+
+  return sections
+    .map(({ heading, id, parts }) => ({ heading, id, text: parts.join(' ') }))
+    .filter(section => section.heading || section.text);
+}
+
+/** @param {{ config?: object, root?: string, output?: string }} [options] */
+export async function generateSearchIndex({
+  config,
+  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 seen = new Set();
+  const records = [];
+
+  for (const { fileSlug, slug } of collectVisiblePages(docsJson.navigation || {})) {
+    if (seen.has(fileSlug)) {
+      continue;
+    }
+
+    seen.add(fileSlug);
+
+    let source;
+    let filePath;
+
+    for (const extension of ['mdx', 'md']) {
+      filePath = path.join(root, contentDir, `${fileSlug}.${extension}`);
+      source = await fs.readFile(filePath, 'utf8').catch(() => undefined);
+
+      if (source !== undefined) {
+        break;
+      }
+    }
+
+    if (source === undefined) {
+      // Missing files fail config normalization; search just skips them.
+      continue;
+    }
+
+    const tree = parser.parse(source);
+    const url = slug === 'index' ? docsPrefix || '/' : `${docsPrefix}/${slug}`;
+    const page = frontmatterTitle(tree) || fileSlug;
+
+    for (const { heading, id, text } of collectSections(tree)) {
+      records.push({ url, page, heading, id, text });
+    }
+  }
+
+  // Emitted in the repo's formatter style (single quotes, bare keys, trailing
+  // commas) so the generated file passes `biome check` unchanged.
+  const quote = value => {
+    const escaped = value.replace(/\\/g, '\\\\');
+    const singles = (value.match(/'/g) || []).length;
+    const doubles = (value.match(/"/g) || []).length;
+
+    // Like the formatter: whichever quote needs fewer escapes, single on ties.
+    return singles > doubles
+      ? `"${escaped.replace(/"/g, '\\"')}"`
+      : `'${escaped.replace(/'/g, "\\'")}'`;
+  };
+  const body = records
+    .map(record => {
+      const fields = Object.entries(record)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `    ${key}: ${quote(value)},`)
+        .join('\n');
+
+      return `  {\n${fields}\n  },`;
+    })
+    .join('\n');
+
+  const contents = `// Generated by scripts/generate-search-index.mjs. Do not edit by hand.
+import type { SearchRecord } from '@/lib/search';
+
+export const SEARCH_INDEX: SearchRecord[] = [
+${body}
+];
+`;
+
+  const previous = await fs.readFile(output, 'utf8').catch(() => '');
+
+  if (previous !== contents) {
+    await fs.mkdir(path.dirname(output), { recursive: true });
+    await fs.writeFile(output, contents);
+  }
+
+  return { pages: seen.size, records: records.length, changed: previous !== contents };
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  const { pages, records } = await generateSearchIndex();
+  console.log(`Search index: ${records} sections across ${pages} pages`);
+}

package/scripts/load-docs-config.mjs

@@ -0,0 +1,244 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/** Error raised while locating, reading, or parsing a Shiso configuration file. */
+export class DocsConfigLoadError extends Error {
+  constructor(message, { cause, code, sourcePath }) {
+    super(message, { cause });
+    this.name = 'DocsConfigLoadError';
+    this.code = code;
+    this.sourcePath = sourcePath;
+  }
+}
+
+function isObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isInsideRoot(projectRoot, candidate) {
+  const relative = path.relative(projectRoot, candidate);
+  return (
+    relative === '' ||
+    (!path.isAbsolute(relative) && !relative.startsWith(`..${path.sep}`) && relative !== '..')
+  );
+}
+
+function parseLocation(source, error) {
+  const reported = error.message.match(/line\s+(\d+)(?:\s+column\s+(\d+))?/i);
+
+  if (reported) {
+    return ` at line ${reported[1]}${reported[2] ? `, column ${reported[2]}` : ''}`;
+  }
+
+  const position = error.message.match(/position\s+(\d+)/i)?.[1];
+  const unexpectedToken = error.message.match(/Unexpected token '([^']+)'/i)?.[1];
+  const parsedOffset = position === undefined ? -1 : Number(position);
+  const offset = parsedOffset >= 0 ? parsedOffset : source.indexOf(unexpectedToken || '');
+
+  if (offset < 0 || (!position && !unexpectedToken)) {
+    return '';
+  }
+
+  const before = source.slice(0, offset);
+  const line = before.split('\n').length;
+  const lastNewline = before.lastIndexOf('\n');
+  const column = offset - lastNewline;
+
+  return ` at line ${line}, column ${column}`;
+}
+
+/** Reads a JSON document while preserving its source path in every error. */
+export async function loadJsonDocument(sourcePath, label = 'JSON document') {
+  const resolvedPath = path.resolve(sourcePath);
+  let source;
+
+  try {
+    source = await fs.readFile(resolvedPath, 'utf8');
+  } catch (error) {
+    const reason =
+      error.code === 'ENOENT' ? 'does not exist' : `could not be read: ${error.message}`;
+
+    throw new DocsConfigLoadError(`${label} "${resolvedPath}" ${reason}.`, {
+      cause: error,
+      code: error.code === 'ENOENT' ? 'NOT_FOUND' : 'READ_FAILED',
+      sourcePath: resolvedPath,
+    });
+  }
+
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    throw new DocsConfigLoadError(
+      `${label} "${resolvedPath}" contains invalid JSON${parseLocation(source, error)}: ${error.message}`,
+      {
+        cause: error,
+        code: 'INVALID_JSON',
+        sourcePath: resolvedPath,
+      },
+    );
+  }
+}
+
+function referenceError(message, { code, sourcePath }) {
+  return new DocsConfigLoadError(message, { code, sourcePath });
+}
+
+/** Resolves every `$ref` in one project configuration tree. */
+async function resolveConfigReferences(entryPath, projectRoot) {
+  const lexicalRoot = path.resolve(projectRoot);
+  const canonicalRoot = await fs.realpath(projectRoot);
+  const sourcePaths = new Set();
+  const cache = new Map();
+
+  async function canonicalDocumentPath(sourcePath, referringPath) {
+    const resolvedPath = path.resolve(sourcePath);
+
+    if (!isInsideRoot(lexicalRoot, resolvedPath) && !isInsideRoot(canonicalRoot, resolvedPath)) {
+      throw referenceError(
+        `Config reference "${resolvedPath}" from "${referringPath}" leaves the project root "${canonicalRoot}".`,
+        { code: 'REF_OUTSIDE_ROOT', sourcePath: resolvedPath },
+      );
+    }
+
+    let canonicalPath;
+
+    try {
+      canonicalPath = await fs.realpath(resolvedPath);
+    } catch (error) {
+      const reason =
+        error.code === 'ENOENT' ? 'does not exist' : `could not be resolved: ${error.message}`;
+
+      throw new DocsConfigLoadError(`Referenced config "${resolvedPath}" ${reason}.`, {
+        cause: error,
+        code: error.code === 'ENOENT' ? 'NOT_FOUND' : 'READ_FAILED',
+        sourcePath: resolvedPath,
+      });
+    }
+
+    if (!isInsideRoot(canonicalRoot, canonicalPath)) {
+      throw referenceError(
+        `Config reference "${resolvedPath}" from "${referringPath}" resolves outside the project root.`,
+        { code: 'REF_OUTSIDE_ROOT', sourcePath: resolvedPath },
+      );
+    }
+
+    return canonicalPath;
+  }
+
+  async function resolveDocument(sourcePath, stack = []) {
+    const referringPath = stack.at(-1) || entryPath;
+    const canonicalPath = await canonicalDocumentPath(sourcePath, referringPath);
+
+    if (stack.includes(canonicalPath)) {
+      const cycle = [...stack.slice(stack.indexOf(canonicalPath)), canonicalPath]
+        .map(item => path.relative(projectRoot, item) || path.basename(item))
+        .join(' -> ');
+
+      throw referenceError(`Circular config reference detected: ${cycle}.`, {
+        code: 'CIRCULAR_REF',
+        sourcePath: canonicalPath,
+      });
+    }
+
+    if (cache.has(canonicalPath)) {
+      return cache.get(canonicalPath);
+    }
+
+    sourcePaths.add(canonicalPath);
+    const document = await loadJsonDocument(canonicalPath, 'Referenced config');
+    const resolved = await resolveValue(document, canonicalPath, [...stack, canonicalPath]);
+    cache.set(canonicalPath, resolved);
+    return resolved;
+  }
+
+  async function resolveReference(reference, sourcePath, stack) {
+    if (typeof reference !== 'string' || !reference.trim()) {
+      throw referenceError(`Config $ref in "${sourcePath}" must be a non-empty string.`, {
+        code: 'INVALID_REF',
+        sourcePath,
+      });
+    }
+
+    if (path.isAbsolute(reference) || /^[a-z][a-z0-9+.-]*:/i.test(reference)) {
+      throw referenceError(
+        `Config $ref "${reference}" in "${sourcePath}" must be a relative JSON file path.`,
+        { code: 'INVALID_REF', sourcePath },
+      );
+    }
+
+    if (path.extname(reference).toLowerCase() !== '.json') {
+      throw referenceError(`Config $ref "${reference}" in "${sourcePath}" must end in .json.`, {
+        code: 'INVALID_REF',
+        sourcePath,
+      });
+    }
+
+    return resolveDocument(path.resolve(path.dirname(sourcePath), reference), stack);
+  }
+
+  async function resolveValue(value, sourcePath, stack) {
+    if (Array.isArray(value)) {
+      return Promise.all(value.map(item => resolveValue(item, sourcePath, stack)));
+    }
+
+    if (!isObject(value)) {
+      return value;
+    }
+
+    if ('$ref' in value) {
+      const referenced = await resolveReference(value.$ref, sourcePath, stack);
+
+      // Object targets receive shallow sibling overrides. For arrays and
+      // primitives, the reference replaces the whole object and siblings are
+      // intentionally ignored.
+      if (!isObject(referenced)) {
+        return referenced;
+      }
+
+      const siblings = Object.fromEntries(Object.entries(value).filter(([key]) => key !== '$ref'));
+      const resolvedSiblings = await resolveValue(siblings, sourcePath, stack);
+      return { ...referenced, ...resolvedSiblings };
+    }
+
+    const entries = await Promise.all(
+      Object.entries(value).map(async ([key, item]) => [
+        key,
+        await resolveValue(item, sourcePath, stack),
+      ]),
+    );
+    return Object.fromEntries(entries);
+  }
+
+  const config = await resolveDocument(entryPath);
+  return { config, projectRoot: canonicalRoot, sourcePaths: [...sourcePaths] };
+}
+
+/**
+ * Loads the project docs configuration.
+ *
+ * Returning its resolved source path now gives the later `$ref` resolver a
+ * stable place from which to resolve relative references without changing
+ * every build-time consumer again.
+ */
+export async function loadDocsConfig({ root = process.cwd(), configFile = 'docs.json' } = {}) {
+  const requestedRoot = path.resolve(root);
+  const requestedSourcePath = path.resolve(requestedRoot, configFile);
+  const { config, projectRoot, sourcePaths } = await resolveConfigReferences(
+    requestedSourcePath,
+    requestedRoot,
+  );
+  const sourcePath = sourcePaths[0] || requestedSourcePath;
+
+  return { config, projectRoot, sourcePath, sourcePaths };
+}
+
+export async function loadDocsSchema({
+  root = process.cwd(),
+  schemaFile = 'docs.schema.json',
+} = {}) {
+  const projectRoot = path.resolve(root);
+  const sourcePath = path.resolve(projectRoot, schemaFile);
+  const schema = await loadJsonDocument(sourcePath, 'Docs schema');
+
+  return { projectRoot, schema, sourcePath };
+}

package/scripts/prerender.mjs

@@ -0,0 +1,187 @@
+/**
+ * Prerenders every docs page to static HTML.
+ *
+ * Runs after `vite build` (client) and `vite build --ssr` (server):
+ * 1. Loads the SSR bundle from dist/server.
+ * 2. Renders each route from the normalized docs.json navigation.
+ * 3. Injects the rendered HTML and per-page head tags into the client
+ *    dist/client/index.html template.
+ * 4. Writes dist/client/<base>/<route>/index.html plus a root entry and 404 page.
+ *
+ * Routes from the SSR bundle are base-relative; the deploy base is applied here
+ * so the output directory layout matches the URLs the router will produce.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { loadDocsConfig } from './load-docs-config.mjs';
+
+const DEFAULT_HEAD_OPEN = '<!--shiso-default-head-->';
+const DEFAULT_HEAD_CLOSE = '<!--/shiso-default-head-->';
+
+const root = process.cwd();
+const clientDir = path.join(root, 'dist', 'client');
+const template = await readFile(path.join(clientDir, 'index.html'), 'utf8');
+
+if (!template.includes('<!--app-html-->')) {
+  throw new Error(
+    'dist/client/index.html is missing the <!--app-html--> placeholder. ' +
+      'Run "vite build" again before prerendering (prerender consumes the template in place).',
+  );
+}
+
+const { config: docsJson } = await loadDocsConfig({ root });
+const docsPrefix = (docsJson.$shiso?.docsPrefix ?? '/docs').replace(/\/+$/, '');
+
+const { render, getRoutes, getRedirects, getSitemapEntries, getMarkdownPages } = await import(
+  pathToFileURL(path.join(root, 'dist', 'server', 'entry-server.js')).href
+);
+
+/** Vite's `base`, normalized to "" or "/prefix". */
+function readBase() {
+  const match = template.match(/<script[^>]+src="([^"]*)\/assets\//);
+  const base = match?.[1] ?? '';
+  return base === '/' ? '' : base;
+}
+
+const base = readBase();
+
+function withBase(routePath) {
+  return `${base}${routePath}`.replace(/\/{2,}/g, '/') || '/';
+}
+
+function fillTemplate(head, html) {
+  // Per-page head tags supersede the site-level defaults injected at build time.
+  const output = head
+    ? template.replace(new RegExp(`${DEFAULT_HEAD_OPEN}[\\s\\S]*?${DEFAULT_HEAD_CLOSE}`), '')
+    : template;
+
+  return output.replace('<!--app-head-->', head).replace('<!--app-html-->', html);
+}
+
+async function writePage(outputPath, contents) {
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, contents, 'utf8');
+}
+
+/** Maps a base-relative route to its output file, e.g. "/docs/a" -> "docs/a/index.html". */
+function outputPathFor(routePath) {
+  const relative = withBase(routePath).replace(/^\//, '');
+  return path.join(clientDir, relative, 'index.html');
+}
+
+const routes = getRoutes();
+
+for (const route of routes) {
+  const { html, head } = render(route);
+  await writePage(outputPathFor(route), fillTemplate(head, html));
+}
+
+// Root entry. When docs live at a prefix the root is a redirect; a meta refresh
+// alone is slow and SEO-hostile, so pair it with a canonical link and an
+// immediate history-replacing navigation.
+if (docsPrefix) {
+  const target = withBase(`${docsPrefix}/`);
+
+  await writePage(
+    path.join(clientDir, 'index.html'),
+    fillTemplate(
+      [
+        `<link rel="canonical" href="${target}" />`,
+        `<meta http-equiv="refresh" content="0;url=${target}" />`,
+        `<script>location.replace(${JSON.stringify(target)});</script>`,
+      ].join('\n    '),
+      '',
+    ),
+  );
+}
+
+// Raw markdown next to every page: "/docs/installation" -> "docs/installation.md".
+// Served for the contextual menu's copy/view options and for AI tools.
+const markdownPages = getMarkdownPages();
+
+for (const { route, filePath } of markdownPages) {
+  const source = await readFile(path.join(root, ...filePath.split('/').filter(Boolean)), 'utf8');
+  const relative = withBase(route).replace(/^\//, '') || 'index';
+  await writePage(path.join(clientDir, `${relative}.md`), source);
+}
+
+// Redirect pages. Static hosting cannot serve real 301s, so each redirect
+// gets the same canonical + meta refresh + immediate replace treatment as
+// the root entry. Real pages always win over redirect rules.
+const routeSet = new Set(routes.map(withBase));
+const redirects = getRedirects();
+
+function redirectTarget(destination) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(destination) ? destination : withBase(destination);
+}
+
+for (const { source, destination } of redirects) {
+  if (routeSet.has(withBase(source))) {
+    console.warn(`Redirect source "${source}" is an existing page — skipped.`);
+    continue;
+  }
+
+  const target = redirectTarget(destination);
+
+  await writePage(
+    outputPathFor(source),
+    fillTemplate(
+      [
+        `<link rel="canonical" href="${target}" />`,
+        `<meta name="robots" content="noindex" />`,
+        `<meta http-equiv="refresh" content="0;url=${target}" />`,
+        `<script>location.replace(${JSON.stringify(target)});</script>`,
+      ].join('\n    '),
+      '',
+    ),
+  );
+}
+
+// Sitemap, only when $shiso.siteUrl provides an absolute origin.
+const sitemapEntries = getSitemapEntries();
+
+if (sitemapEntries.length) {
+  const urls = sitemapEntries
+    .map(({ url, lastmod }) =>
+      [
+        '  <url>',
+        `    <loc>${url}</loc>`,
+        lastmod ? `    <lastmod>${lastmod}</lastmod>` : null,
+        '  </url>',
+      ]
+        .filter(Boolean)
+        .join('\n'),
+    )
+    .join('\n');
+
+  await writePage(
+    path.join(clientDir, 'sitemap.xml'),
+    `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`,
+  );
+}
+
+// 404 fallback renders the app shell so client routing can take over
+// on hosts that serve 404.html for unknown paths (e.g. GitHub Pages).
+const notFound = render('/404');
+await writePage(path.join(clientDir, '404.html'), fillTemplate(notFound.head, notFound.html));
+
+// Guard against a base/route mismatch silently producing unreachable files.
+const stray = routes.filter(route => !withBase(route).startsWith(base || '/'));
+
+if (stray.length) {
+  throw new Error(`Routes fall outside the deploy base "${base}": ${stray.join(', ')}`);
+}
+
+const extras = [
+  redirects.length ? `${redirects.length} redirects` : null,
+  sitemapEntries.length ? 'sitemap.xml' : null,
+]
+  .filter(Boolean)
+  .join(', ');
+
+console.log(
+  `Prerendered ${routes.length} pages to ${path.relative(root, clientDir)}${extras ? ` (+ ${extras})` : ''}`,
+);