@umami/shiso 1.4.0 → 1.6.0

package/dist/chunks/local.js

@@ -1,66 +1,5 @@
-//#region src/lib/search.ts
-/**
-* Restricts records to the active scope. Records without a scope id (from
-* single-scope indexes or older caches) always pass.
-*/
-function filterRecordsByScope(records, context) {
-	if (!context?.scopeId) return records;
-	return records.filter((record) => !record.scopeId || record.scopeId === context.scopeId);
-}
-const SNIPPET_RADIUS = 60;
-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 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);
-	if (!terms.length) return [];
-	const results = [];
-	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, terms) : void 0,
-			score
-		});
-	}
-	return results.sort((a, b) => b.score - a.score).slice(0, limit);
-}
+import { r as searchIndex, t as filterRecordsByScope } from "./search.js";
 
-//#endregion
 //#region src/lib/search/providers/local.ts
 /** Built-in provider backed by the section index generated during the build. */
 function createLocalSearchProvider(_options = {}) {

package/dist/chunks/search.js

@@ -0,0 +1,64 @@
+//#region src/lib/search.ts
+/**
+* Restricts records to the active scope. Records without a scope id (from
+* single-scope indexes or older caches) always pass.
+*/
+function filterRecordsByScope(records, context) {
+	if (!context?.scopeId) return records;
+	return records.filter((record) => !record.scopeId || record.scopeId === context.scopeId);
+}
+const SNIPPET_RADIUS = 60;
+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 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);
+	if (!terms.length) return [];
+	const results = [];
+	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, terms) : void 0,
+			score
+		});
+	}
+	return results.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+
+//#endregion
+export { highlightTerms as n, searchIndex as r, filterRecordsByScope as t };

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/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.",

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@umami/shiso",
-  "version": "1.4.0",
+  "version": "1.6.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",
@@ -59,7 +64,7 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.7.0",
-    "@fontsource/inter": "^5.2.5",
+    "@fontsource-variable/inter": "^5.3.0",
     "@fontsource/jetbrains-mono": "^5.2.5",
     "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
@@ -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",

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/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],
+  };
+}

package/scripts/prerender.mjs

@@ -86,7 +86,9 @@ for (const route of routes) {
 // Root entry. When the default scope's landing page is not the root itself 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 (docsHomeUrl && docsHomeUrl !== '/') {
+// When a standalone page owns "/", the routes loop above already rendered the
+// real home page into dist/client/index.html — do not overwrite it.
+if (docsHomeUrl && docsHomeUrl !== '/' && !routes.includes('/')) {
   const target = withBase(`${docsHomeUrl}/`);
 
   await writePage(
@@ -144,7 +146,7 @@ for (const { source, destination } of redirects) {
   );
 }
 
-// Sitemap, only when $shiso.siteUrl provides an absolute origin.
+// Sitemap, only when shiso.config siteUrl provides an absolute origin.
 const sitemapEntries = getSitemapEntries();
 
 if (sitemapEntries.length) {

package/scripts/validate-config.mjs

@@ -52,25 +52,38 @@ export function suggestKey(unknownKey, knownKeys) {
   return bestDistance <= threshold ? best : null;
 }
 
+const SHISO_KEY_MIGRATION =
+  '(root) "$shiso" is no longer supported in docs.json — move docsPrefix, contentDir, ' +
+  'siteUrl, and locale to shiso.config.ts. See https://shiso.umami.is/docs/project-settings.';
+
 export function validateConfig(config, schema) {
   const ajv = new Ajv({ allErrors: true, allowUnionTypes: true });
 
   const validate = ajv.compile(schema);
   const knownKeys = getSchemaKeys(schema);
+  // Checked directly, not just via Ajv's additionalProperties error, so the
+  // migration message appears even when other errors change Ajv's output.
+  const hasLegacyShisoKey = !!config && typeof config === 'object' && '$shiso' in config;
+
+  if (!validate(config) || hasLegacyShisoKey) {
+    const errors = (validate.errors ?? [])
+      .filter(error => !(error.params?.additionalProperty === '$shiso' && !error.instancePath))
+      .map(error => {
+        const location = error.instancePath || '(root)';
+        const extra = error.params?.additionalProperty;
 
-  if (!validate(config)) {
-    const errors = (validate.errors ?? []).map(error => {
-      const location = error.instancePath || '(root)';
-      const extra = error.params?.additionalProperty;
+        if (extra) {
+          const suggestion = !error.instancePath && suggestKey(extra, knownKeys);
 
-      if (extra) {
-        const suggestion = !error.instancePath && suggestKey(extra, knownKeys);
+          return `${location} has unknown key "${extra}"${suggestion ? ` — did you mean "${suggestion}"?` : ''}`;
+        }
 
-        return `${location} has unknown key "${extra}"${suggestion ? ` — did you mean "${suggestion}"?` : ''}`;
-      }
+        return `${location} ${error.message}`;
+      });
 
-      return `${location} ${error.message}`;
-    });
+    if (hasLegacyShisoKey) {
+      errors.unshift(SHISO_KEY_MIGRATION);
+    }
 
     return { valid: false, errors };
   }