@umami/shiso 1.3.0 → 1.5.0

package/src/lib/standalone-pages.ts

@@ -0,0 +1,129 @@
+import type { DocsConfig, NormalizedDocsSite, StandalonePage } from '@/lib/types';
+
+/**
+ * Standalone pages: routes outside the docs navigation, declared with the
+ * top-level `pages` key in docs.json. They render with the site chrome
+ * (banner, header, footer) but no sidebar or table of contents, and a
+ * `path: "/"` entry replaces the default root redirect to the docs home.
+ */
+
+export interface NormalizeStandaloneOptions {
+  /** Docs prefix ("" or "/prefix"); standalone paths may not live under it. */
+  docsPrefix?: string;
+}
+
+function invalid(message: string): Error {
+  return new Error(`Invalid docs config: ${message}`);
+}
+
+/** Trims and canonicalizes a standalone route path; throws when malformed. */
+function normalizePath(rawPath: unknown): string {
+  const value = typeof rawPath === 'string' ? rawPath.trim() : '';
+
+  if (!value.startsWith('/')) {
+    throw invalid(`standalone page path "${String(rawPath)}" must start with "/".`);
+  }
+
+  if (/[:*]/.test(value)) {
+    throw invalid(`standalone page path "${value}" must not use wildcard patterns.`);
+  }
+
+  if (/\.mdx?$/i.test(value)) {
+    throw invalid(
+      `standalone page path "${value}" must be a route, not a file — drop the extension.`,
+    );
+  }
+
+  const collapsed = value.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+  return collapsed || '/';
+}
+
+/** Mirrors normalizePageReference in docs-config.ts for the `page` slug. */
+function normalizePageSlug(rawSlug: unknown): string {
+  const value = typeof rawSlug === 'string' ? rawSlug : '';
+
+  return (
+    value
+      .trim()
+      .replace(/\\/g, '/')
+      .replace(/^\/+/, '')
+      .replace(/^pages\//, '')
+      .replace(/\.mdx?$/, '')
+      .replace(/\/+$/, '') || 'index'
+  );
+}
+
+export function normalizeStandalonePages(
+  config: DocsConfig,
+  resolvePageFile: (fileSlug: string) => string | undefined,
+  site: NormalizedDocsSite,
+  options: NormalizeStandaloneOptions = {},
+): StandalonePage[] {
+  const items = config.pages || [];
+
+  if (!items.length) {
+    return [];
+  }
+
+  const docsPrefix = options.docsPrefix || '';
+  const pages: StandalonePage[] = [];
+  const seen = new Set<string>();
+
+  for (const item of items) {
+    const path = normalizePath(item?.path);
+
+    if (seen.has(path)) {
+      throw invalid(`duplicate standalone page path "${path}".`);
+    }
+
+    seen.add(path);
+
+    if (path === '/404') {
+      throw invalid('standalone page path "/404" is reserved for the error page.');
+    }
+
+    const docsPage = site.pageByUrl[path];
+
+    if (docsPage) {
+      throw invalid(
+        `standalone page path "${path}" collides with the docs page "${docsPage.fileSlug}". ` +
+          'Standalone pages must live outside the docs navigation.',
+      );
+    }
+
+    if (docsPrefix && (path === docsPrefix || path.startsWith(`${docsPrefix}/`))) {
+      throw invalid(
+        `standalone page path "${path}" is inside the docs prefix "${docsPrefix}". ` +
+          'Standalone pages must live outside the docs tree.',
+      );
+    }
+
+    const fileSlug = normalizePageSlug(item?.page);
+    const filePath = resolvePageFile(fileSlug);
+
+    if (!filePath) {
+      throw new Error(
+        `Missing standalone page file for "${fileSlug}": expected ` +
+          `"content/pages/${fileSlug}.mdx" or ".md".`,
+      );
+    }
+
+    pages.push({ path, filePath, title: item?.title?.trim() || undefined });
+  }
+
+  return pages;
+}
+
+/**
+ * Exact standalone page lookup by base-relative pathname. Tolerates trailing
+ * slashes and an explicit `/index` suffix, like getPageByPathname.
+ */
+export function getStandalonePageByPathname(
+  pages: StandalonePage[],
+  pathname: string,
+): StandalonePage | null {
+  const trimmed = pathname.replace(/\/+$/, '') || '/';
+  const collapsed = trimmed === '/index' ? '/' : trimmed.replace(/\/index$/, '') || '/';
+
+  return pages.find(page => page.path === trimmed || page.path === collapsed) || null;
+}

package/src/lib/types.ts

@@ -101,8 +101,9 @@ export type LogoOption =
   | string
   | { light?: string; dark?: string; href?: string; target?: LinkTarget };
 
-/** Shiso-only configuration. Namespaced so docs.json stays portable. */
-export interface ShisoOptions {
+/** Project-level settings supplied by shiso.config.ts. Mirrors the public
+ * shape exported from "@umami/shiso/config". */
+export interface ShisoConfig {
   /** Where docs pages are mounted within the site. Default "/docs"; "" for root. */
   docsPrefix?: string;
   /** Content directory relative to the project root. Default "content/docs". */
@@ -113,6 +114,14 @@ export interface ShisoOptions {
   locale?: string;
 }
 
+/** ShisoConfig after defaults and normalization, as served by `virtual:shiso-config`. */
+export interface ResolvedShisoConfig {
+  docsPrefix: string;
+  contentDir: string;
+  siteUrl?: string;
+  locale: string;
+}
+
 export type LinkTarget = '_self' | '_blank';
 
 /** A user-configured link. Presentation is determined entirely by its fields. */
@@ -166,6 +175,26 @@ export interface RedirectRule {
   destination: string;
 }
 
+/** A standalone page outside the docs navigation, e.g. a landing page. */
+export interface StandalonePageItem {
+  /** Route path, starting with "/". "/" replaces the root redirect to docs. */
+  path: string;
+  /** File slug under content/pages, e.g. "home" for content/pages/home.mdx. */
+  page: string;
+  /** Page title used in the document head. Frontmatter title wins. */
+  title?: string;
+}
+
+/** Normalized standalone page. */
+export interface StandalonePage {
+  /** Base-relative route, e.g. "/" or "/about". */
+  path: string;
+  /** Module key of the MDX file, e.g. "/content/pages/home.mdx". */
+  filePath: string;
+  /** Config-level head-title override. */
+  title?: string;
+}
+
 export interface SeoConfig {
   /** Extra meta tags added to every page, e.g. { "og:image": "/social.png" }. */
   metatags?: Record<string, string>;
@@ -219,7 +248,7 @@ export interface FontsConfig extends FontSpec {
 export interface SearchConfig {
   /** Placeholder text for the search input. */
   prompt?: string;
-  /** Registered provider id. Defaults to the built-in local provider. */
+  /** Provider id: "local" (default), "pagefind", or a runtime-registered id. */
   provider?: string;
   /** Provider-specific configuration. */
   options?: Record<string, unknown>;
@@ -271,7 +300,6 @@ export interface BackgroundConfig {
 
 export interface DocsConfig {
   $schema?: string;
-  $shiso?: ShisoOptions;
   theme?: string;
   name?: string;
   colors?: ThemeColors;
@@ -279,6 +307,8 @@ export interface DocsConfig {
   favicon?: string;
   description?: string;
   navigation: NavigationConfig;
+  /** Standalone pages outside the docs navigation, e.g. a landing page at "/". */
+  pages?: StandalonePageItem[];
   navbar?: NavbarConfig;
   footer?: FooterConfig;
   banner?: BannerConfig;

package/src/pages/StandalonePage.tsx

@@ -0,0 +1,42 @@
+import { useEffect } from 'react';
+import { useLocation } from 'react-router';
+import { Docs } from '@/components/Docs';
+import { Footer } from '@/components/Footer';
+import { getDocModule } from '@/lib/content';
+import type { SiteModel, StandalonePage } from '@/lib/types';
+
+/**
+ * A standalone (non-docs) page: site chrome from Layout (banner, header),
+ * the MDX content at full container width — no sidebar, TOC, or pager — and
+ * the footer. MDX components come from the app-level MDXProvider.
+ */
+export function StandalonePageView({ page, site }: { page: StandalonePage; site: SiteModel }) {
+  const { pathname } = useLocation();
+  const doc = getDocModule(page.filePath);
+
+  // Start each newly loaded page at the top, like Docs does for docs routes.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pathname is the trigger
+  useEffect(() => {
+    if (!window.location.hash) {
+      window.scrollTo({ top: 0, left: 0 });
+    }
+  }, [pathname]);
+
+  // Normalization guarantees the file exists; this is a build-drift safety net.
+  if (!doc) {
+    return <Docs page={null} doc={null} site={site} />;
+  }
+
+  const Content = doc.default;
+
+  return (
+    <div className="flex min-h-full flex-col">
+      <article className="grow py-8">
+        <div className="docs-markdown">
+          <Content />
+        </div>
+      </article>
+      <Footer footer={site.footer} />
+    </div>
+  );
+}

package/types/config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public types for shiso.config.ts. Kept self-contained (no imports) so the
+ * config file typechecks in consuming projects without pulling in the runtime.
+ */
+
+/** Project-level settings supplied by shiso.config.ts. All fields are optional. */
+export interface ShisoConfig {
+  /** Route prefix for docs pages within the site. Default "/docs"; "" serves docs at the site root. */
+  docsPrefix?: string;
+  /** Content directory relative to the project root. Default "content/docs". */
+  contentDir?: string;
+  /** Absolute site origin (e.g. "https://docs.example.com") used for canonical URLs, og:url, and the sitemap. */
+  siteUrl?: string;
+  /** Locale used for deterministic date formatting. Default "en-US". */
+  locale?: string;
+}
+
+/** Identity helper that types a shiso.config.ts default export. */
+export declare function defineConfig(config: ShisoConfig): ShisoConfig;

package/types/search.d.ts

@@ -3,6 +3,10 @@ export interface SearchResult {
   page: string;
   score: number;
   heading?: string;
+  /**
+   * Matched terms may be wrapped in `<mark>` tags; the search dialog renders
+   * them as highlights (never as raw HTML).
+   */
   snippet?: string;
 }
 
@@ -24,4 +28,9 @@ export type SearchProviderFactory = (
   options: Record<string, unknown>,
 ) => SearchProvider | Promise<SearchProvider>;
 
+/**
+ * Registers a runtime search provider. Call this before rendering the app.
+ * The ids "local" and "pagefind" are reserved for the built-in providers.
+ * The returned cleanup function only removes this exact registration.
+ */
 export function registerSearchProvider(id: string, factory: SearchProviderFactory): () => void;

package/vite.config.ts

@@ -9,7 +9,7 @@ import { generateIconRegistry } from './scripts/generate-icon-registry.mjs';
 import { shisoLastModified } from './scripts/generate-last-modified.mjs';
 import { generateSearchIndex } from './scripts/generate-search-index.mjs';
 import { createDocsConfigModule } from './scripts/vite-docs-config.mjs';
-import type { DocsConfig } from './src/lib/types.ts';
+import type { DocsConfig, ResolvedShisoConfig } from './src/lib/types.ts';
 
 /**
  * Keeps src/lib/icon-registry.generated.ts in sync with the `icon="name"` values
@@ -37,15 +37,25 @@ function shisoIconRegistry(getDocsConfig: () => DocsConfig, root: string, output
  * Keeps src/lib/search-index.generated.ts in sync with content, so the search
  * dialog can query page text without a server.
  */
-function shisoSearchIndex(getDocsConfig: () => DocsConfig, root: string, output: string): Plugin {
+function shisoSearchIndex(
+  getDocsConfig: () => DocsConfig,
+  getShisoConfig: () => ResolvedShisoConfig,
+  root: string,
+  output: string,
+): Plugin {
   return {
     name: 'shiso-search-index',
     async buildStart() {
-      await generateSearchIndex({ config: getDocsConfig(), root, output });
+      await generateSearchIndex({ config: getDocsConfig(), shiso: getShisoConfig(), root, output });
     },
     async handleHotUpdate({ file }) {
-      if (/\.(md|mdx)$/.test(file) || file.endsWith('docs.json')) {
-        await generateSearchIndex({ config: getDocsConfig(), root, output });
+      if (/\.(md|mdx)$/.test(file) || file.endsWith('docs.json') || /shiso\.config\.\w+$/.test(file)) {
+        await generateSearchIndex({
+          config: getDocsConfig(),
+          shiso: getShisoConfig(),
+          root,
+          output,
+        });
       }
     },
   };
@@ -288,7 +298,11 @@ function shisoHtml(getDocsConfig: () => DocsConfig): Plugin {
  * production builds. The contextual menu's copy/view options and AI links
  * depend on these URLs.
  */
-function shisoMarkdownDev(getDocsConfig: () => DocsConfig, root: string): Plugin {
+function shisoMarkdownDev(
+  getDocsConfig: () => DocsConfig,
+  getShisoConfig: () => ResolvedShisoConfig,
+  root: string,
+): Plugin {
   return {
     name: 'shiso-markdown-dev',
     apply: 'serve',
@@ -300,17 +314,8 @@ function shisoMarkdownDev(getDocsConfig: () => DocsConfig, root: string): Plugin
           return next();
         }
 
-        const shiso =
-          (getDocsConfig() as { $shiso?: { docsPrefix?: string; contentDir?: string } }).$shiso ||
-          {};
-        const contentDir = (shiso.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
-        const prefixValue = (shiso.docsPrefix ?? '/docs').trim().replace(/\/+$/, '');
-        const docsPrefix =
-          !prefixValue || prefixValue === '/'
-            ? ''
-            : prefixValue.startsWith('/')
-              ? prefixValue
-              : `/${prefixValue}`;
+        // Values arrive with defaults applied and already normalized.
+        const { contentDir, docsPrefix } = getShisoConfig();
 
         let route = decodeURIComponent(url).slice(0, -'.md'.length);
         const base = server.config.base.replace(/\/+$/, '');
@@ -319,6 +324,39 @@ function shisoMarkdownDev(getDocsConfig: () => DocsConfig, root: string): Plugin
           route = route.slice(base.length);
         }
 
+        // Standalone pages (top-level `pages` key) live under content/pages,
+        // outside the docs prefix. "/index.md" maps to the "/" entry.
+        const routeKey = (route.replace(/\/+$/, '') || '/').replace(/^\/index$/, '/');
+        const standalone = (getDocsConfig().pages || []).find(
+          item => (item?.path?.trim().replace(/\/+$/, '') || '/') === routeKey,
+        );
+
+        if (standalone?.page) {
+          const pagesRoot = path.resolve(root, 'content/pages');
+          const pageSlug = standalone.page
+            .trim()
+            .replace(/^\/+/, '')
+            .replace(/\.mdx?$/, '');
+
+          for (const candidate of [`${pageSlug}.mdx`, `${pageSlug}.md`]) {
+            const filePath = path.resolve(pagesRoot, candidate);
+
+            // Never read outside the pages directory.
+            if (!filePath.startsWith(pagesRoot + path.sep)) {
+              break;
+            }
+
+            try {
+              const source = await readFile(filePath, 'utf8');
+              res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+              res.end(source);
+              return;
+            } catch {
+              // Try the next candidate.
+            }
+          }
+        }
+
         if (docsPrefix && route.startsWith(docsPrefix)) {
           route = route.slice(docsPrefix.length);
         }
@@ -364,6 +402,7 @@ export default defineConfig(async () => {
     root: projectRoot,
   });
   const getDocsConfig = configModule.getConfig as () => DocsConfig;
+  const getShisoConfig = configModule.getShisoConfig as () => ResolvedShisoConfig;
 
   return {
     optimizeDeps: {
@@ -385,11 +424,12 @@ export default defineConfig(async () => {
       }),
       shisoSearchIndex(
         getDocsConfig,
+        getShisoConfig,
         projectRoot,
         path.join(generatedRoot, 'search-index.generated.ts'),
       ),
       shisoHtml(getDocsConfig),
-      shisoMarkdownDev(getDocsConfig, projectRoot),
+      shisoMarkdownDev(getDocsConfig, getShisoConfig, projectRoot),
       shisoMdx(),
       react({ include: /\.(mdx|md|tsx|ts|jsx|js)$/ }),
     ],