@umami/shiso 1.4.0 → 1.6.0

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

@@ -1,6 +1,4 @@
-import '@fontsource/inter/400.css';
-import '@fontsource/inter/700.css';
-import '@fontsource/inter/800.css';
+import '@fontsource-variable/inter/index.css';
 import '@fontsource/jetbrains-mono/400.css';
 import 'highlight.js/styles/github.css';
 import '@umami/shiso/styles.css';
@@ -11,8 +9,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 +25,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

@@ -101,16 +101,18 @@ export function DocContent({ page, doc, site }: DocContentProps) {
 
   return (
     <article className="min-w-0 grow" {...pagefindAttrs}>
-      {eyebrow && <div className="text-sm font-bold text-primary">{eyebrow}</div>}
+      {eyebrow && <div className="text-sm font-medium text-primary">{eyebrow}</div>}
       <div className="flex items-start justify-between gap-4">
         {title && (
-          <h1 className="mt-2 text-4xl text-foreground leading-[1.2] tracking-[-0.03em] [font-family:var(--font-heading)] [font-weight:var(--font-heading-weight,800)]">
+          <h1 className="mt-2 text-4xl text-foreground leading-[1.2] tracking-[-0.03em] [font-family:var(--font-heading)] [font-weight:var(--font-heading-weight,700)]">
             {title}
           </h1>
         )}
         <ContextualMenu options={contextualOptions} labels={site.labels} />
       </div>
-      {description && <p className="mt-1 mb-6 text-base text-muted-foreground">{description}</p>}
+      {description && (
+        <p className="mt-3 mb-8 text-lg text-muted-foreground leading-relaxed">{description}</p>
+      )}
       <div className="docs-markdown">
         <Content />
       </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

@@ -11,7 +11,7 @@ import {
   CommandList,
 } from '@/components/ui/command';
 import { Dialog, DialogContent, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
-import type { SearchResult } from '@/lib/search';
+import { highlightTerms, type SearchResult } from '@/lib/search';
 import type { ResolvedSearchConfig } from '@/lib/search/config';
 import { resolveSearchProvider, type SearchProvider } from '@/lib/search/provider';
 import { getScopeByPathname } from '@/lib/site-config';
@@ -44,6 +44,12 @@ function renderSnippet(snippet: string) {
   );
 }
 
+function renderWithQueryHighlight(text: string, query: string) {
+  const terms = query.trim().split(/\s+/).filter(Boolean);
+  if (!terms.length) return text;
+  return renderSnippet(highlightTerms(text, terms));
+}
+
 /**
  * Provider-neutral search dialog. The selected provider and its index or
  * client are loaded on demand, so search stays out of the initial bundle.
@@ -224,8 +230,13 @@ export function Search({ config, labels }: { config: ResolvedSearchConfig; label
                     onSelect={() => select(result)}
                   >
                     <div className="text-[0.9rem] font-semibold text-foreground">
-                      {result.page}
-                      {result.heading ? ` › ${result.heading}` : ''}
+                      {renderWithQueryHighlight(result.page, query)}
+                      {result.heading ? (
+                        <>
+                          {' › '}
+                          {renderWithQueryHighlight(result.heading, query)}
+                        </>
+                      ) : null}
                     </div>
                     {result.snippet && (
                       <div className="mt-[0.15rem] line-clamp-2 text-[0.8rem] text-muted-foreground">

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

@@ -24,16 +24,16 @@ export function PropertiesTable({ children }: PropertiesTableProps) {
 
   return (
     <div className="my-4 overflow-x-auto rounded-lg border border-border px-6 py-2">
-      <table className="m-0 min-w-[40rem] table-fixed border-collapse">
+      <table className="m-0 min-w-[40rem] table-fixed border-collapse border-0">
         <thead>
           <tr>
-            <th className="w-1/3 border-x-0 border-t-0 border-b border-border bg-transparent px-0 py-2 pr-6 text-left text-sm font-semibold text-foreground">
+            <th className="w-1/5 border-x-0 border-t-0 border-b border-border bg-transparent px-0 py-2 pr-6 text-left text-sm font-semibold text-foreground">
               Name
             </th>
-            <th className="w-1/3 border-x-0 border-t-0 border-b border-border bg-transparent px-0 py-2 pr-6 text-left text-sm font-semibold text-foreground">
+            <th className="w-1/4 border-x-0 border-t-0 border-b border-border bg-transparent px-0 py-2 pr-6 text-left text-sm font-semibold text-foreground">
               Type
             </th>
-            <th className="w-1/3 border-x-0 border-t-0 border-b border-border bg-transparent px-0 py-2 text-left text-sm font-semibold text-foreground">
+            <th className="border-x-0 border-t-0 border-b border-border bg-transparent px-0 py-2 text-left text-sm font-semibold text-foreground">
               Description
             </th>
           </tr>

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)) {