boltdocs 3.2.1 → 3.3.0

package/dist/client/index.js

@@ -3,21 +3,19 @@
  * Copyright (c) 2026 Jesus Alcala
  * Licensed under the MIT License.
  */
-import { A as Monitor, B as useConfig, E as Languages, F as Sun, H as useBoltdocsContext, I as TextAlignStart, L as X, N as Pencil, R as icons_exports, V as BoltdocsProvider, a as useRoutes, b as FaceGood, d as Check, f as ChevronDown, g as Copy, h as CircleHelp, i as useLocalizedTo, j as Moon, k as Menu, o as normalizePath, r as cn, s as RoutesProvider, t as Link$1, u as ArrowLeft, v as ExternalLink, w as Home, x as FaceRegular, y as FaceBad, z as ConfigContext } from "../link-2PzgTnaP.js";
-import { c as ThemeProvider, l as useTheme } from "../image-Bz87fCla.js";
-import { i as copyToClipboard, n as Timeline, r as useCodeBlock, t as mdx_components_default } from "../mdx-BuO6a1f7.js";
-import { A as useUI, C as useSidebar, D as ButtonGroup, O as Breadcrumbs$2, S as useLocation, T as Menu$1, f as PageNav$1, k as UIProvider, m as OnThisPage$1, n as Sidebar$1, t as DocsLayout$1, w as Tabs$1, x as useSearchHighlight } from "../docs-layout-BdtZ9z6s.js";
-import { i as ErrorBoundary$1, n as Navbar$1, o as Button$1, r as Github } from "../search-dialog-DFnlx8LO.js";
-import { n as useSearch, r as InternalErrorBoundary, t as SearchDialog } from "../search-dialog-BmxHiKwt.js";
+import { A as Languages, B as TextAlignStart, C as FaceBad, F as Moon, K as BoltdocsProvider, L as Pencil, N as Menu, O as Home, P as Monitor, S as ExternalLink, T as FaceRegular, U as ConfigContext, V as X, W as useConfig, _ as ChevronLeft, a as useViewTransition, b as Copy, c as RoutesProvider, d as resolvePublicAssetUrl, g as ChevronDown, h as Check, i as startViewTransition, m as ArrowLeft, o as cn, q as useBoltdocsContext, s as useLocalizedTo, t as Link, u as normalizePath, v as ChevronRight, w as FaceGood, y as CircleHelp, z as Sun } from "../link-CgdI6O2o.js";
+import { A as useRouteData, B as normalizeBasename, C as Outlet, D as useMatches, E as useLocation, F as PrefetchContext, I as RouteDataContext, L as defaultNavigate, M as LocationProvider, N as MatchesContext, O as useNavigate, P as NavigateContext, R as addBasename, S as resolveRouteBranch, T as useLoaderData, V as stripBasename, _ as stripSiteProtocol, a as getConfiguredVersions, b as matchRouteBranch, c as hasUriScheme, d as isConfiguredVersion, f as normalizeUrlBase, g as splitUrlReference, h as resolveUrlReference, i as getConfiguredLocales, j as LocationContext, k as usePrefetch, l as hasUrlBase, m as parseUrlReference, n as buildUrl, o as getVersionPrefixSegments, p as normalizeUrlPath, r as classifyUrlPath, s as getVersionSegments, t as addUrlBase, u as isConfiguredLocale, v as stripUrlBase, w as OutletContext, x as matchRouteBranchWithParams, y as RouteRenderer, z as hasBasename } from "../router-CZBxMRAH.js";
+import { _ as useTheme, g as ThemeProvider } from "../image-B-NDSDuY.js";
+import { a as useCopyButton, i as useExpandable, n as Timeline, o as copyToClipboard, r as useCodeBlockFeedback, t as mdx_components_default } from "../mdx-BRT71V5Q.js";
+import { A as UIProvider, C as IconRenderer, E as Menu$1, O as ButtonGroup, S as useSidebar, T as Tabs$1, f as PageNav$1, j as useUI, k as Breadcrumbs$2, m as OnThisPage$1, n as Sidebar$1, t as DocsLayout$1, w as resolveIcon, x as useSearchHighlight } from "../docs-layout-CbZ7LDRe.js";
+import { i as useRoutes, n as useSearch, r as InternalErrorBoundary, t as SearchDialog } from "../search-dialog-Bp_P1MPP.js";
+import { i as ErrorBoundary$1, n as Navbar$1, o as Button$1, r as Github } from "../search-dialog-BqkzDTq2.js";
 import { ViteReactSSG } from "@bdocs/ssg";
-import { Suspense, createContext, isValidElement, lazy, use, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { Link, Outlet, useLoaderData, useLocation as useLocation$1, useMatches, useNavigate } from "react-router-dom";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Suspense, createContext, isValidElement, lazy, use, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { Button } from "react-aria-components";
 import * as ReactHelmetAsync from "react-helmet-async";
 import virtualCustomComponents from "virtual:boltdocs-mdx-components";
-import virtualIcons from "virtual:boltdocs-icons";
-import DOMPurify from "isomorphic-dompurify";
 import UserLayout from "virtual:boltdocs-layout";
 
 //#region src/client/app/mdx-components-context.tsx
@@ -52,12 +50,13 @@ function MdxComponentsProvider({ components, children }) {
 //#endregion
 //#region src/client/app/scroll-handler.tsx
 /**
-* Handles scroll restoration and hash scrolling on navigation.
-* It ensures the page scrolls to top on pathname changes,
-* or specifically to an anchor element if a hash is present.
+* Handles scroll restoration after navigation.
+*
+* Normal page navigation returns the active content container to the top
+* instantly. Explicit hash navigation is positioned at its anchor instead.
 */
 function ScrollHandler() {
-	const { pathname, hash } = useLocation$1();
+	const { pathname, hash } = useLocation();
 	const handleScroll = (behavior = "auto") => {
 		const container = document.querySelector(".boltdocs-content") || document.querySelector(".boltdocs-external-content") || document.querySelector(".boltdocs-shell-content") || window;
 		const getScrollTop = () => {
@@ -75,7 +74,10 @@ function ScrollHandler() {
 			});
 		};
 		if (hash) {
-			const id = hash.replace("#", "");
+			let id = hash.slice(1);
+			try {
+				id = decodeURIComponent(id);
+			} catch {}
 			const element = document.getElementById(id);
 			if (element) {
 				const offset = 80;
@@ -84,23 +86,43 @@ function ScrollHandler() {
 				return true;
 			}
 		}
-		scrollTo(0, behavior);
+		if (container === window) {
+			document.documentElement.scrollTop = 0;
+			document.body.scrollTop = 0;
+		} else container.scrollTop = 0;
 		return false;
 	};
-	useLayoutEffect(() => {
-		handleScroll("auto");
-	}, [pathname, hash]);
 	useEffect(() => {
-		handleScroll("auto");
+		const handleRouteCommit = (event) => {
+			const detail = event.detail;
+			if (detail?.pathname && detail.pathname !== pathname) return;
+			if (detail?.hash !== void 0 && detail.hash !== hash) return;
+			handleScroll("auto");
+		};
+		window.addEventListener("boltdocs:route-commit", handleRouteCommit);
+		let frame = 0;
+		if (hash) {
+			let attempts = 0;
+			const retry = () => {
+				if (handleScroll("auto") || attempts >= 8) return;
+				attempts++;
+				frame = requestAnimationFrame(retry);
+			};
+			frame = requestAnimationFrame(retry);
+		}
+		return () => {
+			window.removeEventListener("boltdocs:route-commit", handleRouteCommit);
+			if (frame) cancelAnimationFrame(frame);
+		};
 	}, [pathname, hash]);
 	return null;
 }
 
 //#endregion
 //#region src/client/components/ui-base/not-found.tsx
-function NotFound() {
+function NotFound({ className }) {
 	return /* @__PURE__ */ jsx("div", {
-		className: "flex items-center justify-center min-h-[65vh] text-center px-4",
+		className: cn("flex items-center justify-center min-h-[65vh] text-center px-4", className),
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "space-y-6 max-w-md mx-auto p-8 border border-subtle bg-surface rounded-2xl shadow-xs",
 			children: [
@@ -118,7 +140,7 @@ function NotFound() {
 						children: "The page you're looking for doesn't exist or has been moved."
 					})]
 				}),
-				/* @__PURE__ */ jsxs(Link$1, {
+				/* @__PURE__ */ jsxs(Link, {
 					href: "/",
 					className: "inline-flex items-center gap-2 rounded-xl border border-subtle bg-main px-6 py-2.5 text-xs font-semibold text-body hover:bg-primary-50/50 hover:border-primary-500/50 transition-all duration-300 outline-none select-none",
 					children: [/* @__PURE__ */ jsx(ArrowLeft, { size: 14 }), " Go to Home"]
@@ -143,15 +165,14 @@ const mod = ReactHelmetAsync;
 * The `<Helmet>` component, resolved across CJS/ESM module shapes.
 * Falls back to a transparent fragment wrapper if the module cannot be resolved.
 */
-const Helmet = mod.Helmet || mod.default?.Helmet || (({ children }) => /* @__PURE__ */ jsx(Fragment, { children }));
+const Helmet = mod.Helmet || mod.default?.Helmet || (({ children }) => /* @__PURE__ */ jsx(Fragment$1, { children }));
 /**
 * The `<HelmetProvider>` component, resolved across CJS/ESM module shapes.
 * Falls back to a transparent fragment wrapper if the module cannot be resolved.
 */
-const HelmetProvider = mod.HelmetProvider || mod.default?.HelmetProvider || (({ children }) => /* @__PURE__ */ jsx(Fragment, { children }));
+const HelmetProvider = mod.HelmetProvider || mod.default?.HelmetProvider || (({ children }) => /* @__PURE__ */ jsx(Fragment$1, { children }));
 if (typeof globalThis !== "undefined" && globalThis.__BOLTDOCS_SSG_RENDERING__) {
-	const hp = HelmetProvider;
-	if (hp && typeof hp === "function" && hp.canUseDOM) hp.canUseDOM = false;
+	if (typeof HelmetProvider === "function" && HelmetProvider.canUseDOM) HelmetProvider.canUseDOM = false;
 }
 if (typeof globalThis !== "undefined") {
 	globalThis.__BOLTDOCS_HELMET_PROVIDER__ = HelmetProvider;
@@ -175,16 +196,120 @@ function getTranslated(value, locale) {
 	return Object.values(value)[0] || "";
 }
 
+//#endregion
+//#region src/shared/structured-data.ts
+/** Preserve literal JSON-LD types in config files and frontmatter helpers. */
+function defineStructuredData(data) {
+	return data;
+}
+/**
+* Creates one JSON-LD value from the common website/article/breadcrumb presets.
+* Single-node input returns an object; multiple nodes return a graph array.
+*/
+function createStructuredData(options) {
+	const nodes = [];
+	if (options.website) nodes.push(createWebSiteStructuredData(options.website));
+	if (options.article) nodes.push(createArticleStructuredData(options.article));
+	if (options.breadcrumbs?.length) nodes.push(createBreadcrumbStructuredData(options.breadcrumbs));
+	if (options.additional) nodes.push(...Array.isArray(options.additional) ? options.additional : [options.additional]);
+	if (nodes.length === 0) throw new Error("createStructuredData() requires at least one of website, article, breadcrumbs, or additional");
+	return nodes.length === 1 ? nodes[0] : nodes;
+}
+function createWebSiteStructuredData(options) {
+	const data = {
+		"@context": "https://schema.org",
+		"@type": "WebSite",
+		name: options.name,
+		url: options.url
+	};
+	if (options.description) data.description = options.description;
+	if (options.searchUrl) data.potentialAction = {
+		"@type": "SearchAction",
+		target: `${options.searchUrl}{search_term_string}`,
+		"query-input": "required name=search_term_string"
+	};
+	return data;
+}
+function toIsoDate(value, field) {
+	const date = new Date(value);
+	if (Number.isNaN(date.getTime())) throw new TypeError(`Invalid ${field} value: ${String(value)}`);
+	return date.toISOString();
+}
+function createArticleStructuredData(options) {
+	const data = {
+		"@context": "https://schema.org",
+		"@type": "Article",
+		headline: options.headline,
+		url: options.url
+	};
+	if (options.description) data.description = options.description;
+	if (options.datePublished) data.datePublished = toIsoDate(options.datePublished, "datePublished");
+	if (options.dateModified) data.dateModified = toIsoDate(options.dateModified, "dateModified");
+	if (options.image) data.image = options.image;
+	if (options.author) data.author = typeof options.author === "string" ? {
+		"@type": "Person",
+		name: options.author
+	} : {
+		"@type": "Person",
+		...options.author
+	};
+	return data;
+}
+function createBreadcrumbStructuredData(items) {
+	return {
+		"@context": "https://schema.org",
+		"@type": "BreadcrumbList",
+		itemListElement: items.map((item, index) => ({
+			"@type": "ListItem",
+			position: index + 1,
+			name: item.name,
+			item: item.url
+		}))
+	};
+}
+
+//#endregion
+//#region src/client/components/structured-data.tsx
+/**
+* Renders safe, valid JSON-LD. Escaping `<` prevents a JSON value from closing
+* the surrounding script tag when the document is rendered server-side.
+*/
+function StructuredData({ data, id }) {
+	return /* @__PURE__ */ jsx("script", {
+		id,
+		type: "application/ld+json",
+		dangerouslySetInnerHTML: { __html: JSON.stringify(data).replace(/</g, "\\u003c") }
+	});
+}
+
 //#endregion
 //#region src/client/app/head.tsx
+function stringifyMetaValue(value) {
+	if (value == null) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) return value.map(stringifyMetaValue).join(", ");
+	if (typeof value === "object") {
+		const record = value;
+		const namedValue = record.name ?? record.value ?? record.url;
+		if (namedValue !== void 0) return stringifyMetaValue(namedValue);
+		try {
+			return JSON.stringify(value);
+		} catch {
+			return "";
+		}
+	}
+	return String(value);
+}
 function Head({ siteTitle, siteDescription, routes }) {
-	const location = useLocation$1();
+	const location = useLocation();
 	const config = useConfig();
 	const { currentLocale, currentRoute } = useRoutes();
 	const route = useMemo(() => {
 		if (currentRoute) return currentRoute;
 		const normalizedPath = location.pathname.endsWith("/") && location.pathname.length > 1 ? location.pathname.slice(0, -1) : location.pathname;
 		return routes?.find?.((r) => {
+			if (!r?.path) return false;
 			return (r.path.endsWith("/") && r.path.length > 1 ? r.path.slice(0, -1) : r.path) === normalizedPath;
 		});
 	}, [
@@ -198,18 +323,23 @@ function Head({ siteTitle, siteDescription, routes }) {
 	const translatedSiteTitle = getTranslated(siteTitle, currentLocale);
 	const finalTitle = pageTitle ? `${pageTitle} | ${translatedSiteTitle}` : translatedSiteTitle;
 	const seo = route?.seo || {};
-	const canonicalUrl = seo.canonical || (config?.siteUrl && route?.path ? `${config.siteUrl.replace(/\/$/, "")}${route.path}` : void 0);
-	const ogUrl = seo["og:url"] || canonicalUrl || (typeof window !== "undefined" ? window.location.href : void 0);
-	const globalMetatags = config?.seo?.metatags || {};
+	const structuredData = [...Array.isArray(config?.seo?.structuredData) ? config.seo.structuredData : config?.seo?.structuredData ? [config.seo.structuredData] : [], ...Array.isArray(seo.structuredData) ? seo.structuredData : seo.structuredData ? [seo.structuredData] : []];
+	const canonicalUrl = stringifyMetaValue(seo.canonical) || (config?.siteUrl && route?.path ? `${config.siteUrl.replace(/\/$/, "")}${route.path}` : void 0);
+	const ogUrl = stringifyMetaValue(seo["og:url"]) || canonicalUrl || (typeof window !== "undefined" ? window.location.href : void 0);
 	const defaultOgImage = config?.seo?.thumbnails?.background;
-	let ogImage = seo["og:image"] || route?.coverImage || defaultOgImage;
-	if (ogImage && config?.siteUrl && !/^https?:\/\/|^\/\//.test(ogImage)) ogImage = `${config.siteUrl.endsWith("/") ? config.siteUrl.slice(0, -1) : config.siteUrl}${ogImage.startsWith("/") ? ogImage : `/${ogImage}`}`;
+	let ogImage = stringifyMetaValue(seo["og:image"]) || route?.coverImage || defaultOgImage;
+	if (ogImage && !/^https?:\/\/|^\/\//.test(ogImage)) {
+		const assetPath = resolvePublicAssetUrl(ogImage.startsWith("/") ? ogImage : `/${ogImage}`, config.base);
+		if (config?.siteUrl) ogImage = `${config.siteUrl.replace(/\/$/, "")}${assetPath}`;
+		else ogImage = assetPath;
+	}
 	return /* @__PURE__ */ jsxs(Helmet, { children: [
 		/* @__PURE__ */ jsx("title", { children: finalTitle }),
 		/* @__PURE__ */ jsx("meta", {
 			name: "description",
 			content: pageDescription
 		}),
+		structuredData.map((data) => /* @__PURE__ */ jsx(StructuredData, { data }, JSON.stringify(data))),
 		/* @__PURE__ */ jsx("meta", {
 			property: "og:title",
 			content: finalTitle
@@ -250,41 +380,6 @@ function Head({ siteTitle, siteDescription, routes }) {
 			property: "og:image",
 			content: ogImage
 		}),
-		/* @__PURE__ */ jsx("meta", {
-			name: "generator",
-			content: "Boltdocs"
-		}),
-		config?.seo?.verification?.google && /* @__PURE__ */ jsx("meta", {
-			name: "google-site-verification",
-			content: config.seo.verification.google
-		}),
-		config?.seo?.verification?.bing && /* @__PURE__ */ jsx("meta", {
-			name: "msvalidate.01",
-			content: config.seo.verification.bing
-		}),
-		config?.seo?.verification?.yandex && /* @__PURE__ */ jsx("meta", {
-			name: "yandex-verification",
-			content: config.seo.verification.yandex
-		}),
-		config?.seo?.verification?.pinterest && /* @__PURE__ */ jsx("meta", {
-			name: "p:domain_verify",
-			content: config.seo.verification.pinterest
-		}),
-		config?.seo?.verification?.facebook && /* @__PURE__ */ jsx("meta", {
-			name: "facebook-domain-verification",
-			content: config.seo.verification.facebook
-		}),
-		Object.entries(globalMetatags).map(([key, value]) => {
-			const isProperty = key.startsWith("og:") || key.startsWith("music:") || key.startsWith("video:") || key.startsWith("article:") || key.startsWith("book:") || key.startsWith("profile:");
-			const strVal = String(value ?? "");
-			return isProperty ? /* @__PURE__ */ jsx("meta", {
-				property: key,
-				content: strVal
-			}, key) : /* @__PURE__ */ jsx("meta", {
-				name: key,
-				content: strVal
-			}, key);
-		}),
 		Object.entries(seo).map(([key, value]) => {
 			if (key === "noindex" && value === true) return /* @__PURE__ */ jsx("meta", {
 				name: "robots",
@@ -292,11 +387,11 @@ function Head({ siteTitle, siteDescription, routes }) {
 			}, "noindex");
 			if (key === "robots") return /* @__PURE__ */ jsx("meta", {
 				name: "robots",
-				content: String(value)
+				content: stringifyMetaValue(value)
 			}, "robots");
-			if (key === "canonical" || key === "og:url" || key === "og:image" || key === "twitter:image") return null;
+			if (key === "canonical" || key === "og:url" || key === "og:image" || key === "twitter:image" || key === "structuredData") return null;
 			const isProperty = key.startsWith("og:") || key.startsWith("music:") || key.startsWith("video:") || key.startsWith("article:") || key.startsWith("book:") || key.startsWith("profile:");
-			const strVal = String(value ?? "");
+			const strVal = stringifyMetaValue(value);
 			return isProperty ? /* @__PURE__ */ jsx("meta", {
 				property: key,
 				content: strVal
@@ -314,6 +409,35 @@ const CollectionsContext = createContext({});
 function useCollectionsData() {
 	return use(CollectionsContext);
 }
+function CollectionsProvider({ collectionsData, children }) {
+	const [data, setData] = useState(collectionsData);
+	useEffect(() => {
+		if (!import.meta.hot) return;
+		const handler = (payload) => {
+			setData((prev) => {
+				const next = { ...prev };
+				for (const post of payload.collections.updated) {
+					const collection = post.collection;
+					if (!collection) continue;
+					const arr = next[collection] ? [...next[collection]] : [];
+					const idx = arr.findIndex((p) => p.filePath === post.filePath);
+					if (idx >= 0) arr[idx] = post;
+					else arr.push(post);
+					next[collection] = arr;
+				}
+				for (const filePath of payload.collections.deleted) for (const key of Object.keys(next)) next[key] = next[key].filter((p) => p.filePath !== filePath);
+				return next;
+			});
+		};
+		const hot = import.meta.hot;
+		hot.on("boltdocs:frontmatter-update", handler);
+		return () => hot.off?.("boltdocs:frontmatter-update", handler);
+	}, []);
+	return /* @__PURE__ */ jsx(CollectionsContext.Provider, {
+		value: data,
+		children
+	});
+}
 const CurrentPostContext = createContext(null);
 function CurrentPostProvider({ value, children }) {
 	return /* @__PURE__ */ jsx(CurrentPostContext.Provider, {
@@ -332,41 +456,58 @@ function useCurrentPostData() {
 */
 function I18nUpdater({ config }) {
 	const { currentLocale } = useBoltdocsContext();
+	const locale = currentLocale || config.i18n?.defaultLocale || "en";
+	const localeConfig = config.i18n?.localeConfigs?.[locale];
+	const htmlLang = localeConfig?.htmlLang || locale;
+	const direction = localeConfig?.direction || "ltr";
 	useEffect(() => {
 		if (!config.i18n || typeof document === "undefined") return;
-		const locale = currentLocale || config.i18n.defaultLocale;
-		const localeConfig = config.i18n.localeConfigs?.[locale];
-		document.documentElement.lang = localeConfig?.htmlLang || locale || "en";
-		document.documentElement.dir = localeConfig?.direction || "ltr";
-	}, [currentLocale, config.i18n]);
-	return null;
+		document.documentElement.lang = htmlLang;
+		document.documentElement.dir = direction;
+	}, [
+		config.i18n,
+		direction,
+		htmlLang
+	]);
+	return /* @__PURE__ */ jsx(Helmet, { htmlAttributes: {
+		lang: htmlLang,
+		dir: direction
+	} });
 }
 function StoreSync({ config, routeMap }) {
-	const location = useLocation$1();
-	const { setLocale, setVersion } = useBoltdocsContext();
+	const location = useLocation();
+	const { currentLocale, currentVersion, setLocale, setVersion } = useBoltdocsContext();
 	useEffect(() => {
-		const currentPath = normalizePath(location.pathname);
+		const currentPath = normalizePath(typeof window !== "undefined" ? window.location.pathname : location.pathname);
 		const matchedRoute = routeMap.get(currentPath);
 		if (matchedRoute) {
-			if (config.i18n) setLocale(matchedRoute.locale || config.i18n.defaultLocale);
-			if (config.versions) setVersion(matchedRoute.version || config.versions.defaultVersion);
-		}
+			if (config.i18n) {
+				const targetLocale = matchedRoute.locale || config.i18n.defaultLocale;
+				if (targetLocale !== currentLocale) setLocale(targetLocale);
+			}
+			if (config.versions) {
+				const targetVersion = matchedRoute.version || config.versions.defaultVersion;
+				if (targetVersion !== currentVersion) setVersion(targetVersion);
+			}
+		} else if (config.versions && currentVersion !== config.versions.defaultVersion) setVersion(config.versions.defaultVersion);
 	}, [
 		location.pathname,
 		config,
 		routeMap,
+		currentLocale,
+		currentVersion,
 		setLocale,
 		setVersion
 	]);
 	return null;
 }
-function BoltdocsShell({ config, routes, components = {}, collectionsData }) {
+function BoltdocsShell({ config, routes, components = {}, collectionsData, contentClassName }) {
 	const allComponents = useMemo(() => ({
 		...mdxComponentsDefault,
 		...virtualCustomComponents,
 		...components
 	}), [components]);
-	const { pathname } = useLocation$1();
+	const { pathname } = useLocation();
 	const currentPath = useMemo(() => normalizePath(pathname || "/"), [pathname]);
 	const routeMap = useMemo(() => {
 		const map = /* @__PURE__ */ new Map();
@@ -399,8 +540,8 @@ function BoltdocsShell({ config, routes, components = {}, collectionsData }) {
 			components: allComponents,
 			children: /* @__PURE__ */ jsx(ConfigContext.Provider, {
 				value: config,
-				children: /* @__PURE__ */ jsxs(CollectionsContext.Provider, {
-					value: collectionsData || {},
+				children: /* @__PURE__ */ jsxs(CollectionsProvider, {
+					collectionsData: collectionsData || {},
 					children: [/* @__PURE__ */ jsx(ScrollHandler, {}), /* @__PURE__ */ jsxs(BoltdocsProvider, {
 						initialLocale: initialData.initLocale,
 						initialVersion: initialData.initVersion,
@@ -416,7 +557,7 @@ function BoltdocsShell({ config, routes, components = {}, collectionsData }) {
 								routes
 							}),
 							/* @__PURE__ */ jsx(InternalErrorBoundary, { children: /* @__PURE__ */ jsx("div", {
-								className: "boltdocs-shell-content h-screen overflow-hidden",
+								className: cn("boltdocs-shell-content h-screen overflow-hidden", contentClassName),
 								children: /* @__PURE__ */ jsx(Outlet, {})
 							}) })
 						]
@@ -461,7 +602,7 @@ function DocPage({ route, content: Content, mdxComponents: propComponents }) {
 	const allComponents = useMergedComponents(propComponents);
 	const { LastUpdated } = allComponents;
 	if (!Content) return null;
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Content, { components: allComponents }), route?.lastUpdated && /* @__PURE__ */ jsx(LastUpdated, { date: route.lastUpdated })] });
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Content, { components: allComponents }), route?.lastUpdated && /* @__PURE__ */ jsx(LastUpdated, { date: route.lastUpdated })] });
 }
 
 //#endregion
@@ -476,26 +617,30 @@ function DocPage({ route, content: Content, mdxComponents: propComponents }) {
 */
 function MdxPage({ MDXComponent, mdxComponents: propComponents, collectionPostComponent: CollectionPost }) {
 	const data = useLoaderData();
+	const mdxComponents = {
+		...useMdxComponents(),
+		...propComponents
+	};
 	if (!MDXComponent) return null;
-	const collectionData = data;
-	if (!!collectionData?.collection) {
+	const collectionData = data || {};
+	if (!!collectionData?.collection && !!collectionData?.route) {
 		const postElement = CollectionPost ? /* @__PURE__ */ jsx(CollectionPost, {
 			MDXComponent,
-			mdxComponents: propComponents
+			mdxComponents
 		}) : /* @__PURE__ */ jsx(DocPage, {
 			route: {
-				path: collectionData.route.path,
-				filePath: collectionData.route.filePath,
-				title: collectionData.route.title,
-				description: collectionData.route.description,
-				headings: collectionData.headings,
-				locale: collectionData.route.locale,
-				version: collectionData.route.version,
-				lastUpdated: collectionData.route.lastUpdated,
-				frontmatter: collectionData.route.frontmatter
+				path: collectionData.route?.path || "",
+				filePath: collectionData.route?.filePath || "",
+				title: collectionData.route?.title,
+				description: collectionData.route?.description,
+				headings: collectionData.headings || [],
+				locale: collectionData.route?.locale,
+				version: collectionData.route?.version,
+				lastUpdated: collectionData.route?.lastUpdated,
+				frontmatter: collectionData.route?.frontmatter
 			},
 			content: MDXComponent,
-			mdxComponents: propComponents
+			mdxComponents
 		});
 		return /* @__PURE__ */ jsx(CurrentPostProvider, {
 			value: {
@@ -506,23 +651,23 @@ function MdxPage({ MDXComponent, mdxComponents: propComponents, collectionPostCo
 			children: postElement
 		});
 	}
-	const docData = data;
+	const docData = data || {};
 	return /* @__PURE__ */ jsx(DocPage, {
 		route: {
-			path: docData.path,
-			filePath: docData.filePath,
-			title: docData.frontmatter?.title,
-			description: docData.frontmatter?.description,
-			headings: docData.headings,
-			locale: docData.locale,
-			version: docData.version,
-			group: docData.group,
-			groupTitle: docData.groupTitle,
-			lastUpdated: docData.lastUpdated,
-			frontmatter: docData.frontmatter
+			path: docData?.path || "",
+			filePath: docData?.filePath || "",
+			title: docData?.frontmatter?.title,
+			description: docData?.frontmatter?.description,
+			headings: docData?.headings || [],
+			locale: docData?.locale,
+			version: docData?.version,
+			group: docData?.group,
+			groupTitle: docData?.groupTitle,
+			lastUpdated: docData?.lastUpdated,
+			frontmatter: docData?.frontmatter
 		},
 		content: MDXComponent,
-		mdxComponents: propComponents
+		mdxComponents
 	});
 }
 
@@ -549,11 +694,11 @@ function useBreadcrumbs() {
 
 //#endregion
 //#region src/client/components/ui-base/breadcrumbs.tsx
-function Breadcrumbs() {
+function Breadcrumbs({ className }) {
 	const { crumbs, activeRoute } = useBreadcrumbs();
 	if (crumbs.length === 0) return null;
 	return /* @__PURE__ */ jsxs(Breadcrumbs$2.Root, {
-		className: "gap-2 text-xs sm:text-sm font-medium",
+		className: cn("gap-2 text-xs sm:text-sm font-medium", className),
 		children: [/* @__PURE__ */ jsx(Breadcrumbs$2.Item, { children: /* @__PURE__ */ jsx(Breadcrumbs$2.Link, {
 			href: "/",
 			className: "text-muted hover:text-body transition-colors flex items-center",
@@ -602,12 +747,12 @@ const useCopyMarkdown = (content) => {
 		handleOpenRaw
 	};
 };
-function CopyMarkdown({ content, mdxRaw }) {
+function CopyMarkdown({ content, mdxRaw, className }) {
 	const displayContent = mdxRaw || content || "";
 	const { copied, handleCopy, handleOpenRaw } = useCopyMarkdown(displayContent);
 	if (!displayContent) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: "relative inline-flex z-100 shrink-0 w-max",
+		className: cn("relative inline-flex z-100 shrink-0 w-max", className),
 		children: /* @__PURE__ */ jsxs(ButtonGroup, {
 			className: "rounded-xl border border-subtle bg-surface transition-all duration-300 hover:border-primary-500/50 group overflow-hidden",
 			children: [
@@ -699,7 +844,7 @@ const formatStars = (count) => {
 
 //#endregion
 //#region src/client/components/ui-base/github-stars.tsx
-function GithubStars({ repo }) {
+function GithubStars({ repo, className }) {
 	const [stars, setStars] = useState(null);
 	useEffect(() => {
 		if (repo) getStarsRepo(repo).then((stars) => setStars(stars)).catch(() => setStars("0"));
@@ -708,7 +853,7 @@ function GithubStars({ repo }) {
 		href: `https://github.com/${repo}`,
 		target: "_blank",
 		rel: "noopener noreferrer",
-		className: "inline-flex items-center gap-2 rounded-xl border border-subtle bg-surface px-3 py-1.5 text-xs font-semibold text-muted dark:hover:bg-primary-300/50 hover:bg-primary-200/50 transition-colors duration-100 hover:border-primary-500/50 hover:text-body select-none outline-none",
+		className: cn("inline-flex items-center gap-2 rounded-xl border border-subtle bg-surface px-3 py-1.5 text-xs font-semibold text-muted dark:hover:bg-primary-300/50 hover:bg-primary-200/50 transition-colors duration-100 hover:border-primary-500/50 hover:text-body select-none outline-none", className),
 		children: [/* @__PURE__ */ jsx(Github, { className: "h-4 w-4 text-body" }), stars !== null && /* @__PURE__ */ jsxs("span", {
 			className: "tabular-nums font-medium",
 			children: [stars, " stars"]
@@ -721,7 +866,7 @@ function GithubStars({ repo }) {
 function useNavbar() {
 	const config = useConfig();
 	const { theme, resolvedTheme } = useTheme();
-	const location = useLocation$1();
+	const location = useLocation();
 	const { currentLocale } = useRoutes();
 	const themeConfig = config.theme || {};
 	const title = getTranslated(themeConfig.title, currentLocale) || "Boltdocs";
@@ -796,18 +941,18 @@ function useNavbar() {
 
 //#endregion
 //#region src/client/components/ui-base/theme-toggle.tsx
-function ThemeToggle() {
+function ThemeToggle({ className }) {
 	const { theme, setTheme } = useTheme();
 	const [mounted, setMounted] = useState(false);
 	useEffect(() => {
 		setMounted(true);
 	}, []);
-	if (!mounted) return /* @__PURE__ */ jsx("div", { className: "h-9 w-9" });
+	if (!mounted) return /* @__PURE__ */ jsx("div", { className: cn("h-9 w-9", className) });
 	const Icon = theme === "system" ? Monitor : theme === "dark" ? Moon : Sun;
 	return /* @__PURE__ */ jsxs(Menu$1.Trigger, {
 		placement: "bottom right",
 		children: [/* @__PURE__ */ jsx(Button, {
-			className: "flex h-9 w-9 items-center justify-center rounded-xl text-muted transition-colors hover:bg-surface hover:text-body outline-none border-none bg-transparent cursor-pointer",
+			className: cn("flex h-9 w-9 items-center justify-center rounded-xl text-muted transition-colors hover:bg-surface hover:text-body outline-none border-none bg-transparent cursor-pointer", className),
 			"aria-label": "Selection theme",
 			children: /* @__PURE__ */ jsx(Icon, {
 				size: 20,
@@ -890,7 +1035,7 @@ function ThemeSwitcher({ className }) {
 //#endregion
 //#region src/client/hooks/use-tabs.ts
 function useTabs(tabs = [], routes = []) {
-	const location = useLocation$1();
+	const location = useLocation();
 	const tabRefs = useRef([]);
 	const [indicatorStyle, setIndicatorStyle] = useState({
 		opacity: 0,
@@ -924,9 +1069,11 @@ function useTabs(tabs = [], routes = []) {
 
 //#endregion
 //#region src/client/components/ui-base/tabs.tsx
-function Tabs({ tabs, routes }) {
+function Tabs({ tabs, routes, allRoutes, className }) {
 	const { currentLocale } = useRoutes();
 	const { indicatorStyle, tabRefs, activeIndex } = useTabs(tabs, routes);
+	const routeCandidates = routes;
+	const fallbackRouteCandidates = allRoutes || [];
 	useEffect(() => {
 		const activeTab = tabRefs.current[activeIndex];
 		if (activeTab) activeTab.scrollIntoView({
@@ -934,33 +1081,19 @@ function Tabs({ tabs, routes }) {
 			block: "nearest",
 			inline: "center"
 		});
-	}, [activeIndex]);
-	const renderTabIcon = (iconName) => {
-		if (!iconName) return null;
-		if (iconName.trim().startsWith("<svg")) return /* @__PURE__ */ jsx("span", {
-			className: "h-4 w-4",
-			dangerouslySetInnerHTML: { __html: DOMPurify.sanitize(iconName, { USE_PROFILES: { svg: true } }) }
-		});
-		const icons = {
-			...icons_exports,
-			...virtualIcons
-		};
-		const TabIcon = icons[iconName] || icons[iconName + "Icon"];
-		if (TabIcon) return /* @__PURE__ */ jsx(TabIcon, { size: 16 });
-		return /* @__PURE__ */ jsx("img", {
-			src: iconName,
-			alt: "",
-			className: "h-4 w-4 object-contain"
-		});
-	};
+	}, [activeIndex, tabRefs]);
+	const renderTabIcon = (iconName) => /* @__PURE__ */ jsx(IconRenderer, {
+		icon: resolveIcon(iconName),
+		size: 16
+	});
 	return /* @__PURE__ */ jsx("div", {
-		className: "mx-auto max-w-(--breakpoint-3xl) px-4 md:px-6 select-none",
+		className: cn("mx-auto max-w-(--breakpoint-3xl) px-4 md:px-6 select-none", className),
 		children: /* @__PURE__ */ jsxs(Tabs$1.List, {
 			className: "border-none py-0 scrollbar-hide relative flex flex-row items-center overflow-x-auto",
 			children: [tabs.map((tab, index) => {
 				const isActive = index === activeIndex;
-				const firstRoute = routes.find((r) => r.tab && r.tab.toLowerCase() === tab.id.toLowerCase());
-				return /* @__PURE__ */ jsxs(Link$1, {
+				const firstRoute = routeCandidates.find((r) => r.tab && r.tab.toLowerCase() === tab.id.toLowerCase()) || fallbackRouteCandidates.find((r) => r.tab && r.tab.toLowerCase() === tab.id.toLowerCase());
+				return /* @__PURE__ */ jsxs(Link, {
 					href: firstRoute ? firstRoute.path : "#",
 					ref: (el) => {
 						tabRefs.current[index] = el;
@@ -1067,6 +1200,7 @@ function VersionSelector({ className }) {
 */
 function useI18n() {
 	const navigate = useNavigate();
+	const location = useLocation();
 	const config = useConfig();
 	const { allRoutes, currentRoute, currentLocale, isCollectionPage } = useRoutes();
 	const i18n = config.i18n;
@@ -1079,16 +1213,16 @@ function useI18n() {
 		const isDocRoute = !!currentRoute?.filePath;
 		let targetPath = "";
 		if (currentRoute) if (isDocRoute && !currentRoute.collection && !isCollectionPage) {
-			const baseFile = getBaseFilePath(currentRoute.filePath, currentRoute.version, currentRoute.locale);
-			const targetRoute = allRoutes.find((r) => getBaseFilePath(r.filePath, r.version, r.locale) === baseFile && (r.locale || i18n.defaultLocale) === locale && r.version === currentRoute.version);
+			const baseFile = currentRoute.filePath ? getBaseFilePath(currentRoute.filePath, currentRoute.version, currentRoute.locale) : "";
+			const targetRoute = allRoutes.find((r) => r.filePath && getBaseFilePath(r.filePath, r.version, r.locale) === baseFile && (r.locale || i18n.defaultLocale) === locale && r.version === currentRoute.version);
 			if (targetRoute) targetPath = targetRoute.path;
 			else {
-				const defaultIndexRoute = allRoutes.find((r) => getBaseFilePath(r.filePath, r.version, r.locale) === "index.md" && (r.locale || i18n.defaultLocale) === locale && r.version === currentRoute.version);
+				const defaultIndexRoute = allRoutes.find((r) => r.filePath && ["index.md", "_index.md"].includes(getBaseFilePath(r.filePath, r.version, r.locale)) && (r.locale || i18n.defaultLocale) === locale && r.version === currentRoute.version);
 				if (defaultIndexRoute) targetPath = defaultIndexRoute.path;
 				else targetPath = `${safeBase}${currentRoute.version ? `/${currentRoute.version}` : ""}${locale === i18n.defaultLocale ? "" : `/${locale}`}` || "/";
 			}
 		} else {
-			let rawExternal = currentRoute.path;
+			let rawExternal = currentRoute.path || "";
 			const parts = rawExternal.split("/").filter(Boolean);
 			const localePosition = currentRoute.collection ? 1 : 0;
 			if (parts.length > localePosition && (Array.isArray(i18n.locales) ? i18n.locales.includes(parts[localePosition]) : !!i18n.locales[parts[localePosition]])) {
@@ -1112,7 +1246,7 @@ function useI18n() {
 				targetPath = "/" + parts.join("/");
 			}
 		}
-		if (!targetPath || targetPath === "") targetPath = "/s";
+		if (!targetPath || targetPath === "") targetPath = "/";
 		targetPath = targetPath.replace(/\/+/g, "/");
 		navigate(targetPath);
 	};
@@ -1146,7 +1280,7 @@ function useI18n() {
 //#region src/client/hooks/use-page-nav.ts
 function usePageNav() {
 	const { routes, currentRoute } = useRoutes();
-	const location = useLocation$1();
+	const location = useLocation();
 	const { groups, ungrouped } = useSidebar(routes);
 	return useMemo(() => {
 		if (!currentRoute) return {
@@ -1171,14 +1305,20 @@ function usePageNav() {
 		});
 		const orderedRoutes = [];
 		const flattenNode = (node) => {
+			if (!node) return;
 			if (node.path && node.path !== "#" && !node.sidebarHidden) orderedRoutes.push(node);
 			const children = node.routes || node.subRoutes;
-			if (children && children.length > 0) for (const child of children) flattenNode(child);
+			if (children && children.length > 0) {
+				for (const child of children) if (child) flattenNode(child);
+			}
 		};
-		for (const item of mergedItems) if (item.type === "link") flattenNode(item.route);
-		else if (item.group.routes) for (const route of item.group.routes) flattenNode(route);
+		for (const item of mergedItems) if (item.type === "link") {
+			if (item.route) flattenNode(item.route);
+		} else if (item.group.routes) {
+			for (const route of item.group.routes) if (route) flattenNode(route);
+		}
 		const currentNormalizedPath = normalizePath(location.pathname);
-		const currentIndex = orderedRoutes.findIndex((r) => normalizePath(r.path) === currentNormalizedPath);
+		const currentIndex = orderedRoutes.findIndex((r) => r && r.path && normalizePath(r.path) === currentNormalizedPath);
 		return {
 			prevPage: currentIndex > 0 ? orderedRoutes[currentIndex - 1] : null,
 			nextPage: currentIndex !== -1 && currentIndex < orderedRoutes.length - 1 ? orderedRoutes[currentIndex + 1] : null,
@@ -1336,16 +1476,17 @@ function useAnalytics(options = {}) {
 	const config = optionsConfig ?? globalConfig?.integrations;
 	const analytics = useMemo(() => createAnalyticsInstance(config), [config]);
 	const previousPath = useRef("");
-	const location = useLocation();
+	const { pathname, search } = location;
 	useEffect(() => {
 		if (!autoTrackPageViews || !analytics.isEnabled) return;
-		const path = location.pathname + location.search;
+		const path = pathname + search;
 		if (path !== previousPath.current) {
 			previousPath.current = path;
 			analytics.trackPageView(path, document.title);
 		}
 	}, [
-		location.pathname,
+		pathname,
+		search,
 		autoTrackPageViews,
 		analytics
 	]);
@@ -1366,7 +1507,6 @@ function useAnalytics(options = {}) {
 		return () => document.removeEventListener("click", handleClick);
 	}, [
 		autoTrackDownloads,
-		autoTrackExternalLinks,
 		analytics,
 		excludePatterns
 	]);
@@ -1431,12 +1571,13 @@ function useFeedback(options = {}) {
 	const [loading, setLoading] = useState(false);
 	const [submitted, setSubmitted] = useState(false);
 	const [error, setError] = useState(null);
+	const routePath = currentRoute?.path;
 	useEffect(() => {
 		setRating(null);
 		setComment("");
 		setSubmitted(false);
 		setError(null);
-	}, [currentRoute?.path]);
+	}, [routePath]);
 	const submit = async (commentOverride, blockId) => {
 		if (!rating) return;
 		setLoading(true);
@@ -1515,17 +1656,17 @@ function I18nSelector({ className }) {
 
 //#endregion
 //#region src/client/components/ui-base/navbar.tsx
-const SearchDialog$1 = lazy(() => import("../search-dialog-D6TvjcuV.js").then((m) => ({ default: m.SearchDialog })));
-function Navbar() {
+const SearchDialog$1 = lazy(() => import("../search-dialog-DtmxmfEu.js").then((m) => ({ default: m.SearchDialog })));
+function Navbar({ className }) {
 	const { links, title, logo, logoProps, github, social, config } = useNavbar();
-	const { routes, currentRoute, isCollectionPage, currentVersion, currentLocale } = useRoutes();
+	const { routes, allRoutes, currentRoute, isCollectionPage, currentVersion, currentLocale } = useRoutes();
 	const { isSidebarOpen, toggleSidebar } = useUI();
 	const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
 	const themeConfig = config.theme;
 	const isDocs = !!currentRoute?.filePath && !isCollectionPage;
 	const hasTabs = themeConfig?.tabs && themeConfig.tabs.length > 0;
 	return /* @__PURE__ */ jsxs(Navbar$1.Root, {
-		className: cn("border-b border-subtle bg-main/80 backdrop-blur-md", hasTabs && "border-b-0"),
+		className: cn("border-b border-subtle bg-main/80 backdrop-blur-md", hasTabs && "border-b-0", className),
 		children: [
 			/* @__PURE__ */ jsxs(Navbar$1.Content, { children: [
 				/* @__PURE__ */ jsxs(Navbar$1.Left, { children: [
@@ -1630,7 +1771,8 @@ function Navbar() {
 				className: "w-full border-b border-subtle bg-main",
 				children: /* @__PURE__ */ jsx(Tabs, {
 					tabs: themeConfig.tabs,
-					routes: routes || []
+					routes: routes || [],
+					allRoutes: allRoutes || []
 				})
 			})
 		]
@@ -1638,7 +1780,7 @@ function Navbar() {
 }
 function NavbarLinkItem({ link }) {
 	const localizedHref = useLocalizedTo(link.href || "");
-	const { pathname } = useLocation$1();
+	const { pathname } = useLocation();
 	const active = pathname === localizedHref || pathname.startsWith(`${localizedHref}/`);
 	if (link.items && link.items.length > 0) return /* @__PURE__ */ jsx(Navbar$1.Dropdown, {
 		label: /* @__PURE__ */ jsx("span", {
@@ -1658,70 +1800,58 @@ function NavbarLinkItem({ link }) {
 	});
 }
 function NavbarMobileLinkItem({ link, onClose }) {
-	const localizedHref = useLocalizedTo(link.href || "");
-	const { pathname } = useLocation$1();
-	const active = pathname === localizedHref;
-	if (link.items && link.items.length > 0) return /* @__PURE__ */ jsxs("div", {
-		className: "flex flex-col gap-1",
-		children: [/* @__PURE__ */ jsx("div", {
-			className: cn("px-3 py-2 text-sm transition-all", active ? "text-body" : "text-muted/80 hover:text-body"),
-			children: link.label
-		}), /* @__PURE__ */ jsx("div", {
-			className: "flex flex-col gap-1 pl-4",
-			children: link.items?.map((item) => /* @__PURE__ */ jsx(NavbarMobileLinkItem, {
-				link: item,
-				onClose
-			}, item.href))
-		})]
-	});
-	return /* @__PURE__ */ jsx(Navbar$1.MobileLink, {
-		...link,
-		href: localizedHref,
-		active,
-		onPress: onClose,
-		className: cn("transition-all", active ? "text-body" : "text-muted/80 hover:text-body")
+	return /* @__PURE__ */ jsx(Navbar$1.MobileLinkItem, {
+		link,
+		onClose
 	});
 }
 
 //#endregion
 //#region src/client/components/ui-base/on-this-page.tsx
-function OnThisPage({ headings = [], editLink, communityHelp, filePath }) {
+function OnThisPage({ headings = [], editLink, communityHelp, filePath, className }) {
 	if (headings.length === 0) return /* @__PURE__ */ jsx("nav", {
-		className: "w-toc shrink-0 hidden xl:block",
+		className: cn("w-toc shrink-0 hidden xl:block", className),
 		"aria-hidden": "true"
 	});
-	return /* @__PURE__ */ jsxs(OnThisPage$1.Root, { children: [
-		/* @__PURE__ */ jsxs(OnThisPage$1.Header, {
-			className: "flex flex-row gap-x-2",
-			children: [/* @__PURE__ */ jsx(TextAlignStart, { size: 16 }), "On this page"]
-		}),
-		/* @__PURE__ */ jsx(OnThisPage$1.Tree, {
-			className: "max-h-[300px]",
-			headings
-		}),
-		(editLink || communityHelp) && /* @__PURE__ */ jsxs("div", {
-			className: "mt-8 pt-8 border-t border-subtle space-y-4",
-			children: [/* @__PURE__ */ jsx("p", {
-				className: "text-xs font-bold text-body",
-				children: "Need help?"
-			}), /* @__PURE__ */ jsxs("ul", {
-				className: "space-y-3",
-				children: [editLink && filePath && /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", {
-					href: editLink.replace(":path", filePath),
-					target: "_blank",
-					rel: "noopener noreferrer",
-					className: "flex items-center gap-2 text-sm text-muted hover:text-body transition-colors",
-					children: [/* @__PURE__ */ jsx(Pencil, { size: 16 }), "Edit this page"]
-				}) }), communityHelp && /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", {
-					href: communityHelp,
-					target: "_blank",
-					rel: "noopener noreferrer",
-					className: "flex items-center gap-2 text-sm text-muted hover:text-body transition-colors",
-					children: [/* @__PURE__ */ jsx(CircleHelp, { size: 16 }), "Community help"]
-				}) })]
-			})]
-		})
-	] });
+	return /* @__PURE__ */ jsxs(OnThisPage$1.Root, {
+		className: cn("sticky top-navbar hidden xl:flex flex-col shrink-0 w-toc py-4 pl-6 pr-4", className),
+		children: [
+			/* @__PURE__ */ jsxs(OnThisPage$1.Header, {
+				className: "mb-4 text-xs font-bold text-body flex flex-row gap-x-2",
+				children: [/* @__PURE__ */ jsx(TextAlignStart, { size: 16 }), "On this page"]
+			}),
+			/* @__PURE__ */ jsx(OnThisPage$1.Tree, {
+				className: "space-y-0.5 text-sm border-l border-subtle",
+				itemClassName: "data-[level=3]:pl-3",
+				linkClassName: "block py-0.5 pl-4 text-[13px] outline-none transition-colors text-muted hover:text-body data-active:text-primary-500",
+				indicatorClassName: "-left-px w-0.5 rounded-full bg-primary-500",
+				fadeClassName: "bg-linear-to-b from-transparent to-main",
+				headings
+			}),
+			(editLink || communityHelp) && /* @__PURE__ */ jsxs("div", {
+				className: "mt-8 pt-8 border-t border-subtle space-y-4",
+				children: [/* @__PURE__ */ jsx("p", {
+					className: "text-xs font-bold text-body",
+					children: "Need help?"
+				}), /* @__PURE__ */ jsxs("ul", {
+					className: "space-y-3",
+					children: [editLink && filePath && /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", {
+						href: editLink.replace(":path", filePath),
+						target: "_blank",
+						rel: "noopener noreferrer",
+						className: "flex items-center gap-2 text-sm text-muted hover:text-body transition-colors",
+						children: [/* @__PURE__ */ jsx(Pencil, { size: 16 }), "Edit this page"]
+					}) }), communityHelp && /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", {
+						href: communityHelp,
+						target: "_blank",
+						rel: "noopener noreferrer",
+						className: "flex items-center gap-2 text-sm text-muted hover:text-body transition-colors",
+						children: [/* @__PURE__ */ jsx(CircleHelp, { size: 16 }), "Community help"]
+					}) })]
+				})]
+			})
+		]
+	});
 }
 
 //#endregion
@@ -1730,32 +1860,44 @@ function OnThisPage({ headings = [], editLink, communityHelp, filePath }) {
 * Component to display the previous and next page navigation buttons.
 * Enhanced with subtle entrance animations, modern card layout, and hover highlights.
 */
-function PageNav() {
+function PageNav({ className }) {
 	const { prevPage, nextPage } = usePageNav();
 	if (!prevPage && !nextPage) return null;
 	return /* @__PURE__ */ jsxs(PageNav$1.Root, {
-		className: "pt-8 border-t border-subtle grid sm:grid-cols-2 gap-4 animate-in fade-in slide-in-from-bottom-4 duration-700 select-none",
+		className: cn("pt-8 border-t border-subtle grid sm:grid-cols-2 gap-4 animate-in fade-in slide-in-from-bottom-4 duration-700 select-none", className),
 		children: [prevPage ? /* @__PURE__ */ jsxs(PageNav$1.Link, {
 			to: prevPage.path,
 			direction: "prev",
 			className: "group border border-subtle bg-surface p-5 rounded-2xl transition-all duration-300 hover:border-primary-500/50 hover:bg-primary-50/20",
-			children: [/* @__PURE__ */ jsx(PageNav$1.Title, {
-				className: "text-xs font-bold uppercase tracking-wider text-muted/60 mb-1",
-				children: "Previous"
-			}), /* @__PURE__ */ jsx(PageNav$1.Description, {
-				className: "text-sm sm:text-base font-bold text-body group-hover:text-primary-500 transition-colors",
-				children: prevPage.title
+			children: [/* @__PURE__ */ jsx(PageNav$1.Icon, {
+				className: "text-muted/60 shrink-0",
+				children: /* @__PURE__ */ jsx(ChevronLeft, {})
+			}), /* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col",
+				children: [/* @__PURE__ */ jsx(PageNav$1.Title, {
+					className: "text-xs font-bold uppercase tracking-wider text-muted/60 mb-1",
+					children: "Previous"
+				}), /* @__PURE__ */ jsx(PageNav$1.Description, {
+					className: "text-sm sm:text-base font-bold text-body group-hover:text-primary-500 transition-colors",
+					children: prevPage.title
+				})]
 			})]
 		}) : /* @__PURE__ */ jsx("div", {}), nextPage ? /* @__PURE__ */ jsxs(PageNav$1.Link, {
 			to: nextPage.path,
 			direction: "next",
 			className: "group border border-subtle bg-surface p-5 rounded-2xl transition-all duration-300 hover:border-primary-500/50 hover:bg-primary-50/20",
-			children: [/* @__PURE__ */ jsx(PageNav$1.Title, {
-				className: "text-xs font-bold uppercase tracking-wider text-muted/60 mb-1",
-				children: "Next"
-			}), /* @__PURE__ */ jsx(PageNav$1.Description, {
-				className: "text-sm sm:text-base font-bold text-body group-hover:text-primary-500 transition-colors",
-				children: nextPage.title
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col",
+				children: [/* @__PURE__ */ jsx(PageNav$1.Title, {
+					className: "text-xs font-bold uppercase tracking-wider text-muted/60 mb-1",
+					children: "Next"
+				}), /* @__PURE__ */ jsx(PageNav$1.Description, {
+					className: "text-sm sm:text-base font-bold text-body group-hover:text-primary-500 transition-colors",
+					children: nextPage.title
+				})]
+			}), /* @__PURE__ */ jsx(PageNav$1.Icon, {
+				className: "text-muted/60 shrink-0",
+				children: /* @__PURE__ */ jsx(ChevronRight, {})
 			})]
 		}) : /* @__PURE__ */ jsx("div", {})]
 	});
@@ -1763,38 +1905,90 @@ function PageNav() {
 
 //#endregion
 //#region src/client/components/ui-base/sidebar.tsx
-function SidebarMain({ routes, config }) {
+/**
+* Default look for the sidebar tree. States are driven by the primitive's
+* `data-*` attributes (`data-active`, `data-open`, `data-badge`).
+*/
+const defaultItemsClassNames = {
+	item: "rounded-lg px-2.5 py-1.5 text-sm transition-all text-muted hover:bg-surface hover:text-body data-active:bg-primary-500/10 data-active:text-primary-500 data-active:font-medium data-active:shadow-sm",
+	groupHeader: "px-2 mb-2 text-[11px] font-bold uppercase tracking-widest text-muted/50",
+	groupContent: "gap-0.5",
+	subgroup: "gap-0.5",
+	subgroupLink: "rounded-lg px-2.5 py-1.5 text-sm transition-all text-muted hover:bg-surface hover:text-body data-active:bg-primary-500/10 data-active:text-primary-500 data-active:font-medium data-active:shadow-sm",
+	subgroupContent: "ml-4 pl-3 border-l border-subtle/50 mt-0.5 gap-0.5",
+	toggle: "p-1.5 text-muted hover:text-body transition-colors"
+};
+const defaultContentClassName = "flex-1 overflow-y-auto p-4 pb-16 custom-scrollbar flex flex-col gap-6";
+const mergeSlots = (defaults, overrides) => {
+	if (!overrides) return defaults;
+	const merged = { ...defaults };
+	for (const key of Object.keys(defaults)) if (overrides[key]) merged[key] = cn(defaults[key], overrides[key]);
+	return merged;
+};
+function SidebarMain({ routes, config, className }) {
 	const { logo, title, logoProps } = useNavbar();
 	const { closeSidebar } = useUI();
 	const SidebarLogo = logo ? /* @__PURE__ */ jsx("img", {
-		src: logo,
+		src: resolvePublicAssetUrl(logo, config.base),
 		alt: logoProps?.alt || title,
 		width: 24,
 		height: 24,
 		className: "rounded-xl"
 	}) : null;
 	const hasUtilities = config.versions || config.i18n;
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Sidebar$1.Root, { children: /* @__PURE__ */ jsx(Sidebar$1.Content, { children: /* @__PURE__ */ jsx(Sidebar$1.Items, { routes }) }) }), /* @__PURE__ */ jsxs(Sidebar$1.Mobile, { children: [/* @__PURE__ */ jsxs(Sidebar$1.Header, { children: [/* @__PURE__ */ jsxs("div", {
-		className: "flex items-center gap-3",
-		children: [SidebarLogo, /* @__PURE__ */ jsx("span", {
-			className: "font-bold text-lg tracking-tight text-body truncate max-w-[120px]",
-			children: title
-		})]
-	}), /* @__PURE__ */ jsxs("div", {
-		className: "flex items-center gap-2",
-		children: [/* @__PURE__ */ jsx(ThemeSwitcher, { className: "w-24 h-9 rounded-xl" }), /* @__PURE__ */ jsx(Button$1, {
-			onPress: closeSidebar,
-			className: "h-9 w-9 flex items-center justify-center bg-transparent border-none outline-none select-none cursor-pointer rounded-xl hover:bg-primary-50/50 text-muted hover:text-body transition-colors",
-			"aria-label": "Close sidebar",
-			children: /* @__PURE__ */ jsx(X, { size: 20 })
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Sidebar$1.Root, {
+		className: cn("hidden lg:flex flex-col w-sidebar sticky top-navbar h-[calc(100vh-var(--spacing-navbar))] border-r border-subtle bg-main", className),
+		children: /* @__PURE__ */ jsx(Sidebar$1.Content, {
+			className: defaultContentClassName,
+			children: /* @__PURE__ */ jsx(Sidebar$1.Items, {
+				routes,
+				className: "flex flex-col gap-6",
+				classNames: defaultItemsClassNames
+			})
+		})
+	}), /* @__PURE__ */ jsxs(Sidebar$1.Mobile, {
+		overlayClassName: "fixed inset-0 z-50 bg-black/20 backdrop-blur-sm lg:hidden entering:animate-in entering:fade-in exiting:animate-out exiting:fade-out duration-300",
+		className: cn("fixed top-0 left-0 bottom-0 w-80 bg-main border-r border-subtle shadow-2xl outline-none entering:animate-in entering:slide-in-from-left exiting:animate-out exiting:slide-out-to-left duration-300", className),
+		children: [/* @__PURE__ */ jsxs(Sidebar$1.Header, {
+			className: "flex items-center justify-between p-4 border-b border-subtle",
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-3",
+				children: [SidebarLogo, /* @__PURE__ */ jsx("span", {
+					className: "font-bold text-lg tracking-tight text-body truncate max-w-[120px]",
+					children: title
+				})]
+			}), /* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2",
+				children: [/* @__PURE__ */ jsx(ThemeSwitcher, { className: "w-24 h-9 rounded-xl" }), /* @__PURE__ */ jsx(Button$1, {
+					onPress: closeSidebar,
+					className: "h-9 w-9 flex items-center justify-center bg-transparent border-none outline-none select-none cursor-pointer rounded-xl hover:bg-primary-50/50 text-muted hover:text-body transition-colors",
+					"aria-label": "Close sidebar",
+					children: /* @__PURE__ */ jsx(X, { size: 20 })
+				})]
+			})]
+		}), /* @__PURE__ */ jsxs(Sidebar$1.Content, {
+			className: defaultContentClassName,
+			children: [hasUtilities && /* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-4 mb-10",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex gap-3",
+					children: [config.versions && /* @__PURE__ */ jsx(VersionSelector, { className: "flex-1 justify-between h-10 bg-surface border-subtle rounded-xl" }), config.i18n && /* @__PURE__ */ jsx(I18nSelector, { className: "flex-1 justify-between h-10 bg-surface border-subtle rounded-xl" })]
+				}), /* @__PURE__ */ jsx("div", { className: "mt-2 border-b border-subtle" })]
+			}), /* @__PURE__ */ jsx(Sidebar$1.Items, {
+				routes,
+				className: "flex flex-col gap-6",
+				classNames: defaultItemsClassNames
+			})]
 		})]
-	})] }), /* @__PURE__ */ jsxs(Sidebar$1.Content, { children: [hasUtilities && /* @__PURE__ */ jsxs("div", {
-		className: "flex flex-col gap-4 mb-10",
-		children: [/* @__PURE__ */ jsxs("div", {
-			className: "flex gap-3",
-			children: [config.versions && /* @__PURE__ */ jsx(VersionSelector, { className: "flex-1 justify-between h-10 bg-surface border-subtle rounded-xl" }), config.i18n && /* @__PURE__ */ jsx(I18nSelector, { className: "flex-1 justify-between h-10 bg-surface border-subtle rounded-xl" })]
-		}), /* @__PURE__ */ jsx("div", { className: "mt-2 border-b border-subtle" })]
-	}), /* @__PURE__ */ jsx(Sidebar$1.Items, { routes })] })] })] });
+	})] });
+}
+function SidebarItems(props) {
+	const { classNames, ...rest } = props;
+	return /* @__PURE__ */ jsx(Sidebar$1.Items, {
+		...rest,
+		className: cn("flex flex-col gap-6", rest.className),
+		classNames: mergeSlots(defaultItemsClassNames, classNames)
+	});
 }
 const Sidebar = Object.assign(SidebarMain, {
 	Root: Sidebar$1.Root,
@@ -1805,7 +1999,7 @@ const Sidebar = Object.assign(SidebarMain, {
 	Link: Sidebar$1.Link,
 	SubGroup: Sidebar$1.SubGroup,
 	Item: Sidebar$1.Item,
-	Items: Sidebar$1.Items
+	Items: SidebarItems
 });
 
 //#endregion
@@ -1969,10 +2163,12 @@ function Giscus({ className }) {
 			return () => {
 				initializedRef.current = false;
 				if (script.parentNode) script.parentNode.removeChild(script);
-				(ref.current?.querySelectorAll("iframe"))?.forEach((iframe) => iframe.remove());
+				(ref.current?.querySelectorAll("iframe"))?.forEach((iframe) => {
+					iframe.remove();
+				});
 			};
 		}
-	}, [giscusConfig]);
+	}, [giscusConfig, resolvedTheme]);
 	useEffect(() => {
 		if (!giscusConfig || !initializedRef.current) return;
 		const theme = giscusConfig.theme || (resolvedTheme === "dark" ? "dark" : "light");
@@ -1986,14 +2182,44 @@ function Giscus({ className }) {
 	});
 }
 
+//#endregion
+//#region src/shared/mdx-path.ts
+function normalizeMdxPath(value) {
+	return value.replace(/\\/g, "/").replace(/^\/+/, "");
+}
+function matchesMdxUpdatePath(routeFilePath, updateRelativePath) {
+	return normalizeMdxPath(routeFilePath) === normalizeMdxPath(updateRelativePath);
+}
+
 //#endregion
 //#region src/client/ssg/mdx-elements.tsx
-const Loading = () => /* @__PURE__ */ jsx("div", {
-	className: "text-muted text-sm py-4",
-	children: "Loading..."
-});
-function resolveModuleLoader(loader) {
-	return typeof loader === "function" ? loader() : Promise.resolve(loader);
+async function resolveModuleLoader(loader) {
+	if (typeof loader !== "function") return Promise.resolve(loader);
+	try {
+		const res = loader();
+		if (res && typeof res.then === "function") return await res;
+		return { default: loader };
+	} catch {
+		return { default: loader };
+	}
+}
+function extractMdxComponent(mod, moduleKey, pathKey) {
+	if (!mod) return null;
+	let target = mod;
+	if (mod.default !== void 0) target = mod.default;
+	if (typeof target === "function" || typeof target === "string") return target;
+	if (target && typeof target === "object") {
+		const possibleKeys = [moduleKey, pathKey].filter(Boolean);
+		for (const key of possibleKeys) {
+			const value = target[key];
+			if (value) {
+				if (typeof value === "function" || typeof value === "string") return value;
+				if (typeof value === "object" && value.default) return value.default;
+			}
+		}
+		if (target.default !== void 0) return extractMdxComponent({ default: target.default }, moduleKey, pathKey);
+	}
+	return null;
 }
 const EagerMdxElement = ({ moduleLoader, moduleKey, route, components, collectionPostComponent }) => {
 	const [mod, setMod] = useState(moduleLoader);
@@ -2003,16 +2229,20 @@ const EagerMdxElement = ({ moduleLoader, moduleKey, route, components, collectio
 	useEffect(() => {
 		if (!import.meta.hot || !moduleKey) return;
 		const handler = (data) => {
-			if (data.relPath.replace(/\\/g, "/").replace(/^\//, "") !== route.filePath.replace(/\\/g, "/").replace(/^\//, "")) return;
-			import(moduleKey + "?t=" + Date.now()).then((m) => {
+			if (!matchesMdxUpdatePath(route.filePath, data.relPath)) return;
+			import(`${import.meta.env.BASE_URL.replace(/\/$/, "")}${moduleKey}?t=${Date.now()}`).then((m) => {
 				setMod(m);
 			});
 		};
-		import.meta.hot.on("boltdocs:mdx-update", handler);
-		return () => import.meta.hot?.off("boltdocs:mdx-update", handler);
+		const hot = import.meta.hot;
+		hot.on("boltdocs:mdx-update", handler);
+		return () => hot.off?.("boltdocs:mdx-update", handler);
 	}, [moduleKey, route.filePath]);
-	const MDXComponent = mod?.default ?? mod ?? null;
-	if (!MDXComponent) return /* @__PURE__ */ jsx(Loading, {});
+	const MDXComponent = extractMdxComponent(mod, moduleKey, route.path || "/");
+	if (!MDXComponent) return /* @__PURE__ */ jsxs("div", {
+		className: "prose dark:prose-invert py-8",
+		children: [/* @__PURE__ */ jsx("h1", { children: route.title }), route.description && /* @__PURE__ */ jsx("p", { children: route.description })]
+	});
 	return /* @__PURE__ */ jsx(MdxPage, {
 		MDXComponent,
 		mdxComponents: components ?? {},
@@ -2086,21 +2316,59 @@ function buildModuleMap(mdxModules) {
 	}
 	return moduleMap;
 }
+function cleanModulePath(value) {
+	return value.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/\([^)]+\)/g, "").replace(/^\([^)]+\)\//, "");
+}
+/**
+* Resolves a route source path against both Vite glob keys and relative keys.
+* Exact cleaned matches are preferred so `es/guide.md` cannot select the
+* default-locale `guide.md` when both modules are present.
+*/
+function resolveModuleKey(filePath, moduleMap) {
+	const normalized = filePath.replace(/\\/g, "/");
+	const cleanPath = cleanModulePath(normalized);
+	for (const candidate of [
+		normalized,
+		normalized.replace(/^\//, ""),
+		cleanPath
+	]) {
+		const direct = moduleMap.get(candidate);
+		if (direct) return direct;
+	}
+	for (const [relativePath, moduleKey] of moduleMap.entries()) {
+		const cleanRelative = cleanModulePath(relativePath);
+		if (normalized.endsWith(relativePath) || relativePath.endsWith(normalized) || cleanPath.endsWith(cleanRelative) || cleanRelative.endsWith(cleanPath)) return moduleKey;
+	}
+}
 
 //#endregion
 //#region src/client/ssg/create-routes.doc.tsx
+function FallbackWrapper({ children }) {
+	return /* @__PURE__ */ jsx(Fragment$1, { children });
+}
 function buildDocRoutes(options) {
 	const { routesData, config, mdxModules, components, externalPages } = options;
 	const baseDocsPath = (config.base || "/docs").replace(/\/$/, "") || "/";
 	const defaultVersionMetadata = [];
 	const defaultVersion = config.versions?.defaultVersion;
 	const docsBase = (config.base || "/docs").replace(/\/$/, "");
+	const urlConfig = {
+		base: config.base,
+		i18n: config.i18n,
+		versions: config.versions,
+		collections: []
+	};
 	if (defaultVersion) routesData.filter((r) => !r.collection).forEach((route) => {
 		if (route.version) return;
 		const p = route.path || "";
 		const subPath = p.startsWith(docsBase) ? p.substring(docsBase.length).replace(/^\//, "") : p.replace(/^\//, "");
-		if (!(subPath === defaultVersion || subPath.startsWith(`${defaultVersion}/`))) {
-			const explicitPath = `${docsBase}/${defaultVersion}/${subPath}`.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+		if (!(route.version === defaultVersion)) {
+			const explicitPath = buildUrl({
+				kind: "doc",
+				path: `/${subPath}`,
+				locale: route.locale,
+				version: defaultVersion
+			}, urlConfig);
 			defaultVersionMetadata.push({
 				...route,
 				path: explicitPath,
@@ -2110,16 +2378,22 @@ function buildDocRoutes(options) {
 	});
 	const docMetadata = [...routesData.filter((r) => !r.collection), ...defaultVersionMetadata];
 	const moduleMap = buildModuleMap(mdxModules);
-	const mdxModuleKeys = Object.keys(mdxModules);
-	const isLazy = mdxModuleKeys.length > 0 && typeof mdxModules[mdxModuleKeys[0]] === "function";
+	const routeMetadata = /* @__PURE__ */ new Map();
+	const getDocumentIdentity = (route) => {
+		const parsed = parseUrlReference(route.path, urlConfig, { kind: "doc" });
+		return {
+			path: parsed.routePath,
+			version: route.version || parsed.version || config.versions?.defaultVersion
+		};
+	};
 	const docRoutes = docMetadata.map((route) => {
-		const normalizedFilePath = route.filePath.replace(/\\/g, "/");
-		const moduleKey = moduleMap.get(normalizedFilePath);
+		const moduleKey = resolveModuleKey(route.filePath, moduleMap);
 		const moduleLoader = moduleKey ? mdxModules[moduleKey] : null;
 		const fullPath = withBase(route.path === "" ? "/" : route.path, config);
 		const path = fullPath === baseDocsPath ? "." : fullPath.startsWith(baseDocsPath + "/") ? fullPath.slice(baseDocsPath.length + 1) : fullPath;
 		const routeRecord = {
 			path,
+			locale: route.locale,
 			loader: async () => ({
 				path,
 				frontmatter: {
@@ -2139,7 +2413,8 @@ function buildDocRoutes(options) {
 			}),
 			getStaticPaths: () => [path]
 		};
-		if (isLazy && moduleLoader) routeRecord.lazy = async () => {
+		routeMetadata.set(routeRecord, route);
+		if (moduleLoader) routeRecord.lazy = async () => {
 			const mod = await resolveModuleLoader(moduleLoader);
 			return { Component: function LoadedMdxRoute() {
 				return /* @__PURE__ */ jsx(EagerMdxElement, {
@@ -2147,7 +2422,7 @@ function buildDocRoutes(options) {
 					moduleLoader: mod,
 					route,
 					components: components ?? {}
-				}, moduleKey || path);
+				}, `${moduleKey || path}-${route.locale || config.i18n?.defaultLocale || "en"}`);
 			} };
 		};
 		else routeRecord.element = /* @__PURE__ */ jsx(EagerMdxElement, {
@@ -2155,95 +2430,147 @@ function buildDocRoutes(options) {
 			moduleLoader: moduleLoader ?? {},
 			route,
 			components: components ?? {}
-		}, moduleKey || path);
+		}, `${moduleKey || path}-${route.locale || config.i18n?.defaultLocale || "en"}`);
 		return routeRecord;
 	});
 	const locales = config.i18n?.locales ? Array.isArray(config.i18n.locales) ? config.i18n.locales : Object.keys(config.i18n.locales) : [];
 	const allVersions = config.versions?.versions?.map((v) => v.path) || [];
 	const targetBasePaths = [];
-	targetBasePaths.push({
-		path: baseDocsPath,
-		filter: () => true,
-		locale: config.i18n?.defaultLocale,
-		version: config.versions?.defaultVersion
-	});
-	if (allVersions.length > 0) allVersions.forEach((v) => {
-		const fullP = baseDocsPath === "/" ? `/${v}` : `${baseDocsPath}/${v}`;
+	const addTargetBase = (locale, version) => {
+		const fullPath = buildUrl({
+			kind: "doc",
+			path: "/",
+			locale,
+			version
+		}, urlConfig);
 		targetBasePaths.push({
-			path: fullP,
-			filter: (rp) => !!rp && rp.startsWith(fullP.replace(/\/$/, "") + "/"),
-			locale: config.i18n?.defaultLocale,
-			version: v
+			path: fullPath,
+			locale,
+			version
 		});
-	});
-	if (locales.length > 0) locales.forEach((l) => {
-		const fullP = baseDocsPath === "/" ? `/${l}` : `${baseDocsPath}/${l}`;
-		targetBasePaths.push({
-			path: fullP,
-			filter: (rp) => !!rp && rp.startsWith(fullP.replace(/\/$/, "") + "/"),
-			locale: l,
-			version: config.versions?.defaultVersion
-		});
-	});
-	if (allVersions.length > 0 && locales.length > 0) allVersions.forEach((v) => {
-		locales.forEach((l) => {
-			const fullP = baseDocsPath === "/" ? `/${v}/${l}` : `${baseDocsPath}/${v}/${l}`;
-			targetBasePaths.push({
-				path: fullP,
-				filter: (rp) => !!rp && rp.startsWith(fullP.replace(/\/$/, "") + "/"),
-				locale: l,
-				version: v
-			});
-		});
-	});
+	};
+	addTargetBase(config.i18n?.defaultLocale);
+	for (const version of allVersions) addTargetBase(config.i18n?.defaultLocale, version);
+	for (const locale of locales) addTargetBase(locale);
+	for (const version of allVersions) for (const locale of locales) addTargetBase(locale, version);
 	const docPathRegistry = new Set(docRoutes.map((r) => (r.path || "").replace(/\/$/, "")));
 	const externalPaths = /* @__PURE__ */ new Set();
 	if (externalPages) Object.keys(externalPages).forEach((rawPath) => {
 		const p = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
 		externalPaths.add(p.replace(/\/$/, ""));
-		if (config.i18n) Object.keys(config.i18n.locales).forEach((locale) => {
+		if (config.i18n) (Array.isArray(config.i18n.locales) ? config.i18n.locales : Object.keys(config.i18n.locales)).forEach((locale) => {
 			externalPaths.add(`/${locale}${p === "/" ? "" : p}`.replace(/\/$/, ""));
 		});
 	});
-	targetBasePaths.forEach(({ path: bPath, filter, locale: bLocale, version: bVersion }) => {
+	targetBasePaths.forEach(({ path: bPath, locale: bLocale, version: bVersion }) => {
 		if (bPath === "/") return;
 		const normalizedPath = bPath.replace(/\/$/, "");
 		if (!(docPathRegistry.has(normalizedPath) || externalPaths.has(normalizedPath))) {
 			const defaultTab = config.theme?.tabs?.[0]?.id;
 			const defaultTabPath = defaultTab ? `${normalizedPath}/${defaultTab}`.replace(/\/+/g, "/") : null;
-			let matchedRouteObj = defaultTabPath && docPathRegistry.has(defaultTabPath.replace(/\/$/, "")) ? docRoutes.find((r) => r.path && r.path.replace(/\/$/, "") === defaultTabPath.replace(/\/$/, "")) : docRoutes.find((r) => r.path && filter(r.path) && r.path !== normalizedPath);
+			let matchedRouteObj = defaultTabPath ? docRoutes.find((r) => {
+				return routeMetadata.get(r)?.path?.replace(/\/$/, "") === defaultTabPath.replace(/\/$/, "");
+			}) : void 0;
+			if (!matchedRouteObj) matchedRouteObj = docRoutes.find((r) => {
+				const routePath = routeMetadata.get(r)?.path?.replace(/\/$/, "");
+				return !!routePath && (routePath === normalizedPath || routePath.startsWith(`${normalizedPath}/`));
+			});
 			if (!matchedRouteObj && docRoutes.length > 0) matchedRouteObj = docRoutes[0];
+			if (matchedRouteObj && bLocale) {
+				const localeBaseRoute = matchedRouteObj;
+				const defaultLocale = config.i18n?.defaultLocale;
+				const matchedMeta = routeMetadata.get(localeBaseRoute);
+				const matchedIdentity = matchedMeta ? getDocumentIdentity(matchedMeta) : void 0;
+				const localeMatch = docRoutes.find((r) => {
+					const meta = routeMetadata.get(r);
+					if (!meta || !matchedIdentity) return false;
+					if (!(meta.locale === bLocale || bLocale === defaultLocale && !meta.locale)) return false;
+					const identity = getDocumentIdentity(meta);
+					return identity.path === matchedIdentity.path && identity.version === (bVersion || config.versions?.defaultVersion);
+				});
+				if (localeMatch) matchedRouteObj = localeMatch;
+			}
 			if (matchedRouteObj) {
+				const matchedRoute = matchedRouteObj;
 				const redirectPath = bPath === baseDocsPath ? "." : bPath.startsWith(baseDocsPath + "/") ? bPath.slice(baseDocsPath.length + 1) : bPath;
 				const isBasePathFallback = redirectPath === ".";
-				docRoutes.push({
+				const matchedMetaObj = (() => {
+					const matchedMeta = routeMetadata.get(matchedRoute);
+					if (!matchedMeta) return void 0;
+					const matchedIdentity = getDocumentIdentity(matchedMeta);
+					const targetVersion = bVersion || config.versions?.defaultVersion;
+					const targetLocale = bLocale || config.i18n?.defaultLocale;
+					return docMetadata.find((m) => {
+						const identity = getDocumentIdentity(m);
+						const locale = m.locale || config.i18n?.defaultLocale;
+						return identity.path === matchedIdentity.path && locale === targetLocale && identity.version === targetVersion;
+					}) || matchedMeta;
+				})();
+				const fallbackMetaObj = matchedMetaObj ? {
+					...matchedMetaObj,
+					path: bPath,
+					filePath: matchedMetaObj.filePath,
+					locale: bLocale,
+					version: bVersion,
+					slugParts: [],
+					fallback: true,
+					seo: {
+						...matchedMetaObj.seo,
+						canonical: config.siteUrl ? `${config.siteUrl.replace(/\/$/, "")}${withBase(bPath, config)}` : withBase(bPath, config)
+					}
+				} : {
+					path: bPath,
+					filePath: "",
+					title: redirectPath,
+					componentPath: "",
+					headings: [],
+					locale: bLocale,
+					version: bVersion,
+					fallback: true
+				};
+				const fallbackRoute = {
 					...isBasePathFallback ? { index: true } : { path: redirectPath },
-					element: matchedRouteObj.element,
-					lazy: matchedRouteObj.lazy,
-					loader: matchedRouteObj.loader,
+					locale: bLocale,
+					loader: matchedRoute.loader,
 					getStaticPaths: () => []
+				};
+				const resolveFallbackComponent = async () => {
+					const moduleKey = resolveModuleKey(fallbackMetaObj.filePath, moduleMap);
+					const moduleLoader = moduleKey ? mdxModules[moduleKey] : null;
+					const localeKey = bLocale || config.i18n?.defaultLocale || "en";
+					const key = `${moduleKey || bPath}-${localeKey}`;
+					if (!moduleLoader) return null;
+					return /* @__PURE__ */ jsx(EagerMdxElement, {
+						moduleKey,
+						moduleLoader: await resolveModuleLoader(moduleLoader),
+						route: fallbackMetaObj,
+						components: components ?? {}
+					}, key);
+				};
+				if (matchedRoute.lazy) fallbackRoute.lazy = async () => {
+					const fallbackComponent = await resolveFallbackComponent();
+					return { Component: () => /* @__PURE__ */ jsx(FallbackWrapper, { children: fallbackComponent }) };
+				};
+				else if (matchedRoute.element) fallbackRoute.element = matchedRoute.element;
+				fallbackRoute.loader = async () => ({
+					path: redirectPath,
+					frontmatter: {
+						title: fallbackMetaObj.title,
+						description: fallbackMetaObj.description || "",
+						...fallbackMetaObj.frontmatter || {}
+					},
+					seo: fallbackMetaObj.seo,
+					headings: fallbackMetaObj.headings || [],
+					filePath: fallbackMetaObj.filePath,
+					locale: fallbackMetaObj.locale,
+					version: fallbackMetaObj.version,
+					group: fallbackMetaObj.group,
+					groupTitle: fallbackMetaObj.groupTitle,
+					date: fallbackMetaObj.date,
+					lastUpdated: fallbackMetaObj.lastUpdated
 				});
-				const matchedMetaObj = docMetadata.find((m) => {
-					const fullPath = withBase(m.path === "" ? "/" : m.path, config);
-					return (fullPath === baseDocsPath ? "." : fullPath.startsWith(baseDocsPath + "/") ? fullPath.slice(baseDocsPath.length + 1) : fullPath) === matchedRouteObj.path;
-				});
-				if (matchedMetaObj) {
-					const canonicalPath = withBase(matchedMetaObj.path, config);
-					const canonicalUrl = config.siteUrl ? `${config.siteUrl.replace(/\/$/, "")}${canonicalPath}` : canonicalPath;
-					docMetadata.push({
-						...matchedMetaObj,
-						path: bPath,
-						filePath: matchedMetaObj.filePath,
-						locale: bLocale,
-						version: bVersion,
-						slugParts: [],
-						fallback: true,
-						seo: {
-							...matchedMetaObj.seo,
-							canonical: canonicalUrl
-						}
-					});
-				}
+				docRoutes.push(fallbackRoute);
+				docMetadata.push(fallbackMetaObj);
 			}
 		}
 	});
@@ -2264,6 +2591,97 @@ function ExternalPageWrapper({ children }) {
 
 //#endregion
 //#region src/client/ssg/create-routes.external.tsx
+function getLocales(config) {
+	if (!config.i18n) return [];
+	return Array.isArray(config.i18n.locales) ? config.i18n.locales : Object.keys(config.i18n.locales);
+}
+function getLocalizedPaths(pathname, config) {
+	const paths = [{
+		path: pathname,
+		locale: config.i18n?.defaultLocale
+	}];
+	for (const locale of getLocales(config)) {
+		const localizedPath = pathname === "/" ? `/${locale}` : `/${locale}${pathname}`;
+		if (!paths.some((entry) => entry.path === localizedPath)) paths.push({
+			path: localizedPath,
+			locale
+		});
+	}
+	return paths;
+}
+/**
+* Content wrapper for file-routed MDX pages. The external layout renders the
+* site chrome (navbar/footer), but unlike docs pages these routes are not
+* nested inside DocsLayout, so the MDX content needs its own page container
+* with the page title and prose typography — otherwise it renders raw and
+* edge-to-edge directly below the navbar.
+*/
+function ExternalMdxContent({ title, children, className, contentClassName }) {
+	return /* @__PURE__ */ jsx("div", {
+		className: cn("boltdocs-page w-full pt-4 pb-20 px-4 sm:px-8", className),
+		children: /* @__PURE__ */ jsxs("div", {
+			className: cn("mx-auto w-full max-w-3xl sm:max-w-4xl lg:max-w-5xl", contentClassName),
+			children: [title && /* @__PURE__ */ jsx("h1", {
+				className: "text-4xl font-bold tracking-tight text-body mb-3",
+				children: title
+			}), /* @__PURE__ */ jsx("div", {
+				className: "prose prose-neutral dark:prose-invert max-w-none",
+				children
+			})]
+		})
+	});
+}
+function routeTitle(pathname) {
+	const segment = pathname === "/" ? "Home" : pathname.split("/").filter(Boolean).at(-1);
+	return segment ? segment.replace(/[-_]/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase()) : "Page";
+}
+function buildExternalRouteRecord(options) {
+	const { path, locale, component, mdxLoader, externalLayout, components, title } = options;
+	const record = {
+		path,
+		locale,
+		loader: async () => ({
+			path,
+			locale
+		}),
+		getStaticPaths: () => [path]
+	};
+	const ExternalLayout = externalLayout;
+	const ExternalComponent = component;
+	if (ExternalComponent) record.element = /* @__PURE__ */ jsx(ExternalPageWrapper, { children: /* @__PURE__ */ jsx(ExternalLayout, { children: /* @__PURE__ */ jsx(ExternalComponent, {}) }) });
+	else if (mdxLoader) record.lazy = async () => {
+		const module = await resolveModuleLoader(mdxLoader);
+		return { Component: function ExternalMdxRoute() {
+			return /* @__PURE__ */ jsx(ExternalPageWrapper, { children: /* @__PURE__ */ jsx(ExternalLayout, { children: /* @__PURE__ */ jsx(ExternalMdxContent, {
+				title,
+				children: /* @__PURE__ */ jsx(EagerMdxElement, {
+					moduleLoader: module,
+					moduleKey: path,
+					route: {
+						path,
+						title,
+						filePath: path,
+						componentPath: "",
+						headings: [],
+						locale
+					},
+					components: components || {}
+				})
+			}) }) });
+		} };
+	};
+	return record;
+}
+function buildExternalRouteMetadata(path, locale, title) {
+	return {
+		path,
+		locale,
+		title,
+		filePath: "",
+		componentPath: "",
+		headings: []
+	};
+}
 function buildExternalRoutes(options) {
 	const { externalPages, externalLayout, config } = options;
 	const children = [];
@@ -2272,56 +2690,78 @@ function buildExternalRoutes(options) {
 		children,
 		metadata
 	};
-	const EffectiveExternalLayout = externalLayout || (({ children }) => /* @__PURE__ */ jsx(Fragment, { children }));
+	const EffectiveExternalLayout = externalLayout || (({ children }) => /* @__PURE__ */ jsx(Fragment$1, { children }));
 	Object.entries(externalPages).forEach(([rawPath, ExtComponent]) => {
-		const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
-		metadata.push({
-			path,
-			locale: config.i18n?.defaultLocale,
-			title: rawPath === "/" ? "Home" : rawPath.replace(/^\//, "").split("/").pop() || "Page",
-			filePath: "",
-			componentPath: "",
-			headings: []
-		});
-		children.push({
-			path,
-			element: /* @__PURE__ */ jsx(ExternalPageWrapper, { children: /* @__PURE__ */ jsx(EffectiveExternalLayout, { children: /* @__PURE__ */ jsx(ExtComponent, {}) }) }),
-			loader: async () => ({
-				path,
-				locale: config.i18n?.defaultLocale
-			}),
-			getStaticPaths: () => [path]
-		});
-		if (config.i18n) Object.keys(config.i18n.locales).forEach((locale) => {
-			const localePath = `/${locale}${rawPath === "/" ? "" : rawPath}`;
-			metadata.push({
-				path: localePath,
-				locale,
-				title: rawPath,
-				filePath: "",
-				componentPath: "",
-				headings: []
-			});
-			children.push({
-				path: localePath,
-				element: /* @__PURE__ */ jsx(ExternalPageWrapper, { children: /* @__PURE__ */ jsx(EffectiveExternalLayout, { children: /* @__PURE__ */ jsx(ExtComponent, {}) }) }),
-				loader: async () => ({
-					path: localePath,
-					locale
-				}),
-				getStaticPaths: () => [localePath]
-			});
-		});
+		const pathname = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+		for (const localized of getLocalizedPaths(pathname, config)) {
+			metadata.push(buildExternalRouteMetadata(localized.path, localized.locale, routeTitle(pathname)));
+			children.push({ ...buildExternalRouteRecord({
+				path: localized.path,
+				locale: localized.locale,
+				component: ExtComponent,
+				externalLayout: EffectiveExternalLayout,
+				title: routeTitle(pathname)
+			}) });
+		}
 	});
 	return {
 		children,
 		metadata
 	};
 }
+function buildExternalFileRoutes(options) {
+	const { externalFilePages, externalFileMdx, externalLayout, components, config } = options;
+	const children = [];
+	const metadata = [];
+	if (!externalFilePages && !externalFileMdx) return {
+		children,
+		metadata
+	};
+	const EffectiveExternalLayout = externalLayout || (({ children }) => /* @__PURE__ */ jsx(Fragment$1, { children }));
+	const locales = getLocales(config);
+	const isLocalizedPath = (pathname) => locales.some((locale) => pathname === `/${locale}` || pathname.startsWith(`/${locale}/`));
+	const localeOfPath = (pathname) => {
+		const first = pathname.split("/").filter(Boolean)[0];
+		return first && locales.includes(first) ? first : void 0;
+	};
+	const fileRoutes = new Set([...Object.keys(externalFilePages || {}), ...Object.keys(externalFileMdx || {})]);
+	const registeredPaths = /* @__PURE__ */ new Set();
+	const pushRoute = (pathname, locale, mdxLoader, component) => {
+		if (registeredPaths.has(pathname)) return;
+		registeredPaths.add(pathname);
+		metadata.push(buildExternalRouteMetadata(pathname, locale, routeTitle(pathname)));
+		children.push(buildExternalRouteRecord({
+			path: pathname,
+			locale,
+			component,
+			mdxLoader,
+			externalLayout: EffectiveExternalLayout,
+			components,
+			title: routeTitle(pathname)
+		}));
+	};
+	for (const pathname of fileRoutes) pushRoute(pathname, localeOfPath(pathname) || config.i18n?.defaultLocale, externalFileMdx?.[pathname], externalFilePages?.[pathname]);
+	for (const pathname of fileRoutes) {
+		if (isLocalizedPath(pathname)) continue;
+		const mdxLoader = externalFileMdx?.[pathname];
+		const component = externalFilePages?.[pathname];
+		for (const localized of getLocalizedPaths(pathname, config)) pushRoute(localized.path, localized.locale, mdxLoader, component);
+	}
+	return {
+		children,
+		metadata
+	};
+}
 
 //#endregion
 //#region src/client/collections/hooks.ts
 const DEFAULT_COLLECTION = "blog";
+const NO_DATE = Number.NEGATIVE_INFINITY;
+function getPostTimestamp(date) {
+	if (!date) return NO_DATE;
+	const timestamp = new Date(date).getTime();
+	return Number.isFinite(timestamp) ? timestamp : NO_DATE;
+}
 /**
 * Returns the posts of a collection, filtered by the current locale and version.
 * Defaults to "blog" if no collection is specified.
@@ -2345,6 +2785,10 @@ function usePosts(collection = DEFAULT_COLLECTION, options) {
 			const versionMatch = !currentVersion || postVersion === currentVersion;
 			const draftMatch = options?.includeDrafts || !post.draft;
 			return localeMatch && versionMatch && draftMatch;
+		}).sort((a, b) => {
+			const dateA = getPostTimestamp(a.date);
+			const dateOrder = getPostTimestamp(b.date) - dateA;
+			return dateOrder !== 0 ? dateOrder : a.path.localeCompare(b.path);
 		});
 	}, [
 		posts,
@@ -2396,20 +2840,57 @@ function useRecentPosts(collection = DEFAULT_COLLECTION, count = 5) {
 
 //#endregion
 //#region src/client/ssg/create-routes.collection.tsx
+function CollectionIndex({ indexContent, ListElement }) {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [indexContent, /* @__PURE__ */ jsx(ListElement, {})] });
+}
+function splitCollectionPath(routePath) {
+	return routePath.split("/").filter(Boolean);
+}
+/**
+* Resolve the child path of a collection post relative to its layout route.
+*
+* Route generation emits collection paths without the configured docs base
+* (e.g. `/blog/post` or `/es/blog/post`), while the collection layout lives
+* under the base (`/docs/blog`). Keeping everything after the collection
+* segment as a *relative* child path is what makes the router match
+* `/docs/blog/post` and the SSG emit `dist/docs/blog/post.html` — never a
+* root-level `/blog/post` that neither the matcher nor the cache can reach.
+*/
+function getCollectionSubPath(routePath, colBase, collection) {
+	if (routePath.startsWith(`${colBase}/`)) return routePath.slice(colBase.length + 1);
+	const parts = splitCollectionPath(routePath);
+	const collectionIndex = parts.indexOf(collection);
+	if (collectionIndex >= 0) return parts.slice(collectionIndex + 1).join("/");
+	return parts.join("/");
+}
+function isCollectionIndexRoute(route, collection) {
+	const normalizedPath = route.path.replace(/\/$/, "");
+	return normalizedPath === `/${collection}` || normalizedPath.endsWith(`/${collection}`);
+}
+function getCollectionModule(route, moduleMap, mdxModules) {
+	const moduleKey = resolveModuleKey(route.filePath, moduleMap);
+	return {
+		moduleKey,
+		moduleLoader: moduleKey ? mdxModules[moduleKey] : null
+	};
+}
 function DefaultCollectionList() {
-	const location = useLocation$1();
+	const location = useLocation();
 	const config = useConfig();
+	const loaderData = useLoaderData();
 	const postsPerPage = config.collections?.postsPerPage ?? 10;
-	const segments = location.pathname.split("/").filter(Boolean);
-	const isLocalePrefixed = config.i18n && segments[0] in (config.i18n.locales || {});
-	const collection = isLocalePrefixed ? segments[1] : segments[0];
-	const currentPage = (isLocalePrefixed ? segments[3] : segments[2]) === "page" ? Number(isLocalePrefixed ? segments[4] : segments[3]) || 1 : 1;
+	const basePath = location.pathname.replace(/\/page\/\d+\/?$/, "").replace(/\/$/, "");
+	const segments = basePath.split("/").filter(Boolean);
+	const collection = loaderData && loaderData.collection || segments[segments.length - 1];
 	const allPosts = usePosts(collection);
-	const totalPages = Math.ceil(allPosts.length / postsPerPage);
+	const totalPages = loaderData && loaderData.totalPages || Math.ceil(allPosts.length / postsPerPage);
+	const currentPage = loaderData && loaderData.currentPage || (() => {
+		const match = location.pathname.match(/\/page\/(\d+)\/?$/);
+		return match ? Number(match[1]) : 1;
+	})();
 	const start = (currentPage - 1) * postsPerPage;
-	const posts = allPosts.slice(start, start + postsPerPage);
+	const posts = loaderData && loaderData.posts || allPosts.slice(start, start + postsPerPage);
 	if (!posts.length) return null;
-	const basePath = isLocalePrefixed ? `/${segments[0]}/${segments[1]}` : `/${segments[0]}`;
 	return /* @__PURE__ */ jsxs("div", {
 		className: "py-8 max-w-2xl mx-auto px-4",
 		children: [
@@ -2476,111 +2957,197 @@ function buildCollectionRoutes(options) {
 		collectionsMap.get(r.collection).push(r);
 	}
 	const moduleMap = buildModuleMap(mdxModules);
-	const mdxModuleKeys = Object.keys(mdxModules);
-	const isLazy = mdxModuleKeys.length > 0 && typeof mdxModules[mdxModuleKeys[0]] === "function";
+	const defaultLocale = config.i18n?.defaultLocale || "en";
 	for (const [colName, colRoutes] of collectionsMap) {
-		const colBase = `/${colName}`;
-		colRoutes.sort((a, b) => {
-			const da = a.date ? new Date(a.date).getTime() : 0;
-			return (b.date ? new Date(b.date).getTime() : 0) - da;
-		});
-		const colChildren = [];
-		for (const route of colRoutes) {
-			const normalizedFilePath = route.filePath.replace(/\\/g, "/");
-			const moduleKey = moduleMap.get(normalizedFilePath);
-			const moduleLoader = moduleKey ? mdxModules[moduleKey] : null;
-			const subPath = route.path.startsWith(colBase + "/") ? route.path.slice(colBase.length + 1) : route.path.replace(colBase, "") || "";
-			const routeWithCollection = {
-				...route,
-				collection: colName
-			};
-			const postComponent = collectionPosts?.[colName];
-			const routeRecord = {
-				path: subPath,
+		const postsByVariant = /* @__PURE__ */ new Map();
+		const indexByVariant = /* @__PURE__ */ new Map();
+		for (const r of colRoutes) {
+			const effectiveLocale = r.locale || defaultLocale;
+			const key = `${r.version || ""}::${effectiveLocale}`;
+			if (!postsByVariant.has(key)) postsByVariant.set(key, []);
+			if (isCollectionIndexRoute(r, colName)) indexByVariant.set(key, r);
+			else postsByVariant.get(key).push(r);
+		}
+		for (const [variant, variantRoutes] of postsByVariant) {
+			const [version, locale] = variant.split("::");
+			const localeRoutes = variantRoutes;
+			const colBase = buildUrl({
+				kind: "collection",
+				collection: colName,
+				path: "/",
+				locale: locale === defaultLocale ? void 0 : locale,
+				version: version || void 0
+			}, {
+				base: config.base,
+				i18n: config.i18n,
+				versions: config.versions,
+				collections: [colName]
+			});
+			localeRoutes.sort((a, b) => {
+				const getTimestamp = (date) => {
+					if (!date) return Number.NEGATIVE_INFINITY;
+					const value = new Date(date).getTime();
+					return Number.isFinite(value) ? value : Number.NEGATIVE_INFINITY;
+				};
+				const da = getTimestamp(a.date);
+				const dateOrder = getTimestamp(b.date) - da;
+				return dateOrder !== 0 ? dateOrder : a.path.localeCompare(b.path);
+			});
+			const colChildren = [];
+			for (const route of localeRoutes) {
+				const { moduleKey, moduleLoader } = getCollectionModule(route, moduleMap, mdxModules);
+				const subPath = getCollectionSubPath(route.path, colBase, colName);
+				const routeWithCollection = {
+					...route,
+					collection: colName
+				};
+				const postComponent = collectionPosts?.[colName];
+				const routeRecord = {
+					path: subPath,
+					loader: async () => ({
+						route: routeWithCollection,
+						headings: route.headings || [],
+						collection: colName,
+						path: subPath,
+						frontmatter: {
+							title: route.title,
+							description: route.description || "",
+							...route.frontmatter || {}
+						},
+						filePath: route.filePath,
+						locale: route.locale,
+						version: route.version,
+						date: route.date,
+						lastUpdated: route.lastUpdated
+					}),
+					getStaticPaths: () => [subPath || "."]
+				};
+				if (moduleLoader) routeRecord.lazy = async () => {
+					const mod = await resolveModuleLoader(moduleLoader);
+					return { Component: function LoadedCollectionMdxRoute() {
+						return /* @__PURE__ */ jsx(EagerMdxElement, {
+							moduleKey,
+							moduleLoader: mod,
+							route,
+							components,
+							collectionPostComponent: postComponent
+						}, `${moduleKey || subPath}-${locale}`);
+					} };
+				};
+				else routeRecord.element = /* @__PURE__ */ jsx(EagerMdxElement, {
+					moduleKey,
+					moduleLoader: {},
+					route,
+					components,
+					collectionPostComponent: postComponent
+				}, `${moduleKey || subPath}-${locale}`);
+				colChildren.push(routeRecord);
+				metadata.push(route);
+			}
+			const totalPages = Math.ceil(localeRoutes.length / postsPerPage);
+			const paginatedPosts = localeRoutes.map((r) => ({
+				path: r.path,
+				title: r.title,
+				date: r.date,
+				excerpt: r.excerpt,
+				tags: r.tags,
+				author: r.author,
+				coverImage: r.coverImage,
+				filePath: r.filePath,
+				locale: r.locale,
+				version: r.version,
+				lastUpdated: r.lastUpdated,
+				frontmatter: r.frontmatter
+			}));
+			const ListElement = collectionLists?.[colName] || DefaultCollectionList;
+			const indexRoute = indexByVariant.get(variant);
+			const indexRecord = {
+				index: true,
+				path: "",
 				loader: async () => ({
-					route: routeWithCollection,
-					headings: route.headings || [],
+					posts: paginatedPosts.slice(0, postsPerPage),
+					totalPages,
+					currentPage: 1,
 					collection: colName,
-					path: subPath,
-					frontmatter: {
-						title: route.title,
-						description: route.description || "",
-						...route.frontmatter || {}
-					},
-					filePath: route.filePath,
-					locale: route.locale,
-					version: route.version,
-					date: route.date,
-					lastUpdated: route.lastUpdated
+					...indexRoute ? {
+						route: indexRoute,
+						headings: indexRoute.headings || [],
+						frontmatter: {
+							title: indexRoute.title,
+							description: indexRoute.description || "",
+							...indexRoute.frontmatter || {}
+						},
+						filePath: indexRoute.filePath,
+						locale: indexRoute.locale,
+						version: indexRoute.version
+					} : {}
 				}),
-				getStaticPaths: () => [subPath || "."]
+				getStaticPaths: () => [""]
 			};
-			if (isLazy && moduleLoader) routeRecord.lazy = async () => {
-				const mod = await resolveModuleLoader(moduleLoader);
-				return { Component: function LoadedCollectionMdxRoute() {
-					return /* @__PURE__ */ jsx(EagerMdxElement, {
-						moduleKey,
-						moduleLoader: mod,
-						route,
-						components,
-						collectionPostComponent: postComponent
-					}, moduleKey || subPath);
-				} };
+			if (indexRoute) {
+				const { moduleKey, moduleLoader } = getCollectionModule(indexRoute, moduleMap, mdxModules);
+				const postComponent = collectionPosts?.[colName];
+				const createIndexContent = (resolvedModule) => /* @__PURE__ */ jsx(EagerMdxElement, {
+					moduleKey,
+					moduleLoader: resolvedModule,
+					route: indexRoute,
+					components,
+					collectionPostComponent: postComponent
+				}, `${moduleKey || colBase}-${locale}`);
+				if (moduleLoader) indexRecord.lazy = async () => {
+					const mod = await resolveModuleLoader(moduleLoader);
+					return { Component: function LoadedCollectionIndex() {
+						return /* @__PURE__ */ jsx(CollectionIndex, {
+							indexContent: createIndexContent(mod),
+							ListElement
+						});
+					} };
+				};
+				else indexRecord.element = /* @__PURE__ */ jsx(CollectionIndex, {
+					indexContent: createIndexContent({}),
+					ListElement
+				});
+			} else indexRecord.element = /* @__PURE__ */ jsx(ListElement, {});
+			colChildren.unshift(indexRecord);
+			metadata.push({
+				path: colBase,
+				locale,
+				collection: colName,
+				title: indexRoute?.title || colName,
+				filePath: indexRoute?.filePath || "",
+				componentPath: indexRoute?.componentPath || "",
+				headings: indexRoute?.headings || []
+			});
+			for (let p = 2; p <= totalPages; p++) {
+				const pagePath = `page/${p}`;
+				colChildren.push({
+					path: pagePath,
+					element: /* @__PURE__ */ jsx(ListElement, {}),
+					loader: async () => ({
+						posts: paginatedPosts.slice((p - 1) * postsPerPage, p * postsPerPage),
+						totalPages,
+						currentPage: p,
+						collection: colName
+					}),
+					getStaticPaths: () => [pagePath]
+				});
+				metadata.push({
+					path: `${colBase}/${pagePath}`.replace(/\/+/g, "/"),
+					locale,
+					collection: colName,
+					title: colName,
+					filePath: "",
+					componentPath: "",
+					headings: []
+				});
+			}
+			const blogLayoutRoute = {
+				path: colBase,
+				element: /* @__PURE__ */ jsx(collectionLayouts?.[colName] || DocsLayout, { collectionsData: collectionsData || {} }),
+				children: colChildren
 			};
-			else routeRecord.element = /* @__PURE__ */ jsx(EagerMdxElement, {
-				moduleKey,
-				moduleLoader,
-				route,
-				components,
-				collectionPostComponent: postComponent
-			}, moduleKey || subPath);
-			colChildren.push(routeRecord);
-			metadata.push(route);
+			children.push(blogLayoutRoute);
 		}
-		const totalPages = Math.ceil(colRoutes.length / postsPerPage);
-		const paginatedPosts = colRoutes.map((r) => ({
-			path: r.path,
-			title: r.title,
-			date: r.date,
-			excerpt: r.excerpt,
-			tags: r.tags,
-			author: r.author,
-			coverImage: r.coverImage,
-			filePath: r.filePath,
-			locale: r.locale,
-			version: r.version,
-			lastUpdated: r.lastUpdated,
-			frontmatter: r.frontmatter
-		}));
-		const ListElement = collectionLists?.[colName] || DefaultCollectionList;
-		colChildren.unshift({
-			index: true,
-			element: /* @__PURE__ */ jsx(ListElement, {}),
-			loader: async () => ({
-				posts: paginatedPosts.slice(0, postsPerPage),
-				totalPages,
-				currentPage: 1,
-				collection: colName
-			}),
-			getStaticPaths: () => []
-		});
-		for (let p = 2; p <= totalPages; p++) colChildren.push({
-			path: `page/${p}`,
-			element: /* @__PURE__ */ jsx(ListElement, {}),
-			loader: async () => ({
-				posts: paginatedPosts.slice((p - 1) * postsPerPage, p * postsPerPage),
-				totalPages,
-				currentPage: p,
-				collection: colName
-			}),
-			getStaticPaths: () => [`page/${p}`]
-		});
-		const blogLayoutRoute = {
-			path: colBase,
-			element: /* @__PURE__ */ jsx(collectionLayouts?.[colName] || DocsLayout, { collectionsData: collectionsData || {} }),
-			children: colChildren
-		};
-		children.push(blogLayoutRoute);
 	}
 	return {
 		children,
@@ -2592,10 +3159,26 @@ function buildCollectionRoutes(options) {
 //#region src/client/ssg/create-routes.tsx
 function createRoutes(options) {
 	const { config, components, externalLayout } = options;
-	const EffectiveExternalLayout = externalLayout || (({ children }) => /* @__PURE__ */ jsx(Fragment, { children }));
+	const EffectiveExternalLayout = externalLayout || (({ children }) => /* @__PURE__ */ jsx(Fragment$1, { children }));
 	const baseDocsPath = (config.base || "/docs").replace(/\/$/, "") || "/";
 	const { routes: docRoutes, metadata: docMetadata } = buildDocRoutes(options);
 	const externalRoutes = buildExternalRoutes(options);
+	const externalFileRoutes = config.experimental?.fileRouting ? buildExternalFileRoutes(options) : {
+		children: [],
+		metadata: []
+	};
+	const occupiedPaths = new Set([...docMetadata.map((route) => route.path), ...externalRoutes.metadata.map((route) => route.path)]);
+	const acceptedExternalFilePaths = /* @__PURE__ */ new Set();
+	const filteredExternalFileRoutes = {
+		children: externalFileRoutes.children,
+		metadata: externalFileRoutes.metadata.filter((route) => {
+			if (occupiedPaths.has(route.path)) return false;
+			occupiedPaths.add(route.path);
+			acceptedExternalFilePaths.add(route.path);
+			return true;
+		})
+	};
+	filteredExternalFileRoutes.children = externalFileRoutes.children.filter((route) => !route.path || acceptedExternalFilePaths.has(route.path));
 	const collectionRoutes = buildCollectionRoutes(options);
 	const children = [
 		{
@@ -2604,18 +3187,20 @@ function createRoutes(options) {
 			children: docRoutes
 		},
 		...externalRoutes.children,
+		...filteredExternalFileRoutes.children,
 		...collectionRoutes.children,
 		{
 			path: "*",
 			element: /* @__PURE__ */ jsx(ExternalPageWrapper, { children: /* @__PURE__ */ jsx(EffectiveExternalLayout, { children: /* @__PURE__ */ jsx(NotFoundWrapper, {}) }) })
 		}
 	];
-	return [{
+	const routes = [{
 		element: /* @__PURE__ */ jsx(BoltdocsShell, {
 			config,
 			routes: [
 				...docMetadata,
 				...externalRoutes.metadata,
+				...filteredExternalFileRoutes.metadata,
 				...collectionRoutes.metadata
 			],
 			components,
@@ -2623,6 +3208,19 @@ function createRoutes(options) {
 		}),
 		children
 	}];
+	const BaseAwareRouteRenderer = (props) => /* @__PURE__ */ jsx(RouteRenderer, {
+		...props,
+		basename: config.base,
+		defaultLocale: config.i18n?.defaultLocale,
+		viewTransitions: config.experimental?.viewTransitions === true ? true : typeof config.experimental?.viewTransitions === "object" ? config.experimental.viewTransitions : void 0
+	});
+	return {
+		routes,
+		RouteRenderer: BaseAwareRouteRenderer,
+		matchRouteBranch,
+		matchRouteBranchWithParams,
+		resolveRouteBranch
+	};
 }
 
 //#endregion
@@ -2647,32 +3245,38 @@ function DocsLayoutComponent({ children }) {
 					routes: filteredRoutes || [],
 					config
 				}),
-				/* @__PURE__ */ jsx(DocsLayout$1.Content, { children: /* @__PURE__ */ jsxs(DocsLayout$1.ContentMdx, { children: [
-					!isCollectionPage && /* @__PURE__ */ jsxs(DocsLayout$1.Header, { children: [
-						/* @__PURE__ */ jsxs("div", {
-							className: "mb-4 border-b border-subtle pb-4 flex flex-wrap items-center justify-between gap-3",
-							children: [/* @__PURE__ */ jsx(Breadcrumbs, {}), /* @__PURE__ */ jsx(CopyMarkdown, {
-								mdxRaw: currentRoute?._rawContent,
-								route: currentRoute
-							})]
-						}),
-						currentRoute?.title && /* @__PURE__ */ jsx("h1", {
-							className: "text-4xl font-bold tracking-tight text-default mb-3",
-							children: currentRoute.title
-						}),
-						currentRoute?.description && /* @__PURE__ */ jsx("p", {
-							className: "text-lg text-muted-foreground mb-6 leading-relaxed",
-							children: currentRoute.description
+				/* @__PURE__ */ jsx(DocsLayout$1.Content, { children: /* @__PURE__ */ jsxs(DocsLayout$1.ContentMdx, {
+					className: "pt-4 pb-20 px-4 sm:px-8",
+					children: [
+						!isCollectionPage && /* @__PURE__ */ jsxs(DocsLayout$1.Header, { children: [
+							/* @__PURE__ */ jsxs("div", {
+								className: "mb-4 border-b border-subtle pb-4 flex flex-wrap items-center justify-between gap-3",
+								children: [/* @__PURE__ */ jsx(Breadcrumbs, {}), /* @__PURE__ */ jsx(CopyMarkdown, {
+									mdxRaw: currentRoute?._rawContent,
+									route: currentRoute
+								})]
+							}),
+							currentRoute?.title && /* @__PURE__ */ jsx("h1", {
+								className: "text-4xl font-bold tracking-tight text-body mb-3",
+								children: currentRoute.title
+							}),
+							currentRoute?.description && /* @__PURE__ */ jsx("p", {
+								className: "text-lg text-muted mb-6 leading-relaxed",
+								children: currentRoute.description
+							})
+						] }),
+						/* @__PURE__ */ jsx(ErrorBoundary, { children: /* @__PURE__ */ jsx("div", {
+							className: "prose prose-neutral dark:prose-invert max-w-none",
+							children: children ?? /* @__PURE__ */ jsx(Outlet, {})
+						}) }),
+						!isCollectionPage && /* @__PURE__ */ jsx(Feedback, {}),
+						!isCollectionPage && /* @__PURE__ */ jsx(Giscus, {}),
+						!isCollectionPage && /* @__PURE__ */ jsx("div", {
+							className: "mt-20",
+							children: /* @__PURE__ */ jsx(PageNav, {})
 						})
-					] }),
-					/* @__PURE__ */ jsx(ErrorBoundary, { children: /* @__PURE__ */ jsx("div", {
-						className: "prose prose-neutral dark:prose-invert max-w-none",
-						children
-					}) }),
-					!isCollectionPage && /* @__PURE__ */ jsx(Feedback, {}),
-					!isCollectionPage && /* @__PURE__ */ jsx(Giscus, {}),
-					/* @__PURE__ */ jsx(DocsLayout$1.Footer, { children: !isCollectionPage && /* @__PURE__ */ jsx(PageNav, {}) })
-				] }) }),
+					]
+				}) }),
 				/* @__PURE__ */ jsx("div", {
 					className: "overflow-y-auto sticky",
 					children: /* @__PURE__ */ jsx(OnThisPage, {
@@ -2702,4 +3306,46 @@ const reactToText = (node, resolvers) => {
 };
 
 //#endregion
-export { Banner, BoltdocsShell, Breadcrumbs, CollectionsContext, CopyMarkdown, CurrentPostProvider, DocsLayoutComponent as DocsLayout, ErrorBoundary, MdxPage, Navbar, NotFound, OnThisPage, PageNav, SearchDialog, Sidebar, Timeline, ViteReactSSG, cn, copyToClipboard, createRoutes, getStarsRepo, getTranslated, reactToText, useAnalytics, useBreadcrumbs, useCodeBlock, useConfig, useFeedback, useHeadings, useI18n, useLocalizedTo, useLocation, useMdxComponents, useMergedComponents, useNavbar, usePageNav, usePost, usePosts, useRecentPosts, useRoutes, useSearch, useSearchHighlight, useSidebar, useTabs, useTheme, useTrackEvent, useTrackPageView, useUI, useVersion };
+//#region src/client/components/mdx/use-code-block.ts
+/**
+* @deprecated Use the feature-scoped hooks instead: `useCopyButton`,
+* `useExpandable` and `useCodeBlockFeedback`. This composition keeps the
+* historical single-hook API and will be removed in a future major version.
+*/
+function useCodeBlock(props) {
+	const lang = props.lang || props["data-lang"] || "";
+	const isHighlighted = props["data-highlighted"] === "true" || typeof props.className === "string" && props.className.includes("shiki");
+	const rawHighlightedHtml = props.highlightedHtml || props["data-highlighted-html"];
+	const effectiveHighlightedHtml = typeof rawHighlightedHtml === "string" ? rawHighlightedHtml.replace(/<span class="line">\s*(?:<span[^>]*>\s*<\/span>)?\s*<\/span>\s*(<\/code>\s*<\/pre>)/g, "$1") : rawHighlightedHtml;
+	const effectiveTitle = props.title || props["data-title"];
+	const { copied, handleCopy } = useCopyButton();
+	const { isExpanded, setIsExpanded, isExpandable, shouldTruncate, preRef } = useExpandable({
+		children: props.children,
+		highlightedHtml: effectiveHighlightedHtml
+	});
+	const { rated, handleRate, enabled: showCodeBlockFeedback } = useCodeBlockFeedback({
+		plain: props.plain,
+		lang
+	});
+	const copyFromRef = () => handleCopy(preRef.current?.textContent ?? "");
+	const rateFromRef = (type) => handleRate(type, preRef.current?.textContent ?? "");
+	return {
+		copied,
+		isExpanded,
+		setIsExpanded,
+		isExpandable,
+		preRef,
+		handleCopy: copyFromRef,
+		shouldTruncate,
+		isHighlighted,
+		effectiveHighlightedHtml,
+		effectiveTitle,
+		lang,
+		showCodeBlockFeedback,
+		rated,
+		handleRate: rateFromRef
+	};
+}
+
+//#endregion
+export { Banner, BoltdocsShell, Breadcrumbs, CollectionsContext, CopyMarkdown, CurrentPostProvider, DocsLayoutComponent as DocsLayout, ErrorBoundary, LocationContext, LocationProvider, MatchesContext, MdxPage, Navbar, NavigateContext, NotFound, OnThisPage, Outlet, OutletContext, PageNav, PrefetchContext, RouteDataContext, RouteRenderer, SearchDialog, Sidebar, StructuredData, Timeline, ViteReactSSG, addBasename, addUrlBase, buildUrl, classifyUrlPath, cn, copyToClipboard, createArticleStructuredData, createBreadcrumbStructuredData, createRoutes, createStructuredData, createWebSiteStructuredData, defaultNavigate, defineStructuredData, getConfiguredLocales, getConfiguredVersions, getStarsRepo, getTranslated, getVersionPrefixSegments, getVersionSegments, hasBasename, hasUriScheme, hasUrlBase, isConfiguredLocale, isConfiguredVersion, matchRouteBranch, matchRouteBranchWithParams, normalizeBasename, normalizeUrlBase, normalizeUrlPath, parseUrlReference, reactToText, resolvePublicAssetUrl, resolveRouteBranch, resolveUrlReference, splitUrlReference, startViewTransition, stripBasename, stripSiteProtocol, stripUrlBase, useAnalytics, useBreadcrumbs, useCodeBlock, useCodeBlockFeedback, useConfig, useCopyButton, useExpandable, useFeedback, useHeadings, useI18n, useLoaderData, useLocalizedTo, useLocation, useMatches, useMdxComponents, useMergedComponents, useNavbar, useNavigate, usePageNav, usePost, usePosts, usePrefetch, useRecentPosts, useRouteData, useRoutes, useSearch, useSearchHighlight, useSidebar, useTabs, useTheme, useTrackEvent, useTrackPageView, useUI, useVersion, useViewTransition };