@umami/shiso 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -5,15 +5,12 @@ All notable changes to `@umami/shiso` are documented here. This project follows
 
 ## Unreleased
 
-### Fixed
-
-- Dev server: allow serving raw assets (fonts, images) from Shiso's real
-  install location when the framework is linked from outside the project's
-  workspace root (`link:`/`file:` installs previously returned 403 for
-  bundled font files).
-
 ### Added
 
+- `Link` export from `@umami/shiso/components`: a client-side navigation link
+  bound to Shiso's router, for TSX standalone pages and other app code.
+  Importing `react-router` directly from app code creates a second router
+  instance without Shiso's context, so use this instead.
 - Public `@umami/shiso/components` entry point for importing Shiso's built-in
   content components from TSX standalone pages and other React modules.
 - TSX standalone pages under `content/pages`. Component pages retain Shiso's
@@ -24,7 +21,6 @@ All notable changes to `@umami/shiso` are documented here. This project follows
   descendants) are excluded from `.docs-markdown` typography styles — headings,
   lists, tables, links, and spacing rules — so embedded UI components render
   with their own styles. Guards use `:not(:where(…))` and add no specificity.
-
 - Per-page `search: false` frontmatter to hide the header search control and
   disable its keyboard shortcut on selected docs or standalone pages.
 - Link tabs: a navigation tab may define `href` instead of `groups`/`pages`/
@@ -32,6 +28,19 @@ All notable changes to `@umami/shiso` are documented here. This project follows
   navigation. Internal hrefs route client-side and highlight when active;
   external URLs open in a new browser tab.
 
+### Fixed
+
+- Let standalone page content expand through the layout's flex chain so short
+  pages keep the footer at the bottom of the viewport.
+- Bundle `@umami/shiso` entry points into the SSR build (`ssr.noExternal`) so
+  TSX standalone pages that import `@umami/shiso/components` prerender
+  correctly; previously Node hit the unresolved project-time virtual import
+  `@/lib/icon-registry.generated` inside the published chunks.
+- Dev server: allow serving raw assets (fonts, images) from Shiso's real
+  install location when the framework is linked from outside the project's
+  workspace root (`link:`/`file:` installs previously returned 403 for
+  bundled font files).
+
 ## 2.0.0 - 2026-08-21
 
 ### Breaking

package/dist/chunks/App.js

@@ -1,4 +1,4 @@
-import { $ as POPUP_COLLISION_AVOIDANCE, $n as isLastTraversableNode, $t as listNavigation, A as popupStoreSelectors, An as jsdom, B as useSyncedFloatingRootContext, Bn as EMPTY_OBJECT, Bt as resolveIcon, C as pressableTriggerOpenStateMapping, Cn as activeElement, Ct as inertValue, D as useFocus, Dn as ARROW_LEFT, E as useHoverFloatingInteraction, En as ARROW_DOWN, F as setPopupOpenState, Fn as useTimeout, G as FloatingNode, Gn as useCompositeRootContext, Gt as useCompositeListItem, H as useDismiss, Hn as useButton, Ht as useOpenChangeComplete, I as useImplicitActiveTrigger, In as Button, J as useFloatingParentNodeId, Jn as useStableCallback, Jt as cancelOpen, K as FloatingTree, Kn as mergeProps$1, Kt as useAnimationFrame, L as useOpenStateTransitions, Ln as cn, Lt as Badge, M as FOCUSABLE_POPUP_PROPS, Mn as mac, N as PopupHandleAttachment, Nn as useBaseUiId, O as usePopupHandleStore, On as ARROW_RIGHT, P as attachPreventUnmountOnClose, Pn as useId$1, Q as DROPDOWN_COLLISION_AVOIDANCE, Qn as isHTMLElement, Qt as itemPress, R as usePopupInteractionProps, Rn as useRenderElement, S as popupTransitionStateMapping, Sn as isTypeableCombobox, St as COMPOSITE_KEYS, T as useHoverReferenceInteraction, Tn as getTarget, U as useClick, Un as dispatchClickWithModifiers, Ut as useAnimationsFinished, V as ReactStore, Vn as useMergedRefs, Vt as getIcon, W as FloatingFocusManager, Wn as ownerDocument, Wt as useValueAsRef, X as FloatingTreeStore, Xn as getParentNode, Xt as focusOut, Y as useFloatingTree, Yn as useRefWithInit, Yt as escapeKey, Z as FloatingPortal, Zn as getWindow, Zt as imperativeAction, _n as isListIndexDisabled, _t as CollapsibleContent, a as DialogTitle, an as CompositeList, ar as Link, b as getDisabledMountTransitionStyles, bn as stopEvent, c as useOpenInteractionType, cn as getNextTabbable, d as useScrollLock, dn as isOutsideEvent, dr as useNavigate, en as outsidePress, er as X$1, et as enqueueFocus, f as DialogPortal$1, fn as findNonDisabledListIndex, g as DialogBackdrop, gn as isIndexOutOfListBounds, gt as Collapsible, h as DialogClose, hn as isElementVisible, i as DialogContent$1, in as triggerPress, j as PopupTriggerMap, jn as webkit, k as createInitialPopupStoreState, kn as ARROW_UP, l as DialogTitle$1, ln as getTabbableAfterElement, lr as Routes, m as DialogPopup, mn as getMinListIndex, mt as renderInlineMarkdown, n as ZoomableImage, nn as triggerFocus, nr as Check, nt as fastComponent, o as DialogTrigger, on as addEventListener, or as Navigate, p as InternalBackdrop, pn as getMaxListIndex, q as useFloatingNodeId, qn as useIsoLayoutEffect, qt as createChangeEventDetails, r as Dialog$1, rn as triggerHover, rr as createLucideIcon, rt as fastComponentRef, s as DialogTrigger$1, sn as useDirection, sr as Route, t as docs_exports, tn as siblingOpen, tr as ChevronRight, tt as FocusGuard, u as DialogRoot, un as getTabbableBeforeElement, ur as useLocation, v as TooltipProvider, vn as isVirtualClick, vt as CollapsibleTrigger, w as safePolygon, wn as contains, wt as useCompositeItem, x as useAnchorPositioning, xn as getFloatingFocusElement, y as usePositioner, yn as isVirtualPointerEvent, z as useTriggerDataForwarding, zn as EMPTY_ARRAY } from "./docs.js";
+import { $ as POPUP_COLLISION_AVOIDANCE, $n as isHTMLElement, $t as itemPress, A as popupStoreSelectors, An as ARROW_UP, B as useSyncedFloatingRootContext, Bn as EMPTY_ARRAY, C as pressableTriggerOpenStateMapping, Cn as isTypeableCombobox, Ct as COMPOSITE_KEYS, D as useFocus, Dn as ARROW_DOWN, E as useHoverFloatingInteraction, En as getTarget, F as setPopupOpenState, Fn as useId$1, G as FloatingNode, Gn as ownerDocument, Gt as useValueAsRef, H as useDismiss, Hn as useMergedRefs, Ht as getIcon, I as useImplicitActiveTrigger, In as useTimeout, J as useFloatingParentNodeId, Jn as useIsoLayoutEffect, Jt as createChangeEventDetails, K as FloatingTree, Kn as useCompositeRootContext, Kt as useCompositeListItem, L as useOpenStateTransitions, Ln as Button, M as FOCUSABLE_POPUP_PROPS, Mn as webkit, N as PopupHandleAttachment, Nn as mac, O as usePopupHandleStore, On as ARROW_LEFT, P as attachPreventUnmountOnClose, Pn as useBaseUiId, Q as DROPDOWN_COLLISION_AVOIDANCE, Qn as getWindow, Qt as imperativeAction, R as usePopupInteractionProps, Rn as cn, Rt as Badge, S as popupTransitionStateMapping, Sn as getFloatingFocusElement, T as useHoverReferenceInteraction, Tn as contains, Tt as useCompositeItem, U as useClick, Un as useButton, Ut as useOpenChangeComplete, V as ReactStore, Vn as EMPTY_OBJECT, Vt as resolveIcon, W as FloatingFocusManager, Wn as dispatchClickWithModifiers, Wt as useAnimationsFinished, X as FloatingTreeStore, Xn as useRefWithInit, Xt as escapeKey, Y as useFloatingTree, Yn as useStableCallback, Yt as cancelOpen, Z as FloatingPortal, Zn as getParentNode, Zt as focusOut, _n as isIndexOutOfListBounds, _t as Collapsible, a as DialogTitle, an as triggerPress, b as getDisabledMountTransitionStyles, bn as isVirtualPointerEvent, c as useOpenInteractionType, cn as useDirection, cr as Route, d as useScrollLock, dn as getTabbableBeforeElement, dr as useLocation, en as listNavigation, er as isLastTraversableNode, et as enqueueFocus, f as DialogPortal$1, fn as isOutsideEvent, fr as useNavigate, g as DialogBackdrop, gn as isElementVisible, h as DialogClose, hn as getMinListIndex, ht as renderInlineMarkdown, i as DialogContent$1, in as triggerHover, ir as createLucideIcon, j as PopupTriggerMap, jn as jsdom, k as createInitialPopupStoreState, kn as ARROW_RIGHT, l as DialogTitle$1, ln as getNextTabbable, m as DialogPopup, mn as getMaxListIndex, n as ZoomableImage, nn as siblingOpen, nr as ChevronRight, nt as fastComponent, o as DialogTrigger, on as CompositeList, or as Link, p as InternalBackdrop, pn as findNonDisabledListIndex, q as useFloatingNodeId, qn as mergeProps$1, qt as useAnimationFrame, r as Dialog$1, rn as triggerFocus, rr as Check, rt as fastComponentRef, s as DialogTrigger$1, sn as addEventListener, sr as Navigate, t as docs_exports, tn as outsidePress, tr as X$1, tt as FocusGuard, u as DialogRoot, un as getTabbableAfterElement, ur as Routes, v as TooltipProvider, vn as isListIndexDisabled, vt as CollapsibleContent, w as safePolygon, wn as activeElement, wt as inertValue, x as useAnchorPositioning, xn as stopEvent, y as usePositioner, yn as isVirtualClick, yt as CollapsibleTrigger, z as useTriggerDataForwarding, zn as useRenderElement } from "./docs.js";
 import { n as highlightTerms } from "./search.js";
 import { resolveSearchProvider } from "../search.js";
 import * as React from "react";
@@ -14,6 +14,40 @@ import shiso from "virtual:shiso-config";
 import rawConfig from "virtual:shiso-docs-config";
 import { LAST_MODIFIED } from "@/generated/last-modified";
 
+//#region ../../node_modules/.pnpm/lucide-react@1.28.0_react@19.2.8/node_modules/lucide-react/dist/esm/icons/arrow-left.mjs
+/**
+* @license lucide-react v1.28.0 - ISC
+*
+* This source code is licensed under the ISC license.
+* See the LICENSE file in the root directory of this source tree.
+*/
+const __iconNode$10 = [["path", {
+	d: "m12 19-7-7 7-7",
+	key: "1l729n"
+}], ["path", {
+	d: "M19 12H5",
+	key: "x3x0zl"
+}]];
+const ArrowLeft = createLucideIcon("arrow-left", __iconNode$10);
+
+//#endregion
+//#region ../../node_modules/.pnpm/lucide-react@1.28.0_react@19.2.8/node_modules/lucide-react/dist/esm/icons/arrow-right.mjs
+/**
+* @license lucide-react v1.28.0 - ISC
+*
+* This source code is licensed under the ISC license.
+* See the LICENSE file in the root directory of this source tree.
+*/
+const __iconNode$9 = [["path", {
+	d: "M5 12h14",
+	key: "1ays0h"
+}], ["path", {
+	d: "m12 5 7 7-7 7",
+	key: "xquz4c"
+}]];
+const ArrowRight = createLucideIcon("arrow-right", __iconNode$9);
+
+//#endregion
 //#region ../../node_modules/.pnpm/lucide-react@1.28.0_react@19.2.8/node_modules/lucide-react/dist/esm/icons/copy.mjs
 /**
 * @license lucide-react v1.28.0 - ISC
@@ -4026,11 +4060,24 @@ const DEFAULT_SEARCH_PROMPT = "Search...";
 const DEFAULT_SEARCH_PROVIDER = "local";
 const DEFAULT_SEARCH_SHORTCUT = "k";
 const DEFAULT_SEARCH_SHORTCUT_LABEL = "Ctrl K";
+const DEFAULT_SEARCH_POSITION = "header";
+/** Positions the built-in theme knows how to render. */
+const SEARCH_POSITIONS = ["header", "sidebar"];
+/**
+* Themes must always support "header", so anything unrecognized (or not
+* implemented by the active theme) lands there instead of vanishing.
+*/
+function resolveSearchPosition(position, supported = SEARCH_POSITIONS) {
+	if (typeof position === "string" && supported.includes(position)) return position;
+	if (position !== void 0 && position !== "header") console.warn(`[shiso] Unsupported search.position "${String(position)}" — using "${DEFAULT_SEARCH_POSITION}".`);
+	return DEFAULT_SEARCH_POSITION;
+}
 /** Normalizes docs.json search settings for both the UI and provider loader. */
 function resolveSearchConfig(config) {
 	if (config === false) return {
 		enabled: false,
 		prompt: DEFAULT_SEARCH_PROMPT,
+		position: DEFAULT_SEARCH_POSITION,
 		provider: DEFAULT_SEARCH_PROVIDER,
 		options: {},
 		shortcut: false,
@@ -4039,6 +4086,7 @@ function resolveSearchConfig(config) {
 	return {
 		enabled: true,
 		prompt: config?.prompt?.trim() || "Search...",
+		position: resolveSearchPosition(config?.position),
 		provider: config?.provider?.trim().toLowerCase() || "local",
 		options: config?.options || {},
 		shortcut: config?.shortcut === false ? false : config?.shortcut?.trim().toLowerCase() || "k",
@@ -4060,6 +4108,8 @@ const SHISO_THEME_LABELS = {
 	noResults: "No results",
 	lastUpdated: "Last updated on",
 	relatedTopics: "Related topics",
+	previousPage: "Previous",
+	nextPage: "Next",
 	notFound: "Page not found",
 	dismissBanner: "Dismiss banner",
 	toggleTheme: "Toggle theme",
@@ -7205,7 +7255,7 @@ function renderWithQueryHighlight(text, query) {
 * Provider-neutral search dialog. The selected provider and its index or
 * client are loaded on demand, so search stays out of the initial bundle.
 */
-function Search({ config, labels }) {
+function Search({ config, labels, className }) {
 	const navigate = useNavigate();
 	const { pathname } = useLocation();
 	const [open, setOpen] = useState(false);
@@ -7294,12 +7344,12 @@ function Search({ config, labels }) {
 		children: [/* @__PURE__ */ jsxs(DialogTrigger, {
 			render: /* @__PURE__ */ jsx(Button, {
 				variant: "outline",
-				className: "h-auto gap-2 rounded-md bg-card px-2.5 py-1.5 text-muted-foreground hover:border-input hover:bg-card hover:text-foreground"
+				className: cn("h-auto gap-2 rounded-md bg-card px-2.5 py-1.5 text-muted-foreground hover:border-input hover:bg-card hover:text-foreground", className)
 			}),
 			children: [
 				/* @__PURE__ */ jsx(Search$1, { className: "size-3.5" }),
 				/* @__PURE__ */ jsx("span", {
-					className: "min-w-24 text-left",
+					className: "min-w-24 grow text-left",
 					children: config.prompt
 				}),
 				config.shortcut ? /* @__PURE__ */ jsx("kbd", {
@@ -7348,6 +7398,21 @@ function Search({ config, labels }) {
 		})]
 	});
 }
+/**
+* Renders the search control only when `search.position` targets this slot.
+* Layout components drop one of these into each position they support; the
+* per-page `search: false` frontmatter flag is honored here as well.
+*/
+function SearchSlot({ site, position, className }) {
+	const { pathname } = useLocation();
+	if (!site.search.enabled || site.search.position !== position) return null;
+	if (getPageFrontmatter(pathname)?.search === false) return null;
+	return /* @__PURE__ */ jsx(Search, {
+		config: site.search,
+		labels: site.labels,
+		className
+	});
+}
 
 //#endregion
 //#region src/components/ThemeToggle.tsx
@@ -7527,10 +7592,9 @@ function NavbarLinkItem({ link, primary = false }) {
 	});
 }
 function Header({ site }) {
-	const { logo, navbar, name, appearance, labels, search } = site;
+	const { logo, navbar, name, appearance, labels } = site;
 	const { pathname } = useLocation();
 	const docs = getScopeByPathname(pathname).docs;
-	const showSearch = getPageFrontmatter(pathname)?.search !== false;
 	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]";
@@ -7579,10 +7643,15 @@ function Header({ site }) {
 				/* @__PURE__ */ jsxs("div", {
 					className: "flex min-w-0 items-center gap-2 justify-self-end",
 					children: [
-						showSearch ? /* @__PURE__ */ jsx(Search, {
-							config: search,
-							labels
-						}) : null,
+						/* @__PURE__ */ jsx(SearchSlot, {
+							site,
+							position: "header"
+						}),
+						/* @__PURE__ */ jsx(SearchSlot, {
+							site,
+							position: "sidebar",
+							className: "lg:hidden"
+						}),
 						navbar?.links.map((link) => /* @__PURE__ */ jsx(NavbarLinkItem, { link }, link.href)),
 						!appearance.strict && /* @__PURE__ */ jsx(ThemeToggle, { label: labels.toggleTheme }),
 						navbar?.primary ? /* @__PURE__ */ jsx(NavbarLinkItem, {
@@ -7816,7 +7885,7 @@ function Layout({ children, site }) {
 			/* @__PURE__ */ jsx("div", {
 				className: "mx-auto flex min-h-0 w-full max-w-[1600px] grow flex-col px-5",
 				children: /* @__PURE__ */ jsx("main", {
-					className: "min-h-0 grow",
+					className: "flex min-h-0 grow flex-col",
 					children
 				})
 			})
@@ -8001,30 +8070,44 @@ function DocContent({ page, doc, site }) {
 				})]
 			}),
 			/* @__PURE__ */ jsxs("div", {
-				className: "mt-8 flex items-center justify-between",
+				className: "mt-8 flex items-end justify-between",
 				"data-pagefind-ignore": true,
 				children: [/* @__PURE__ */ jsx(NavigationButton, {
 					...prev,
+					eyebrow: site.labels.previousPage,
 					isPrev: true
-				}), /* @__PURE__ */ jsx(NavigationButton, { ...next })]
+				}), /* @__PURE__ */ jsx(NavigationButton, {
+					...next,
+					eyebrow: site.labels.nextPage
+				})]
 			})
 		]
 	});
 }
-const NavigationButton = ({ label, url, isPrev }) => {
+const NavigationButton = ({ label, url, eyebrow, isPrev }) => {
 	if (!url || !label) return /* @__PURE__ */ jsx("div", {});
 	return /* @__PURE__ */ jsxs(Link, {
 		to: url,
-		className: "group my-3 inline-flex items-center gap-3 text-base font-bold text-foreground",
+		className: cn("group my-3 inline-flex items-end gap-3 text-base text-foreground", { "text-right": !isPrev }),
+		rel: isPrev ? "prev" : "next",
 		children: [
-			isPrev && /* @__PURE__ */ jsx(ChevronRight, {
+			isPrev && /* @__PURE__ */ jsx(ArrowLeft, {
 				size: 14,
-				className: "rotate-180 text-muted-foreground transition-colors group-hover:text-foreground"
+				className: "mb-[0.3rem] text-muted-foreground transition-colors group-hover:text-foreground"
 			}),
-			label,
-			!isPrev && /* @__PURE__ */ jsx(ChevronRight, {
+			/* @__PURE__ */ jsxs("span", {
+				className: "flex flex-col",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "text-xs font-bold text-muted-foreground",
+					children: eyebrow
+				}), /* @__PURE__ */ jsx("span", {
+					className: "font-medium transition-colors group-hover:text-primary",
+					children: label
+				})]
+			}),
+			!isPrev && /* @__PURE__ */ jsx(ArrowRight, {
 				size: 14,
-				className: "text-muted-foreground transition-colors group-hover:text-foreground"
+				className: "mb-[0.3rem] text-muted-foreground transition-colors group-hover:text-foreground"
 			})
 		]
 	});
@@ -8307,7 +8390,7 @@ function SideNav({ tabs, navigation, anchors, activeTabId, isSticky, drilldown,
 	const { pathname } = useLocation();
 	const nodes = navigation[activeTabId] || navigation[tabs[0]?.id] || [];
 	return /* @__PURE__ */ jsx(ScrollArea, {
-		className: cn("w-full max-w-full", { "h-full": isSticky }),
+		className: cn("w-full max-w-full", { "min-h-0 grow": isSticky }),
 		children: /* @__PURE__ */ jsxs("nav", {
 			className: "flex w-full flex-col gap-6 pr-4 text-sm",
 			"aria-label": navigationLabel,
@@ -8462,9 +8545,13 @@ function Docs({ page, doc, site }) {
 			})]
 		}), /* @__PURE__ */ jsxs("div", {
 			className: "flex items-start gap-12 lg:min-h-[calc(100dvh-var(--header-height))] lg:pt-6",
-			children: [/* @__PURE__ */ jsx("div", {
-				className: "hidden min-w-0 max-w-60 basis-60 self-start lg:sticky lg:top-[calc(var(--header-height)+1.5rem)] lg:block lg:h-[calc(100dvh-var(--header-height)-3rem)] lg:shrink-0",
-				children: /* @__PURE__ */ jsx(SideNav, {
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "hidden min-w-0 max-w-60 basis-60 flex-col gap-4 self-start lg:sticky lg:top-[calc(var(--header-height)+1.5rem)] lg:flex lg:h-[calc(100dvh-var(--header-height)-3rem)] lg:shrink-0",
+				children: [/* @__PURE__ */ jsx(SearchSlot, {
+					site,
+					position: "sidebar",
+					className: "w-full"
+				}), /* @__PURE__ */ jsx(SideNav, {
 					tabs,
 					navigation,
 					anchors: scopeDocs.anchors,
@@ -8474,7 +8561,7 @@ function Docs({ page, doc, site }) {
 					navigationLabel: site.labels.documentationNavigation,
 					expandLabel: site.labels.expand,
 					collapseLabel: site.labels.collapse
-				})
+				})]
 			}), /* @__PURE__ */ jsxs("div", {
 				className: "flex min-w-0 grow self-stretch flex-col",
 				children: [/* @__PURE__ */ jsxs("div", {
@@ -8547,7 +8634,7 @@ function StandalonePageView({ page, site }) {
 	const Content = doc.default;
 	const isComponentPage = page.filePath.endsWith(".tsx");
 	return /* @__PURE__ */ jsxs("div", {
-		className: "flex min-h-full flex-col",
+		className: "flex grow flex-col",
 		children: [isComponentPage ? /* @__PURE__ */ jsx("div", {
 			className: "grow",
 			children: /* @__PURE__ */ jsx(Content, {})

package/dist/chunks/docs.js

@@ -2503,7 +2503,7 @@ HistoryRouter.displayName = "unstable_HistoryRouter";
 * @param {LinkProps.defaultShouldRevalidate} props.defaultShouldRevalidate n/a
 * @param {LinkProps.mask} props.mask [modes: framework, data] n/a
 */
-const Link = React$1.forwardRef(function LinkWithRef({ onClick, discover = "render", prefetch = "none", relative, reloadDocument, replace, mask, state, target, to, preventScrollReset, viewTransition, defaultShouldRevalidate, ...rest }, forwardedRef) {
+const Link$1 = React$1.forwardRef(function LinkWithRef({ onClick, discover = "render", prefetch = "none", relative, reloadDocument, replace, mask, state, target, to, preventScrollReset, viewTransition, defaultShouldRevalidate, ...rest }, forwardedRef) {
 	let { basename, navigator, useTransitions } = React$1.useContext(NavigationContext);
 	let isAbsolute = typeof to === "string" && ABSOLUTE_URL_REGEX.test(to);
 	let parsed = parseToInfo(to, basename);
@@ -2544,7 +2544,7 @@ const Link = React$1.forwardRef(function LinkWithRef({ onClick, discover = "rend
 	});
 	return shouldPrefetch && !isAbsolute ? /* @__PURE__ */ React$1.createElement(React$1.Fragment, null, link, /* @__PURE__ */ React$1.createElement(PrefetchPageLinks, { page: href })) : link;
 });
-Link.displayName = "Link";
+Link$1.displayName = "Link";
 /**
 * Wraps {@link Link | `<Link>`} with additional props for styling active and
 * pending states.
@@ -2621,7 +2621,7 @@ const NavLink = React$1.forwardRef(function NavLinkWithRef({ "aria-current": ari
 		isTransitioning ? "transitioning" : null
 	].filter(Boolean).join(" ");
 	let style = typeof styleProp === "function" ? styleProp(renderProps) : styleProp;
-	return /* @__PURE__ */ React$1.createElement(Link, {
+	return /* @__PURE__ */ React$1.createElement(Link$1, {
 		...rest,
 		"aria-current": ariaCurrent,
 		className,
@@ -10182,7 +10182,7 @@ function Button({ href, variant = "default", size = "default", icon, className,
 		rel: "noreferrer",
 		children: content
 	});
-	return /* @__PURE__ */ jsx(Link, {
+	return /* @__PURE__ */ jsx(Link$1, {
 		to: href,
 		className: linkClassName,
 		children: content
@@ -10400,7 +10400,7 @@ function Card({ title, href, icon, color, img, cta, horizontal, arrow, type, chi
 		rel: "noreferrer",
 		children: content
 	});
-	return /* @__PURE__ */ jsx(Link, {
+	return /* @__PURE__ */ jsx(Link$1, {
 		to: href,
 		className: linkClassName,
 		children: content
@@ -11666,6 +11666,18 @@ function Icon({ icon, src, color, size = 16, className }) {
 	});
 }
 
+//#endregion
+//#region src/components/docs/Link.tsx
+/**
+* Client-side navigation link bound to Shiso's router. Exposed from
+* `@umami/shiso/components` so TSX standalone pages and other app code can
+* navigate without reloading (importing `react-router` directly would create a
+* second router instance without Shiso's context).
+*/
+function Link(props) {
+	return /* @__PURE__ */ jsx(Link$1, { ...props });
+}
+
 //#endregion
 //#region src/components/docs/ParamField.tsx
 function ParamField({ name, query, path, header, body, type, required, children }) {
@@ -18901,6 +18913,7 @@ var docs_exports = /* @__PURE__ */ __exportAll({
 	Frame: () => Frame,
 	Icon: () => Icon,
 	Info: () => Info,
+	Link: () => Link,
 	Note: () => Note,
 	Param: () => Param,
 	ParamField: () => ParamField,
@@ -18918,4 +18931,4 @@ var docs_exports = /* @__PURE__ */ __exportAll({
 });
 
 //#endregion
-export { POPUP_COLLISION_AVOIDANCE as $, isLastTraversableNode as $n, listNavigation as $t, popupStoreSelectors as A, jsdom as An, Info as At, useSyncedFloatingRootContext as B, EMPTY_OBJECT as Bn, resolveIcon as Bt, pressableTriggerOpenStateMapping as C, activeElement as Cn, inertValue as Ct, useFocus as D, ARROW_LEFT$1 as Dn, Callout as Dt, useHoverFloatingInteraction as E, ARROW_DOWN$1 as En, CardGroup as Et, setPopupOpenState as F, useTimeout as Fn, Button as Ft, FloatingNode as G, useCompositeRootContext as Gn, useCompositeListItem as Gt, useDismiss as H, useButton as Hn, useOpenChangeComplete as Ht, useImplicitActiveTrigger as I, Button$1 as In, Badge as It, useFloatingParentNodeId as J, useStableCallback as Jn, cancelOpen as Jt, FloatingTree as K, mergeProps as Kn, useAnimationFrame as Kt, useOpenStateTransitions as L, cn as Ln, Badge$1 as Lt, FOCUSABLE_POPUP_PROPS as M, mac as Mn, Tip as Mt, PopupHandleAttachment as N, useBaseUiId as Nn, Warning as Nt, usePopupHandleStore as O, ARROW_RIGHT$1 as On, Check as Ot, attachPreventUnmountOnClose as P, useId as Pn, WarningBanner as Pt, DROPDOWN_COLLISION_AVOIDANCE as Q, isHTMLElement as Qn, itemPress as Qt, usePopupInteractionProps as R, useRenderElement as Rn, Accordion as Rt, popupTransitionStateMapping as S, isTypeableCombobox as Sn, COMPOSITE_KEYS as St, useHoverReferenceInteraction as T, getTarget as Tn, Card as Tt, useClick as U, dispatchClickWithModifiers as Un, useAnimationsFinished as Ut, ReactStore as V, useMergedRefs as Vn, getIcon as Vt, FloatingFocusManager as W, ownerDocument as Wn, useValueAsRef as Wt, FloatingTreeStore as X, getParentNode as Xn, focusOut as Xt, useFloatingTree as Y, useRefWithInit as Yn, escapeKey as Yt, FloatingPortal as Z, getWindow as Zn, imperativeAction as Zt, Tooltip as _, isListIndexDisabled as _n, CollapsibleContent as _t, DialogTitle as a, CompositeList as an, Link as ar, Tabs as at, getDisabledMountTransitionStyles as b, stopEvent as bn, Columns as bt, useOpenInteractionType as c, getNextTabbable as cn, Router as cr, ResponseField as ct, useScrollLock as d, isOutsideEvent as dn, useNavigate as dr, ParamField as dt, outsidePress as en, X as er, enqueueFocus as et, DialogPortal$1 as f, findNonDisabledListIndex as fn, createPath as fr, Icon as ft, DialogBackdrop as g, isIndexOutOfListBounds as gn, Collapsible as gt, DialogClose as h, isElementVisible as hn, Expandable as ht, DialogContent as i, triggerPress as in, BrowserRouter as ir, Tab as it, PopupTriggerMap as j, webkit as jn, Note as jt, createInitialPopupStoreState as k, ARROW_UP$1 as kn, Danger as kt, DialogTitle$1 as l, getTabbableAfterElement as ln, Routes as lr, PropertiesTable as lt, DialogPopup as m, getMinListIndex as mn, ABSOLUTE_URL_REGEX as mr, renderInlineMarkdown as mt, ZoomableImage as n, triggerFocus as nn, Check$1 as nr, fastComponent as nt, DialogTrigger as o, addEventListener as on, Navigate as or, Step as ot, InternalBackdrop as p, getMaxListIndex as pn, parsePath as pr, Frame as pt, useFloatingNodeId as q, useIsoLayoutEffect as qn, createChangeEventDetails as qt, Dialog as r, triggerHover as rn, createLucideIcon as rr, fastComponentRef as rt, DialogTrigger$1 as s, useDirection as sn, Route as sr, Steps as st, docs_exports as t, siblingOpen as tn, ChevronRight as tr, FocusGuard as tt, DialogRoot as u, getTabbableBeforeElement as un, useLocation as ur, Param as ut, TooltipProvider as v, isVirtualClick as vn, CollapsibleTrigger as vt, safePolygon as w, contains as wn, useCompositeItem as wt, useAnchorPositioning as x, getFloatingFocusElement as xn, CodeGroup as xt, usePositioner as y, isVirtualPointerEvent as yn, Column as yt, useTriggerDataForwarding as z, EMPTY_ARRAY$1 as zn, AccordionGroup as zt };
+export { POPUP_COLLISION_AVOIDANCE as $, isHTMLElement as $n, itemPress as $t, popupStoreSelectors as A, ARROW_UP$1 as An, Danger as At, useSyncedFloatingRootContext as B, EMPTY_ARRAY$1 as Bn, AccordionGroup as Bt, pressableTriggerOpenStateMapping as C, isTypeableCombobox as Cn, COMPOSITE_KEYS as Ct, useFocus as D, ARROW_DOWN$1 as Dn, CardGroup as Dt, useHoverFloatingInteraction as E, getTarget as En, Card as Et, setPopupOpenState as F, useId as Fn, WarningBanner as Ft, FloatingNode as G, ownerDocument as Gn, useValueAsRef as Gt, useDismiss as H, useMergedRefs as Hn, getIcon as Ht, useImplicitActiveTrigger as I, useTimeout as In, Button as It, useFloatingParentNodeId as J, useIsoLayoutEffect as Jn, createChangeEventDetails as Jt, FloatingTree as K, useCompositeRootContext as Kn, useCompositeListItem as Kt, useOpenStateTransitions as L, Button$1 as Ln, Badge as Lt, FOCUSABLE_POPUP_PROPS as M, webkit as Mn, Note as Mt, PopupHandleAttachment as N, mac as Nn, Tip as Nt, usePopupHandleStore as O, ARROW_LEFT$1 as On, Callout as Ot, attachPreventUnmountOnClose as P, useBaseUiId as Pn, Warning as Pt, DROPDOWN_COLLISION_AVOIDANCE as Q, getWindow as Qn, imperativeAction as Qt, usePopupInteractionProps as R, cn as Rn, Badge$1 as Rt, popupTransitionStateMapping as S, getFloatingFocusElement as Sn, CodeGroup as St, useHoverReferenceInteraction as T, contains as Tn, useCompositeItem as Tt, useClick as U, useButton as Un, useOpenChangeComplete as Ut, ReactStore as V, EMPTY_OBJECT as Vn, resolveIcon as Vt, FloatingFocusManager as W, dispatchClickWithModifiers as Wn, useAnimationsFinished as Wt, FloatingTreeStore as X, useRefWithInit as Xn, escapeKey as Xt, useFloatingTree as Y, useStableCallback as Yn, cancelOpen as Yt, FloatingPortal as Z, getParentNode as Zn, focusOut as Zt, Tooltip as _, isIndexOutOfListBounds as _n, Collapsible as _t, DialogTitle as a, triggerPress as an, BrowserRouter as ar, Tabs as at, getDisabledMountTransitionStyles as b, isVirtualPointerEvent as bn, Column as bt, useOpenInteractionType as c, useDirection as cn, Route as cr, ResponseField as ct, useScrollLock as d, getTabbableBeforeElement as dn, useLocation as dr, ParamField as dt, listNavigation as en, isLastTraversableNode as er, enqueueFocus as et, DialogPortal$1 as f, isOutsideEvent as fn, useNavigate as fr, Link as ft, DialogBackdrop as g, isElementVisible as gn, Expandable as gt, DialogClose as h, getMinListIndex as hn, ABSOLUTE_URL_REGEX as hr, renderInlineMarkdown as ht, DialogContent as i, triggerHover as in, createLucideIcon as ir, Tab as it, PopupTriggerMap as j, jsdom as jn, Info as jt, createInitialPopupStoreState as k, ARROW_RIGHT$1 as kn, Check as kt, DialogTitle$1 as l, getNextTabbable as ln, Router as lr, PropertiesTable as lt, DialogPopup as m, getMaxListIndex as mn, parsePath as mr, Frame as mt, ZoomableImage as n, siblingOpen as nn, ChevronRight as nr, fastComponent as nt, DialogTrigger as o, CompositeList as on, Link$1 as or, Step as ot, InternalBackdrop as p, findNonDisabledListIndex as pn, createPath as pr, Icon as pt, useFloatingNodeId as q, mergeProps as qn, useAnimationFrame as qt, Dialog as r, triggerFocus as rn, Check$1 as rr, fastComponentRef as rt, DialogTrigger$1 as s, addEventListener as sn, Navigate as sr, Steps as st, docs_exports as t, outsidePress as tn, X as tr, FocusGuard as tt, DialogRoot as u, getTabbableAfterElement as un, Routes as ur, Param as ut, TooltipProvider as v, isListIndexDisabled as vn, CollapsibleContent as vt, safePolygon as w, activeElement as wn, inertValue as wt, useAnchorPositioning as x, stopEvent as xn, Columns as xt, usePositioner as y, isVirtualClick as yn, CollapsibleTrigger as yt, useTriggerDataForwarding as z, useRenderElement as zn, Accordion as zt };

package/dist/components.js

@@ -1,3 +1,3 @@
-import { At as Info, Dt as Callout, Et as CardGroup, Ft as Button, It as Badge, Mt as Tip, Nt as Warning, Ot as Check, Pt as WarningBanner, Rt as Accordion, Tt as Card, _ as Tooltip, at as Tabs, bt as Columns, ct as ResponseField, dt as ParamField, ft as Icon, ht as Expandable, it as Tab, jt as Note, kt as Danger, lt as PropertiesTable, n as ZoomableImage, ot as Step, pt as Frame, st as Steps, ut as Param, xt as CodeGroup, yt as Column, zt as AccordionGroup } from "./chunks/docs.js";
+import { At as Danger, Bt as AccordionGroup, Dt as CardGroup, Et as Card, Ft as WarningBanner, It as Button, Lt as Badge, Mt as Note, Nt as Tip, Ot as Callout, Pt as Warning, St as CodeGroup, _ as Tooltip, at as Tabs, bt as Column, ct as ResponseField, dt as ParamField, ft as Link, gt as Expandable, it as Tab, jt as Info, kt as Check, lt as PropertiesTable, mt as Frame, n as ZoomableImage, ot as Step, pt as Icon, st as Steps, ut as Param, xt as Columns, zt as Accordion } from "./chunks/docs.js";
 
-export { Accordion, AccordionGroup, Badge, Button, Callout, Card, CardGroup, Check, CodeGroup, Column, Columns, Danger, Expandable, Frame, Icon, Info, Note, Param, ParamField, PropertiesTable, ResponseField, Step, Steps, Tab, Tabs, Tip, Tooltip, Warning, WarningBanner, ZoomableImage };
+export { Accordion, AccordionGroup, Badge, Button, Callout, Card, CardGroup, Check, CodeGroup, Column, Columns, Danger, Expandable, Frame, Icon, Info, Link, Note, Param, ParamField, PropertiesTable, ResponseField, Step, Steps, Tab, Tabs, Tip, Tooltip, Warning, WarningBanner, ZoomableImage };

package/dist/entry-client.js

@@ -1,4 +1,4 @@
-import { ir as BrowserRouter } from "./chunks/docs.js";
+import { ar as BrowserRouter } from "./chunks/docs.js";
 import { m as BASE_URL, t as App } from "./chunks/App.js";
 import { jsx } from "react/jsx-runtime";
 

package/dist/entry-server.js

@@ -1,4 +1,4 @@
-import { cr as Router, fr as createPath, mr as ABSOLUTE_URL_REGEX, pr as parsePath } from "./chunks/docs.js";
+import { hr as ABSOLUTE_URL_REGEX, lr as Router, mr as parsePath, pr as createPath } from "./chunks/docs.js";
 import { a as docsSite, c as getSeo, d as getDocModule, f as getLastModified, h as toAbsoluteUrl, i as docsHomeUrl, l as siteName, m as BASE_URL, n as buildHead, o as getLocaleByPathname, p as getScopeForPage, r as renderHeadToString, s as getRedirects, t as App, u as standalonePages } from "./chunks/App.js";
 import * as React$1 from "react";
 import { jsx } from "react/jsx-runtime";

package/docs.schema.json

@@ -279,6 +279,14 @@
               "allOf": [{ "$ref": "#/definitions/stringValue" }],
               "description": "Placeholder text for the search input."
             },
+            "position": {
+              "anyOf": [
+                { "type": "string", "enum": ["header", "sidebar"] },
+                { "$ref": "#/definitions/configRefValue" }
+              ],
+              "default": "header",
+              "description": "Where the search control renders: \"header\" (right side of the header) or \"sidebar\" (top of the navigation column; stays in the header on small screens). Themes that do not support a position fall back to \"header\"."
+            },
             "provider": {
               "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
               "description": "Search provider id: \"local\" (default), \"pagefind\", or a provider registered at runtime."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umami/shiso",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {

package/src/components/DocContent.tsx

@@ -1,12 +1,13 @@
 import { Link } from 'react-router';
 import { ContextualMenu } from '@/components/ContextualMenu';
-import { ChevronRight, FileText } from '@/components/icons';
+import { ArrowLeft, ArrowRight, FileText } from '@/components/icons';
 import { getLastModified } from '@/lib/content';
 import { getScopeForPage } from '@/lib/docs-config';
 import { resolveLocale } from '@/lib/locale';
 import { docsSite, getPageByPathname } from '@/lib/site-config';
 import { resolveContextualOptions } from '@/lib/site-model';
 import type { DocModule, NormalizedDocsPage, RelatedEntry, SiteModel } from '@/lib/types';
+import { cn } from '@/lib/utils';
 
 interface RelatedLink {
   href: string;
@@ -148,9 +149,9 @@ export function DocContent({ page, doc, site }: DocContentProps) {
           </ul>
         </nav>
       )}
-      <div className="mt-8 flex items-center justify-between" data-pagefind-ignore>
-        <NavigationButton {...prev} isPrev />
-        <NavigationButton {...next} />
+      <div className="mt-8 flex items-end justify-between" data-pagefind-ignore>
+        <NavigationButton {...prev} eyebrow={site.labels.previousPage} isPrev />
+        <NavigationButton {...next} eyebrow={site.labels.nextPage} />
       </div>
     </article>
   );
@@ -159,10 +160,13 @@ export function DocContent({ page, doc, site }: DocContentProps) {
 const NavigationButton = ({
   label,
   url,
+  eyebrow,
   isPrev,
 }: {
   label?: string;
   url?: string;
+  /** Direction caption ("Previous" / "Next") shown above the page title. */
+  eyebrow: string;
   isPrev?: boolean;
 }) => {
   if (!url || !label) {
@@ -172,19 +176,25 @@ const NavigationButton = ({
   return (
     <Link
       to={url}
-      className="group my-3 inline-flex items-center gap-3 text-base font-bold text-foreground"
+      className={cn('group my-3 inline-flex items-end gap-3 text-base text-foreground', {
+        'text-right': !isPrev,
+      })}
+      rel={isPrev ? 'prev' : 'next'}
     >
       {isPrev && (
-        <ChevronRight
+        <ArrowLeft
           size={14}
-          className="rotate-180 text-muted-foreground transition-colors group-hover:text-foreground"
+          className="mb-[0.3rem] text-muted-foreground transition-colors group-hover:text-foreground"
         />
       )}
-      {label}
+      <span className="flex flex-col">
+        <span className="text-xs font-bold text-muted-foreground">{eyebrow}</span>
+        <span className="font-medium transition-colors group-hover:text-primary">{label}</span>
+      </span>
       {!isPrev && (
-        <ChevronRight
+        <ArrowRight
           size={14}
-          className="text-muted-foreground transition-colors group-hover:text-foreground"
+          className="mb-[0.3rem] text-muted-foreground transition-colors group-hover:text-foreground"
         />
       )}
     </Link>

package/src/components/Docs.tsx

@@ -5,6 +5,7 @@ import { Footer } from '@/components/Footer';
 import { Menu } from '@/components/icons';
 import { LanguageSwitcher } from '@/components/LanguageSwitcher';
 import { PageLinks } from '@/components/PageLinks';
+import { SearchSlot } from '@/components/Search';
 import { SideNav } from '@/components/SideNav';
 import { Button } from '@/components/ui/button';
 import { Sheet, SheetContent, SheetTitle, SheetTrigger } from '@/components/ui/sheet';
@@ -104,7 +105,8 @@ export function Docs({ page, doc, site }: DocsProps) {
         </SheetContent>
       </Sheet>
       <div className="flex items-start gap-12 lg:min-h-[calc(100dvh-var(--header-height))] lg:pt-6">
-        <div className="hidden min-w-0 max-w-60 basis-60 self-start lg:sticky lg:top-[calc(var(--header-height)+1.5rem)] lg:block lg:h-[calc(100dvh-var(--header-height)-3rem)] lg:shrink-0">
+        <div className="hidden min-w-0 max-w-60 basis-60 flex-col gap-4 self-start lg:sticky lg:top-[calc(var(--header-height)+1.5rem)] lg:flex lg:h-[calc(100dvh-var(--header-height)-3rem)] lg:shrink-0">
+          <SearchSlot site={site} position="sidebar" className="w-full" />
           <SideNav
             tabs={tabs}
             navigation={navigation}

package/src/components/Header.tsx

@@ -1,17 +1,12 @@
 import { Link, useLocation } from 'react-router';
 import { ConfiguredIcon } from '@/components/ConfiguredIcon';
 import { LanguageSwitcher } from '@/components/LanguageSwitcher';
-import { Search } from '@/components/Search';
+import { SearchSlot } from '@/components/Search';
 import { ThemeToggle } from '@/components/ThemeToggle';
 import { TopNav } from '@/components/TopNav';
 import { VersionSwitcher } from '@/components/VersionSwitcher';
 import { isExternalHref } from '@/lib/paths';
-import {
-  docsHomeUrl,
-  getPageFrontmatter,
-  getScopeByPathname,
-  hasRootStandalonePage,
-} from '@/lib/site-config';
+import { docsHomeUrl, getScopeByPathname, hasRootStandalonePage } from '@/lib/site-config';
 import type { NormalizedLink, SiteModel } from '@/lib/types';
 
 /**
@@ -63,11 +58,10 @@ function NavbarLinkItem({ link, primary = false }: { link: NormalizedLink; prima
 }
 
 export function Header({ site }: { site: SiteModel }) {
-  const { logo, navbar, name, appearance, labels, search } = site;
+  const { logo, navbar, name, appearance, labels } = site;
   const { pathname } = useLocation();
   // The header renders the navigation of whichever scope owns the current page.
   const docs = getScopeByPathname(pathname).docs;
-  const showSearch = getPageFrontmatter(pathname)?.search !== false;
   // The brand links to the standalone home page when one owns "/".
   const brandHref = logo?.href || (hasRootStandalonePage ? '/' : docsHomeUrl);
   const hasBrand = !!name || !!logo?.light || !!logo?.dark;
@@ -120,7 +114,10 @@ export function Header({ site }: { site: SiteModel }) {
           {docs.showTabs ? <TopNav docs={docs} label={labels.sections} /> : null}
         </div>
         <div className="flex min-w-0 items-center gap-2 justify-self-end">
-          {showSearch ? <Search config={search} labels={labels} /> : null}
+          <SearchSlot site={site} position="header" />
+          {/* The sidebar collapses into a sheet on small screens, so its
+              search control moves up here until the column is visible. */}
+          <SearchSlot site={site} position="sidebar" className="lg:hidden" />
           {navbar?.links.map(link => (
             <NavbarLinkItem key={link.href} link={link} />
           ))}

package/src/components/Layout.tsx

@@ -17,7 +17,7 @@ export function Layout({ children, site }: { children: ReactNode; site: SiteMode
       <Banner banner={site.banner} dismissLabel={site.labels.dismissBanner} />
       <Header site={site} />
       <div className="mx-auto flex min-h-0 w-full max-w-[1600px] grow flex-col px-5">
-        <main className="min-h-0 grow">{children}</main>
+        <main className="flex min-h-0 grow flex-col">{children}</main>
       </div>
     </div>
   );

package/src/components/Search.tsx

@@ -14,8 +14,9 @@ import { Dialog, DialogContent, DialogTitle, DialogTrigger } from '@/components/
 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';
-import type { ThemeLabels } from '@/lib/types';
+import { getPageFrontmatter, getScopeByPathname } from '@/lib/site-config';
+import type { SearchPosition, SiteModel, ThemeLabels } from '@/lib/types';
+import { cn } from '@/lib/utils';
 
 /** Enough results to make the list scroll; the dialog caps its own height. */
 const RESULT_LIMIT = 30;
@@ -54,7 +55,16 @@ function renderWithQueryHighlight(text: string, query: string) {
  * Provider-neutral search dialog. The selected provider and its index or
  * client are loaded on demand, so search stays out of the initial bundle.
  */
-export function Search({ config, labels }: { config: ResolvedSearchConfig; labels: ThemeLabels }) {
+export function Search({
+  config,
+  labels,
+  className,
+}: {
+  config: ResolvedSearchConfig;
+  labels: ThemeLabels;
+  /** Extra classes for the trigger button (e.g. to stretch it in a column). */
+  className?: string;
+}) {
   const navigate = useNavigate();
   const { pathname } = useLocation();
   const [open, setOpen] = useState(false);
@@ -179,12 +189,15 @@ export function Search({ config, labels }: { config: ResolvedSearchConfig; label
         render={
           <Button
             variant="outline"
-            className="h-auto gap-2 rounded-md bg-card px-2.5 py-1.5 text-muted-foreground hover:border-input hover:bg-card hover:text-foreground"
+            className={cn(
+              'h-auto gap-2 rounded-md bg-card px-2.5 py-1.5 text-muted-foreground hover:border-input hover:bg-card hover:text-foreground',
+              className,
+            )}
           />
         }
       >
         <SearchIcon className="size-3.5" />
-        <span className="min-w-24 text-left">{config.prompt}</span>
+        <span className="min-w-24 grow text-left">{config.prompt}</span>
         {config.shortcut ? (
           <kbd className="rounded-sm border border-border bg-muted px-[0.3rem] py-[0.05rem] text-[0.7rem] font-sans">
             {config.shortcutLabel}
@@ -253,3 +266,30 @@ export function Search({ config, labels }: { config: ResolvedSearchConfig; label
     </Dialog>
   );
 }
+
+/**
+ * Renders the search control only when `search.position` targets this slot.
+ * Layout components drop one of these into each position they support; the
+ * per-page `search: false` frontmatter flag is honored here as well.
+ */
+export function SearchSlot({
+  site,
+  position,
+  className,
+}: {
+  site: SiteModel;
+  position: SearchPosition;
+  className?: string;
+}) {
+  const { pathname } = useLocation();
+
+  if (!site.search.enabled || site.search.position !== position) {
+    return null;
+  }
+
+  if (getPageFrontmatter(pathname)?.search === false) {
+    return null;
+  }
+
+  return <Search config={site.search} labels={site.labels} className={className} />;
+}

package/src/components/SideNav.tsx

@@ -1,4 +1,3 @@
-import { cn } from '@/lib/utils';
 import { type ReactNode, useEffect, useState } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router';
 import { resolveIcon } from '@/components/docs/utils';
@@ -9,9 +8,9 @@ import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/component
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { flattenNav, isNodeHidden } from '@/lib/docs-config';
 import type { DocsTab, NavGroupNode, NavNode } from '@/lib/types';
+import { cn } from '@/lib/utils';
 
-const sectionLabelClass =
-  'flex min-w-0 items-center gap-[0.4rem] pb-2 pr-1 font-bold text-inherit';
+const sectionLabelClass = 'flex min-w-0 items-center gap-[0.4rem] pb-2 pr-1 font-bold text-inherit';
 const groupLabelClass =
   'flex min-w-0 items-center gap-[0.4rem] py-2 pl-3 pr-1 font-medium text-inherit';
 const selectedClass =
@@ -319,7 +318,7 @@ export function SideNav({
   const nodes = navigation[activeTabId] || navigation[tabs[0]?.id] || [];
 
   return (
-    <ScrollArea className={cn('w-full max-w-full', { 'h-full': isSticky })}>
+    <ScrollArea className={cn('w-full max-w-full', { 'min-h-0 grow': isSticky })}>
       <nav className="flex w-full flex-col gap-6 pr-4 text-sm" aria-label={navigationLabel}>
         {anchors.length ? (
           <NavNodes

package/src/components/docs/Link.tsx

@@ -0,0 +1,14 @@
+import type { ComponentProps } from 'react';
+import { Link as RouterLink } from 'react-router';
+
+export type LinkProps = ComponentProps<typeof RouterLink>;
+
+/**
+ * Client-side navigation link bound to Shiso's router. Exposed from
+ * `@umami/shiso/components` so TSX standalone pages and other app code can
+ * navigate without reloading (importing `react-router` directly would create a
+ * second router instance without Shiso's context).
+ */
+export function Link(props: LinkProps) {
+  return <RouterLink {...props} />;
+}

package/src/components/docs/index.ts

@@ -8,6 +8,7 @@ export * from './Columns';
 export * from './Expandable';
 export * from './Frame';
 export * from './Icon';
+export * from './Link';
 export * from './ParamField';
 export * from './PropertiesTable';
 export * from './ResponseField';

package/src/components/icons/index.ts

@@ -1,4 +1,6 @@
 export {
+  ArrowLeft,
+  ArrowRight,
   Check,
   Check as CheckIcon,
   ChevronRight,

package/src/lib/search/config.ts

@@ -1,13 +1,39 @@
-import type { SearchConfig } from '@/lib/types';
+import type { SearchConfig, SearchPosition } from '@/lib/types';
 
 export const DEFAULT_SEARCH_PROMPT = 'Search...';
 export const DEFAULT_SEARCH_PROVIDER = 'local';
 export const DEFAULT_SEARCH_SHORTCUT = 'k';
 export const DEFAULT_SEARCH_SHORTCUT_LABEL = 'Ctrl K';
+export const DEFAULT_SEARCH_POSITION: SearchPosition = 'header';
+
+/** Positions the built-in theme knows how to render. */
+export const SEARCH_POSITIONS: readonly SearchPosition[] = ['header', 'sidebar'];
+
+/**
+ * Themes must always support "header", so anything unrecognized (or not
+ * implemented by the active theme) lands there instead of vanishing.
+ */
+export function resolveSearchPosition(
+  position: unknown,
+  supported: readonly SearchPosition[] = SEARCH_POSITIONS,
+): SearchPosition {
+  if (typeof position === 'string' && (supported as readonly string[]).includes(position)) {
+    return position as SearchPosition;
+  }
+
+  if (position !== undefined && position !== DEFAULT_SEARCH_POSITION) {
+    console.warn(
+      `[shiso] Unsupported search.position "${String(position)}" — using "${DEFAULT_SEARCH_POSITION}".`,
+    );
+  }
+
+  return DEFAULT_SEARCH_POSITION;
+}
 
 export interface ResolvedSearchConfig {
   enabled: boolean;
   prompt: string;
+  position: SearchPosition;
   provider: string;
   options: Record<string, unknown>;
   shortcut: string | false;
@@ -22,6 +48,7 @@ export function resolveSearchConfig(
     return {
       enabled: false,
       prompt: DEFAULT_SEARCH_PROMPT,
+      position: DEFAULT_SEARCH_POSITION,
       provider: DEFAULT_SEARCH_PROVIDER,
       options: {},
       shortcut: false,
@@ -32,6 +59,7 @@ export function resolveSearchConfig(
   return {
     enabled: true,
     prompt: config?.prompt?.trim() || DEFAULT_SEARCH_PROMPT,
+    position: resolveSearchPosition(config?.position),
     provider: config?.provider?.trim().toLowerCase() || DEFAULT_SEARCH_PROVIDER,
     options: config?.options || {},
     shortcut:

package/src/lib/site-model.ts

@@ -29,6 +29,8 @@ const SHISO_THEME_LABELS: ThemeLabels = {
   noResults: 'No results',
   lastUpdated: 'Last updated on',
   relatedTopics: 'Related topics',
+  previousPage: 'Previous',
+  nextPage: 'Next',
   notFound: 'Page not found',
   dismissBanner: 'Dismiss banner',
   toggleTheme: 'Toggle theme',

package/src/lib/types.ts

@@ -255,9 +255,20 @@ export interface FontsConfig extends FontSpec {
   body?: FontSpec;
 }
 
+/**
+ * Named slots a theme can place the search control in. Every theme must
+ * support "header"; unsupported positions fall back to it.
+ */
+export type SearchPosition = 'header' | 'sidebar';
+
 export interface SearchConfig {
   /** Placeholder text for the search input. */
   prompt?: string;
+  /**
+   * Where the search control renders: "header" (default, right side of the
+   * header) or "sidebar" (top of the navigation column).
+   */
+  position?: SearchPosition;
   /** Provider id: "local" (default), "pagefind", or a runtime-registered id. */
   provider?: string;
   /** Provider-specific configuration. */
@@ -487,6 +498,8 @@ export interface ThemeLabels {
   noResults: string;
   lastUpdated: string;
   relatedTopics: string;
+  previousPage: string;
+  nextPage: string;
   notFound: string;
   dismissBanner: string;
   toggleTheme: string;
@@ -555,7 +568,7 @@ export interface DocFrontmatter {
   title?: string;
   description?: string;
   noindex?: boolean;
-  /** Hide the header search control and disable its shortcut on this page. */
+  /** Hide the search control and disable its shortcut on this page. */
   search?: false;
   /** Overrides the site-wide `metadata.timestamp` setting for this page. */
   timestamp?: boolean;

package/src/pages/StandalonePage.tsx

@@ -31,7 +31,7 @@ export function StandalonePageView({ page, site }: { page: StandalonePage; site:
   const isComponentPage = page.filePath.endsWith('.tsx');
 
   return (
-    <div className="flex min-h-full flex-col">
+    <div className="flex grow flex-col">
       {isComponentPage ? (
         <div className="grow">
           <Content />

package/types/components.d.ts

@@ -1,4 +1,5 @@
-import type { ImgHTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { ComponentProps, ImgHTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { Link as RouterLink } from 'react-router';
 
 export interface AccordionProps {
   title?: ReactNode;
@@ -215,3 +216,7 @@ export interface ZoomableImageProps extends ImgHTMLAttributes<HTMLImageElement>
 }
 
 export declare function ZoomableImage(props: ZoomableImageProps): ReactElement;
+
+/** Client-side navigation link bound to Shiso's router. */
+export type LinkProps = ComponentProps<typeof RouterLink>;
+export declare function Link(props: LinkProps): ReactElement;

package/vite.config.ts

@@ -434,6 +434,13 @@ export default defineConfig(async () => {
       // virtual imports that are resolved by the plugins below.
       exclude: ['@umami/shiso'],
     },
+    ssr: {
+      // App code may import framework entry points directly (e.g.
+      // "@umami/shiso/components" from TSX standalone pages). Bundle them in
+      // the SSR build so project-time virtual imports resolve through the
+      // aliases below instead of failing in Node during prerender.
+      noExternal: ['@umami/shiso'],
+    },
     plugins: [
       configModule.plugin,
       tailwindcss(),