@umami/shiso 1.4.0 → 1.5.0

package/src/components/Header.tsx

@@ -1,31 +1,58 @@
-import { useLocation } from 'react-router';
+import { Link, useLocation } from 'react-router';
 import { ConfiguredIcon } from '@/components/ConfiguredIcon';
 import { LanguageSwitcher } from '@/components/LanguageSwitcher';
 import { Search } from '@/components/Search';
 import { ThemeToggle } from '@/components/ThemeToggle';
 import { TopNav } from '@/components/TopNav';
 import { VersionSwitcher } from '@/components/VersionSwitcher';
-import { docsHomeUrl, getScopeByPathname } from '@/lib/site-config';
+import { isExternalHref } from '@/lib/paths';
+import { docsHomeUrl, getScopeByPathname, hasRootStandalonePage } from '@/lib/site-config';
 import type { NormalizedLink, SiteModel } from '@/lib/types';
 
+/**
+ * Header hrefs come from config, so they may point inside the site or off it.
+ * In-app routes go through react-router; anything external (or explicitly
+ * opened in a new tab) stays a plain anchor and triggers a document load.
+ */
+function isRoutedHref(href: string, target?: string): boolean {
+  return href.startsWith('/') && !isExternalHref(href) && target !== '_blank';
+}
+
 function NavbarLinkItem({ link, primary = false }: { link: NormalizedLink; primary?: boolean }) {
   const iconOnly = !link.label;
   const accessibleLabel = link.ariaLabel || link.icon || link.href;
 
+  const className = primary
+    ? `ml-1 inline-flex items-center justify-center rounded-full bg-primary text-sm font-semibold text-primary-foreground hover:opacity-90 ${iconOnly ? 'size-8' : 'gap-1.5 px-3.5 py-1.5'}`
+    : `inline-flex items-center rounded-md text-sm font-medium text-foreground hover:bg-accent hover:text-foreground ${iconOnly ? 'size-8 justify-center' : 'gap-1.5 px-2.5 py-1.5'}`;
+  const content = (
+    <>
+      <ConfiguredIcon icon={link.icon} />
+      {link.label}
+    </>
+  );
+
+  if (isRoutedHref(link.href, link.target)) {
+    return (
+      <Link
+        to={link.href}
+        className={className}
+        aria-label={iconOnly ? accessibleLabel : undefined}
+      >
+        {content}
+      </Link>
+    );
+  }
+
   return (
     <a
       href={link.href}
-      className={
-        primary
-          ? `ml-1 inline-flex items-center justify-center rounded-full bg-primary text-sm font-semibold text-primary-foreground hover:opacity-90 ${iconOnly ? 'size-8' : 'gap-1.5 px-3.5 py-1.5'}`
-          : `inline-flex items-center rounded-md text-sm font-medium text-foreground hover:bg-accent hover:text-foreground ${iconOnly ? 'size-8 justify-center' : 'gap-1.5 px-2.5 py-1.5'}`
-      }
+      className={className}
       target={link.target}
       rel={link.target === '_blank' ? 'noreferrer' : undefined}
       aria-label={iconOnly ? accessibleLabel : undefined}
     >
-      <ConfiguredIcon icon={link.icon} />
-      {link.label}
+      {content}
     </a>
   );
 }
@@ -35,28 +62,38 @@ export function Header({ site }: { site: SiteModel }) {
   const { pathname } = useLocation();
   // The header renders the navigation of whichever scope owns the current page.
   const docs = getScopeByPathname(pathname).docs;
-  const brandHref = logo?.href || docsHomeUrl;
+  // The brand links to the standalone home page when one owns "/".
+  const brandHref = logo?.href || (hasRootStandalonePage ? '/' : docsHomeUrl);
   const hasBrand = !!name || !!logo?.light || !!logo?.dark;
+  const brandClassName =
+    'inline-flex items-center gap-2 text-xl font-bold text-foreground tracking-[-0.03em]';
+  const brandContent = (
+    <>
+      {logo?.light ? <img src={logo.light} alt="" className="h-6 w-auto dark:hidden" /> : null}
+      {logo?.dark ? <img src={logo.dark} alt="" className="hidden h-6 w-auto dark:block" /> : null}
+      {name ? <span>{name}</span> : null}
+    </>
+  );
 
   return (
     <header className="sticky top-0 z-50 h-[var(--header-height)] shrink-0 border-border border-b bg-[color-mix(in_srgb,var(--background)_92%,transparent)] backdrop-blur-md">
       <div className="mx-auto grid h-full max-w-[1600px] grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center px-5">
         <div className="flex min-w-0 items-center gap-5 justify-self-start">
           {hasBrand ? (
-            <a
-              href={brandHref}
-              target={logo?.target}
-              rel={logo?.target === '_blank' ? 'noreferrer' : undefined}
-              className="inline-flex items-center gap-2 text-xl font-bold text-foreground tracking-[-0.03em]"
-            >
-              {logo?.light ? (
-                <img src={logo.light} alt="" className="h-6 w-auto dark:hidden" />
-              ) : null}
-              {logo?.dark ? (
-                <img src={logo.dark} alt="" className="hidden h-6 w-auto dark:block" />
-              ) : null}
-              {name ? <span>{name}</span> : null}
-            </a>
+            isRoutedHref(brandHref, logo?.target) ? (
+              <Link to={brandHref} className={brandClassName}>
+                {brandContent}
+              </Link>
+            ) : (
+              <a
+                href={brandHref}
+                target={logo?.target}
+                rel={logo?.target === '_blank' ? 'noreferrer' : undefined}
+                className={brandClassName}
+              >
+                {brandContent}
+              </a>
+            )
           ) : null}
           <div className="hidden items-center gap-2 lg:flex">
             <VersionSwitcher />

package/src/components/TopNav.tsx

@@ -1,4 +1,3 @@
-import { cn } from '@/lib/utils';
 import { Link, useLocation, useNavigate } from 'react-router';
 import { ConfiguredIcon } from '@/components/ConfiguredIcon';
 import { ChevronRight } from '@/components/icons';
@@ -8,7 +7,9 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
+import { getStandalonePage } from '@/lib/site-config';
 import type { DocsTab, LinkTarget, NavNode, NormalizedDocsConfig } from '@/lib/types';
+import { cn } from '@/lib/utils';
 
 interface MenuLink {
   label: string;
@@ -55,12 +56,13 @@ export function TopNav({ docs, label }: { docs: NormalizedDocsConfig; label: str
   }
 
   const page = docs.pages.find(item => item.url === pathname);
-  const selected =
-    page?.tabId ||
-    [...tabs]
-      .sort((a, b) => b.url.length - a.url.length)
-      .find(tab => pathname === tab.url || pathname.startsWith(`${tab.url}/`))?.id ||
-    tabs[0]?.id;
+  const matchedTabId = [...tabs]
+    .sort((a, b) => b.url.length - a.url.length)
+    .find(tab => pathname === tab.url || pathname.startsWith(`${tab.url}/`))?.id;
+  // Standalone pages live outside the docs tree, so no tab owns them. Only
+  // unmatched *docs* routes fall back to highlighting the first tab.
+  const fallbackTabId = getStandalonePage(pathname) ? undefined : tabs[0]?.id;
+  const selected = page?.tabId || matchedTabId || fallbackTabId;
   const tabClass = (tab: DocsTab) =>
     cn(
       'flex h-full items-center gap-1 whitespace-nowrap border-transparent border-b-2 font-medium',

package/src/components/docs/Button.tsx

@@ -0,0 +1,67 @@
+import type { ReactNode } from 'react';
+import { Link } from 'react-router';
+import { Button as ButtonPrimitive, buttonVariants } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+import { resolveIcon } from './utils';
+
+export interface ButtonProps {
+  href?: string;
+  variant?: 'default' | 'outline' | 'secondary' | 'ghost' | 'destructive' | 'link';
+  size?: 'default' | 'xs' | 'sm' | 'lg';
+  icon?: ReactNode | string;
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * MDX-facing button. Renders a link when `href` is set (internal routes go
+ * through react-router), otherwise a plain button element.
+ */
+export function Button({
+  href,
+  variant = 'default',
+  size = 'default',
+  icon,
+  className,
+  children,
+}: ButtonProps) {
+  const resolvedIcon = resolveIcon(icon, 16);
+  const content = (
+    <>
+      {resolvedIcon}
+      {children}
+    </>
+  );
+  // MDX wraps block-level children in <p>; strip its margins so the label
+  // stays centered against the icon.
+  const baseClassName = cn(resolvedIcon ? 'gap-2' : '', '[&_p]:m-0', className);
+
+  if (!href) {
+    return (
+      <ButtonPrimitive variant={variant} size={size} className={baseClassName}>
+        {content}
+      </ButtonPrimitive>
+    );
+  }
+
+  const linkClassName = cn(
+    buttonVariants({ variant, size }),
+    'no-underline hover:no-underline active:no-underline',
+    baseClassName,
+  );
+  const external = /^https?:\/\//i.test(href);
+
+  if (external) {
+    return (
+      <a href={href} className={linkClassName} target="_blank" rel="noreferrer">
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <Link to={href} className={linkClassName}>
+      {content}
+    </Link>
+  );
+}

package/src/components/docs/index.ts

@@ -1,5 +1,6 @@
 export * from './Accordion';
 export * from './Badge';
+export * from './Button';
 export * from './Callout';
 export * from './Card';
 export * from './CodeGroup';

package/src/declarations.d.ts

@@ -7,3 +7,10 @@ declare module 'virtual:shiso-docs-config' {
   const config: DocsConfig;
   export default config;
 }
+
+declare module 'virtual:shiso-config' {
+  import type { ResolvedShisoConfig } from '@/lib/types';
+
+  const config: ResolvedShisoConfig;
+  export default config;
+}

package/src/entry-server.tsx

@@ -12,6 +12,7 @@ import {
   getRedirects,
   getSeo,
   siteName,
+  standalonePages,
 } from '@/lib/site-config';
 
 export interface RenderResult {
@@ -28,7 +29,7 @@ export interface SitemapEntry {
 
 /** Base-relative routes for every scope. The prerenderer prepends the deploy base itself. */
 export function getRoutes(): string[] {
-  return docsSite.pages.map(page => page.url);
+  return [...docsSite.pages.map(page => page.url), ...standalonePages.map(page => page.path)];
 }
 
 /** Redirect rules with exact-match sources, for static redirect pages. */
@@ -41,12 +42,15 @@ export { getRedirects };
  * "/content/docs/index.mdx", resolved against the project root.
  */
 export function getMarkdownPages(): { route: string; filePath: string }[] {
-  return docsSite.pages.map(page => ({ route: page.url, filePath: page.filePath }));
+  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.
  */
 export function getSitemapEntries(): SitemapEntry[] {
@@ -71,6 +75,19 @@ export function getSitemapEntries(): SitemapEntry[] {
     }
   }
 
+  // Standalone pages are always navigable; only frontmatter noindex opts out.
+  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;
 }
 

package/src/lib/content.ts

@@ -1,5 +1,5 @@
 import { LAST_MODIFIED } from '@/generated/last-modified';
-import { CONTENT_DIR } from '@/lib/paths';
+import { CONTENT_DIR, PAGES_DIR } from '@/lib/paths';
 import type { DocModule } from '@/lib/types';
 
 /**
@@ -12,7 +12,7 @@ import type { DocModule } from '@/lib/types';
  * without Suspense, at the cost of bundling all pages together.
  *
  * The glob pattern must be a literal for Vite to statically analyze it, so it
- * covers all of `content/` and the configured `$shiso.contentDir` is applied at
+ * covers all of `content/` and the configured shiso.config `contentDir` is applied at
  * lookup time instead. That also lets later versioned/localized content roots
  * (`content/v2`, `content/es`) work without touching this glob.
  */
@@ -30,6 +30,14 @@ export function resolveDocFile(fileSlug: string, contentDir = CONTENT_DIR): stri
   return candidates.find(candidate => candidate in docModules);
 }
 
+/**
+ * Resolves a standalone page slug (docs.json `pages[].page`) to a module key
+ * under the fixed content/pages root.
+ */
+export function resolvePageFile(fileSlug: string): string | undefined {
+  return resolveDocFile(fileSlug, PAGES_DIR);
+}
+
 export function getDocModule(filePath: string): DocModule | undefined {
   return docModules[filePath];
 }

package/src/lib/head.ts

@@ -8,6 +8,7 @@ import {
   getPageTitle,
   getScopeByPathname,
   getSeo,
+  getStandalonePage,
   showTimestamp,
   siteConfig,
   siteModel,
@@ -49,18 +50,25 @@ function escapeJsonLd(value: string): string {
 
 export function buildHead(pathname: string): HeadTag[] {
   const page = getPageByPathname(pathname);
-  const doc = page ? getDocModule(page.filePath) : undefined;
+  const standalone = page ? null : getStandalonePage(pathname);
+  const filePath = page?.filePath || standalone?.filePath;
+  const doc = filePath ? getDocModule(filePath) : undefined;
   const frontmatter = doc?.frontmatter;
 
   const seo = getSeo();
-  const pageTitle = frontmatter?.title || page?.label;
+  const pageTitle = frontmatter?.title || standalone?.title || page?.label;
   const title = getPageTitle(pageTitle);
   const description = frontmatter?.description || siteConfig.description;
-  const canonical = page ? toAbsoluteUrl(page.url) : undefined;
+  const canonical = page
+    ? toAbsoluteUrl(page.url)
+    : standalone
+      ? toAbsoluteUrl(standalone.path)
+      : undefined;
   // `seo.indexing: "all"` opts hidden pages (and hidden versions/languages)
   // into the index; explicit per-page `noindex` frontmatter always wins.
   const hidden = !!page && (!!page.hidden || !!getScopeByPathname(pathname).hidden);
-  const noindex = !page || frontmatter?.noindex === true || (hidden && seo.indexing !== 'all');
+  const noindex =
+    (!page && !standalone) || frontmatter?.noindex === true || (hidden && seo.indexing !== 'all');
 
   const tags: HeadTag[] = [{ tag: 'title', children: title }];
 
@@ -76,9 +84,9 @@ export function buildHead(pathname: string): HeadTag[] {
     tags.push({ tag: 'meta', attrs: { name: 'robots', content: 'noindex' } });
   }
 
-  // Open Graph
+  // Open Graph. Standalone pages (home, landing) are websites, not articles.
   tags.push(
-    { tag: 'meta', attrs: { property: 'og:type', content: 'article' } },
+    { tag: 'meta', attrs: { property: 'og:type', content: standalone ? 'website' : 'article' } },
     { tag: 'meta', attrs: { property: 'og:title', content: title } },
   );
 
@@ -106,7 +114,7 @@ export function buildHead(pathname: string): HeadTag[] {
 
   // Last-modified time, when the timestamp feature is on for this page.
   const lastModified =
-    page && showTimestamp(frontmatter?.timestamp) ? getLastModified(page.filePath) : undefined;
+    filePath && showTimestamp(frontmatter?.timestamp) ? getLastModified(filePath) : undefined;
 
   if (lastModified) {
     tags.push({ tag: 'meta', attrs: { property: 'article:modified_time', content: lastModified } });

package/src/lib/locale.ts

@@ -18,7 +18,7 @@ export function isValidLocale(value: string | undefined): value is string {
 
 /**
  * Locale for a page: its scope's language code when valid, then the
- * site-wide `$shiso.locale`, then en-US.
+ * site-wide shiso.config `locale`, then en-US.
  */
 export function resolveLocale(language: string | undefined, fallback: string | undefined): string {
   if (isValidLocale(language)) {

package/src/lib/paths.ts

@@ -1,5 +1,4 @@
-import rawConfig from 'virtual:shiso-docs-config';
-import type { ShisoOptions } from '@/lib/types';
+import shiso from 'virtual:shiso-config';
 
 /**
  * All URL construction goes through this module.
@@ -14,10 +13,11 @@ import type { ShisoOptions } from '@/lib/types';
  * 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`.
+ *
+ * Values from `virtual:shiso-config` arrive with defaults applied and already
+ * normalized by scripts/load-shiso-config.mjs.
  */
 
-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(/\/+$/, '');
@@ -31,13 +31,17 @@ function normalizePrefix(value: string): string {
 
 export const BASE_URL = normalizePrefix(import.meta.env?.BASE_URL || '/');
 
-export const DOCS_PREFIX = normalizePrefix(shiso.docsPrefix ?? '/docs');
+export const DOCS_PREFIX = shiso.docsPrefix;
 
 /** Content directory, relative to the project root, without leading/trailing slashes. */
-export const CONTENT_DIR = (shiso.contentDir ?? 'content/docs').replace(/^\/+|\/+$/g, '');
+export const CONTENT_DIR = shiso.contentDir;
+
+/** Fixed root for standalone (non-docs) page files. Not configurable, so page
+ * slugs can never collide with the docs content tree. */
+export const PAGES_DIR = 'content/pages';
 
 /** Absolute origin used for canonical and og:url tags. Undefined when unconfigured. */
-export const SITE_URL = shiso.siteUrl?.replace(/\/+$/, '') || undefined;
+export const SITE_URL = shiso.siteUrl;
 
 /** Joins path segments with exactly one slash between them. */
 export function joinPath(...parts: (string | undefined)[]): string {

package/src/lib/site-config.ts

@@ -1,5 +1,6 @@
+import shisoConfig from 'virtual:shiso-config';
 import rawConfig from 'virtual:shiso-docs-config';
-import { resolveDocFile } from '@/lib/content';
+import { resolveDocFile, resolvePageFile } from '@/lib/content';
 import {
   assertDocsConfig,
   getDefaultScope,
@@ -8,8 +9,9 @@ import {
   normalizeDocsSite,
 } from '@/lib/docs-config';
 import { getTextDirection, resolveLocale } from '@/lib/locale';
-import { stripBase } from '@/lib/paths';
+import { DOCS_PREFIX, stripBase } from '@/lib/paths';
 import { resolveSiteModel } from '@/lib/site-model';
+import { getStandalonePageByPathname, normalizeStandalonePages } from '@/lib/standalone-pages';
 import type {
   DocsConfig,
   DocsScope,
@@ -18,6 +20,7 @@ import type {
   NormalizedDocsSite,
   RedirectRule,
   SeoConfig,
+  StandalonePage,
 } from '@/lib/types';
 
 assertDocsConfig(rawConfig, 'docs.json');
@@ -33,7 +36,22 @@ export const docsConfig: NormalizedDocsConfig = getDefaultScope(docsSite).docs;
 /** Landing page of the default scope: the site-wide "docs home" URL. */
 export const docsHomeUrl = getDefaultScope(docsSite).firstPageUrl;
 
-export const siteModel = resolveSiteModel(siteConfig, docsConfig);
+export const siteModel = resolveSiteModel(siteConfig, docsConfig, shisoConfig);
+
+/** Standalone pages declared with the top-level `pages` key, e.g. a home page. */
+export const standalonePages: StandalonePage[] = normalizeStandalonePages(
+  siteConfig,
+  resolvePageFile,
+  docsSite,
+  { docsPrefix: DOCS_PREFIX },
+);
+
+/** True when a standalone page owns "/", replacing the root docs redirect. */
+export const hasRootStandalonePage = standalonePages.some(page => page.path === '/');
+
+export function getStandalonePage(pathname: string): StandalonePage | null {
+  return getStandalonePageByPathname(standalonePages, stripBase(pathname));
+}
 
 /** Scope that owns the current pathname; the default scope for unknown paths. */
 export function getScopeByPathname(pathname: string): DocsScope {

package/src/lib/site-model.ts

@@ -12,6 +12,7 @@ import type {
   NormalizedLink,
   NormalizedNavbar,
   ResolvedContextualOption,
+  ResolvedShisoConfig,
   SiteModel,
   ThemeLabels,
 } from '@/lib/types';
@@ -90,7 +91,11 @@ function normalizeFooter(config: DocsConfig['footer']): NormalizedFooter | null
   return socials.length || links.length || attribution ? { socials, links, attribution } : null;
 }
 
-export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig): SiteModel {
+export function resolveSiteModel(
+  config: DocsConfig,
+  docs: NormalizedDocsConfig,
+  shiso?: ResolvedShisoConfig,
+): SiteModel {
   const appearance = config.appearance || {};
   const logo = config.logo
     ? typeof config.logo === 'string'
@@ -128,7 +133,7 @@ export function resolveSiteModel(config: DocsConfig, docs: NormalizedDocsConfig)
     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',
+    locale: shiso?.locale || 'en-US',
     labels: SHISO_THEME_LABELS,
     docs,
   };

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;
+}