@umami/shiso 1.3.0 → 1.5.0

package/scripts/pagefind-index.mjs

@@ -0,0 +1,127 @@
+/**
+ * Generates a Pagefind index over the prerendered HTML.
+ *
+ * Runs after `prerender.mjs` as the final step of `shiso build`, from the
+ * project root. It is a no-op unless docs.json resolves `search.provider`
+ * to "pagefind". Only pages carrying `data-pagefind-body` (the doc
+ * `<article>`) are indexed, so redirect stubs and the 404 page are skipped
+ * automatically.
+ *
+ * The base subdirectory of dist/client is indexed (not dist/client itself)
+ * so the recorded URLs are base-relative — the runtime provider hands them
+ * to a router whose `basename` re-applies the deploy base.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+import { loadDocsConfig } from './load-docs-config.mjs';
+
+const root = process.cwd();
+const clientDir = path.join(root, 'dist', 'client');
+
+const { config } = await loadDocsConfig({ root });
+
+const search = config.search;
+const provider =
+  search === false
+    ? ''
+    : String(search?.provider || 'local')
+        .trim()
+        .toLowerCase();
+
+if (provider !== 'pagefind') {
+  process.exit(0);
+}
+
+let pagefind;
+
+try {
+  pagefind = await import('pagefind');
+} catch (error) {
+  if (error?.code === 'ERR_MODULE_NOT_FOUND') {
+    console.error(
+      'search.provider is "pagefind" but the "pagefind" package is not installed.\n' +
+        'It is an optional dependency of @umami/shiso — install it in your project:\n\n' +
+        '  pnpm add -D pagefind\n',
+    );
+    process.exit(1);
+  }
+
+  throw error;
+}
+
+/** Vite's `base`, normalized to "" or "/prefix". Mirrors prerender.mjs. */
+function readBase(template) {
+  const match = template.match(/<script[^>]+src="([^"]*)\/assets\//);
+  const base = match?.[1] ?? '';
+  return base === '/' ? '' : base;
+}
+
+const template = await readFile(path.join(clientDir, 'index.html'), 'utf8');
+const base = readBase(template);
+const indexRoot = path.join(clientDir, ...base.split('/').filter(Boolean));
+const outputPath = path.join(indexRoot, 'pagefind');
+
+// The permalink "#" appended to every heading (rehype-autolink-headings in
+// mdx.config.ts) must not leak into indexed titles and excerpts.
+const DEFAULT_EXCLUDE_SELECTORS = ['.heading-anchor'];
+
+const searchOptions = search && typeof search === 'object' ? search.options || {} : {};
+const excludeSelectors = [
+  ...DEFAULT_EXCLUDE_SELECTORS,
+  ...(Array.isArray(searchOptions.excludeSelectors) ? searchOptions.excludeSelectors : []),
+];
+
+const { index, errors: createErrors } = await pagefind.createIndex({ excludeSelectors });
+
+if (!index) {
+  console.error(`Pagefind index creation failed:\n${(createErrors || []).join('\n')}`);
+  process.exit(1);
+}
+
+const { page_count, errors } = await index.addDirectory({ path: indexRoot, glob: '**/*.html' });
+
+if (errors?.length) {
+  console.error(`Pagefind indexing failed:\n${errors.join('\n')}`);
+  await pagefind.close();
+  process.exit(1);
+}
+
+if (!page_count) {
+  console.error(
+    'Pagefind indexed 0 pages. Expected prerendered pages with a data-pagefind-body attribute ' +
+      `under ${path.relative(root, indexRoot)}.`,
+  );
+  await pagefind.close();
+  process.exit(1);
+}
+
+const { errors: writeErrors } = await index.writeFiles({ outputPath });
+
+if (writeErrors?.length) {
+  console.error(`Pagefind bundle write failed:\n${writeErrors.join('\n')}`);
+  await pagefind.close();
+  process.exit(1);
+}
+
+await pagefind.close();
+
+// `addDirectory` counts scanned files; the entry manifest counts pages that
+// actually carried `data-pagefind-body` and made it into the index.
+const entry = JSON.parse(await readFile(path.join(outputPath, 'pagefind-entry.json'), 'utf8'));
+const indexedPages = Object.values(entry.languages || {}).reduce(
+  (total, language) => total + (language.page_count || 0),
+  0,
+);
+
+if (!indexedPages) {
+  console.error(
+    'Pagefind indexed 0 pages. Expected prerendered pages with a data-pagefind-body attribute ' +
+      `under ${path.relative(root, indexRoot)}.`,
+  );
+  process.exit(1);
+}
+
+console.log(`Pagefind indexed ${indexedPages} pages into ${path.relative(root, outputPath)}`);

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

package/scripts/vite-docs-config.mjs

@@ -1,17 +1,22 @@
 import path from 'node:path';
 import { loadDocsConfig } from './load-docs-config.mjs';
+import { SHISO_CONFIG_FILES, loadShisoConfig } from './load-shiso-config.mjs';
 
 export const VIRTUAL_DOCS_CONFIG_ID = 'virtual:shiso-docs-config';
+export const VIRTUAL_SHISO_CONFIG_ID = 'virtual:shiso-config';
 const RESOLVED_DOCS_CONFIG_ID = `\0${VIRTUAL_DOCS_CONFIG_ID}`;
+const RESOLVED_SHISO_CONFIG_ID = `\0${VIRTUAL_SHISO_CONFIG_ID}`;
 
 function renderConfigModule(config) {
   return `export default ${JSON.stringify(config)};`;
 }
 
 /**
- * Creates the single docs-config state shared by a Vite build and application
- * modules. The virtual module keeps Node-only file loading out of the browser
- * bundle and gives the later `$ref` resolver one integration point.
+ * Creates the single config state shared by a Vite build and application
+ * modules. Two virtual modules keep Node-only file loading out of the browser
+ * bundle: `virtual:shiso-docs-config` carries docs.json (with `$ref`s
+ * resolved) and `virtual:shiso-config` carries the resolved shiso.config.*
+ * options with defaults already applied.
  */
 export async function createDocsConfigModule({
   root = process.cwd(),
@@ -19,35 +24,69 @@ export async function createDocsConfigModule({
 } = {}) {
   const options = { root, configFile };
   let loaded = await loadDocsConfig(options);
+  let loadedShiso = await loadShisoConfig({ root });
+  // Candidate names are matched in handleHotUpdate (the dev watcher already
+  // covers the project root), so creating shiso.config.ts is picked up live.
+  // Only existing files may go through addWatchFile: Vite's dev import
+  // analysis re-resolves watched files from a load hook and errors on paths
+  // that do not exist.
+  const shisoCandidatePaths = SHISO_CONFIG_FILES.map(name => path.resolve(root, name));
 
   return {
     getConfig: () => loaded.config,
-    getSourcePaths: () => loaded.sourcePaths,
+    getShisoConfig: () => loadedShiso.config,
+    getSourcePaths: () => [...loaded.sourcePaths, ...loadedShiso.sourcePaths],
     sourcePath: loaded.sourcePath,
+    shisoSourcePath: loadedShiso.sourcePath,
     plugin: {
       name: 'shiso-docs-config',
       enforce: 'pre',
       resolveId(id) {
-        return id === VIRTUAL_DOCS_CONFIG_ID ? RESOLVED_DOCS_CONFIG_ID : undefined;
+        if (id === VIRTUAL_DOCS_CONFIG_ID) {
+          return RESOLVED_DOCS_CONFIG_ID;
+        }
+
+        if (id === VIRTUAL_SHISO_CONFIG_ID) {
+          return RESOLVED_SHISO_CONFIG_ID;
+        }
+
+        return undefined;
       },
       load(id) {
-        if (id !== RESOLVED_DOCS_CONFIG_ID) {
-          return undefined;
+        if (id === RESOLVED_DOCS_CONFIG_ID) {
+          for (const sourcePath of loaded.sourcePaths) {
+            this.addWatchFile(sourcePath);
+          }
+          return renderConfigModule(loaded.config);
         }
 
-        for (const sourcePath of loaded.sourcePaths) {
-          this.addWatchFile(sourcePath);
+        if (id === RESOLVED_SHISO_CONFIG_ID) {
+          for (const sourcePath of loadedShiso.sourcePaths) {
+            this.addWatchFile(sourcePath);
+          }
+          return renderConfigModule(loadedShiso.config);
         }
-        return renderConfigModule(loaded.config);
+
+        return undefined;
       },
       async handleHotUpdate(context) {
-        if (!loaded.sourcePaths.includes(path.resolve(context.file))) {
+        const changedPath = path.resolve(context.file);
+        const isDocsSource = loaded.sourcePaths.includes(changedPath);
+        const isShisoSource = shisoCandidatePaths.includes(changedPath);
+
+        if (!isDocsSource && !isShisoSource) {
           return;
         }
 
-        loaded = await loadDocsConfig(options);
+        const resolvedId = isDocsSource ? RESOLVED_DOCS_CONFIG_ID : RESOLVED_SHISO_CONFIG_ID;
+
+        if (isDocsSource) {
+          loaded = await loadDocsConfig(options);
+        } else {
+          loadedShiso = await loadShisoConfig({ root });
+        }
 
-        const configModule = context.server.moduleGraph.getModuleById(RESOLVED_DOCS_CONFIG_ID);
+        const configModule = context.server.moduleGraph.getModuleById(resolvedId);
 
         if (configModule) {
           context.server.moduleGraph.invalidateModule(configModule);

package/src/App.tsx

@@ -11,8 +11,9 @@ import { CodeBlock } from '@/components/CodeBlock';
 import * as docsComponents from '@/components/docs/index';
 import { Layout } from '@/components/Layout';
 import { TooltipProvider } from '@/components/ui/tooltip';
-import { docsHomeUrl, siteModel } from '@/lib/site-config';
+import { docsHomeUrl, hasRootStandalonePage, siteModel, standalonePages } from '@/lib/site-config';
 import { DocPage } from '@/pages/DocPage';
+import { StandalonePageView } from '@/pages/StandalonePage';
 
 const mdxComponents = {
   ...docsComponents,
@@ -26,8 +27,16 @@ export function App() {
       <MDXProvider components={mdxComponents}>
         <Layout site={siteModel}>
           <Routes>
-            {/* When the default scope's landing page is the root there is nothing to redirect. */}
-            {docsHomeUrl !== '/' ? (
+            {standalonePages.map(page => (
+              <Route
+                key={page.path}
+                path={page.path}
+                element={<StandalonePageView page={page} site={siteModel} />}
+              />
+            ))}
+            {/* When the default scope's landing page is the root, or a
+                standalone page owns "/", there is nothing to redirect. */}
+            {docsHomeUrl !== '/' && !hasRootStandalonePage ? (
               <Route path="/" element={<Navigate to={docsHomeUrl} replace />} />
             ) : null}
             <Route path="*" element={<DocPage site={siteModel} />} />

package/src/components/DocContent.tsx

@@ -59,8 +59,9 @@ export interface DocContentProps {
 }
 
 export function DocContent({ page, doc, site }: DocContentProps) {
+  const scope = getScopeForPage(docsSite, page);
   // Prev/next paging never crosses a version or language boundary.
-  const pagerPages = getScopeForPage(docsSite, page).docs.pages.filter(item => !item.hidden);
+  const pagerPages = scope.docs.pages.filter(item => !item.hidden);
   const pageIndex = pagerPages.findIndex(item => item.slug === page.slug);
   const prev = pageIndex > 0 ? pagerPages[pageIndex - 1] : undefined;
   const next = pageIndex >= 0 ? pagerPages[pageIndex + 1] : undefined;
@@ -85,8 +86,21 @@ export function DocContent({ page, doc, site }: DocContentProps) {
     timeZone: 'UTC',
   });
 
+  // Pagefind indexing markers on the prerendered HTML. Inert unless the site
+  // uses the pagefind provider. Hidden pages/scopes mirror the local index's
+  // search visibility rules; the scope filter matches the id Search.tsx sends.
+  const pagefindAttrs =
+    page.hidden || scope.hidden
+      ? {}
+      : {
+          'data-pagefind-body': '',
+          ...(page.scopeId !== 'default'
+            ? { 'data-pagefind-filter': 'scope[data-scope]', 'data-scope': page.scopeId }
+            : {}),
+        };
+
   return (
-    <article className="min-w-0 grow">
+    <article className="min-w-0 grow" {...pagefindAttrs}>
       {eyebrow && <div className="text-sm font-bold text-primary">{eyebrow}</div>}
       <div className="flex items-start justify-between gap-4">
         {title && (
@@ -107,7 +121,7 @@ export function DocContent({ page, doc, site }: DocContentProps) {
         </div>
       )}
       {related.length > 0 && (
-        <nav className="mt-8" aria-label={site.labels.relatedTopics}>
+        <nav className="mt-8" aria-label={site.labels.relatedTopics} data-pagefind-ignore>
           <div className="text-sm text-muted-foreground">{site.labels.relatedTopics}</div>
           <ul className="mt-3 flex flex-col gap-2 text-sm">
             {related.map(({ href, title, external }) => (
@@ -132,7 +146,7 @@ export function DocContent({ page, doc, site }: DocContentProps) {
           </ul>
         </nav>
       )}
-      <div className="mt-8 flex items-center justify-between">
+      <div className="mt-8 flex items-center justify-between" data-pagefind-ignore>
         <NavigationButton {...prev} isPrev />
         <NavigationButton {...next} />
       </div>

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/Search.tsx

@@ -17,6 +17,33 @@ import { resolveSearchProvider, type SearchProvider } from '@/lib/search/provide
 import { getScopeByPathname } from '@/lib/site-config';
 import type { ThemeLabels } from '@/lib/types';
 
+/** Enough results to make the list scroll; the dialog caps its own height. */
+const RESULT_LIMIT = 30;
+
+/**
+ * Renders a snippet, turning provider-supplied `<mark>` tags into highlight
+ * elements. Snippets are parsed — never injected as HTML — so any other
+ * markup in the text renders literally.
+ */
+function renderSnippet(snippet: string) {
+  const parts = snippet.split(/<mark>(.*?)<\/mark>/g);
+
+  if (parts.length === 1) {
+    return snippet;
+  }
+
+  return parts.map((part, index) =>
+    index % 2 ? (
+      // biome-ignore lint/suspicious/noArrayIndexKey: parts are positional and never reorder.
+      <mark key={index} className="rounded-xs bg-primary/15 px-px text-primary">
+        {part}
+      </mark>
+    ) : (
+      part
+    ),
+  );
+}
+
 /**
  * Provider-neutral search dialog. The selected provider and its index or
  * client are loaded on demand, so search stays out of the initial bundle.
@@ -71,7 +98,7 @@ export function Search({ config, labels }: { config: ResolvedSearchConfig; label
         // Search stays inside the version/language scope being browsed.
         // Providers that predate the context argument simply ignore it.
         const scope = getScopeByPathname(pathname);
-        const nextResults = await activeProvider.search(value, undefined, {
+        const nextResults = await activeProvider.search(value, RESULT_LIMIT, {
           scopeId: scope.id,
           language: scope.language,
           version: scope.version,
@@ -202,7 +229,7 @@ export function Search({ config, labels }: { config: ResolvedSearchConfig; label
                     </div>
                     {result.snippet && (
                       <div className="mt-[0.15rem] line-clamp-2 text-[0.8rem] text-muted-foreground">
-                        {result.snippet}
+                        {renderSnippet(result.snippet)}
                       </div>
                     )}
                   </CommandItem>

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';