@astrojs/starlight 0.41.10 → 0.42.0

package/dist/utils/i18n.js

@@ -0,0 +1,141 @@
+import { AstroError } from "astro/errors";
+//#region src/utils/i18n.ts
+/**
+* A list of well-known right-to-left languages used as a fallback when determining the text
+* direction of a locale is not supported by the `Intl.Locale` API in the current environment.
+*
+* @see getLocaleDir()
+* @see https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags
+*/
+const wellKnownRTL = [
+	"ar",
+	"fa",
+	"he",
+	"prs",
+	"ps",
+	"syc",
+	"ug",
+	"ur"
+];
+/** Information about the built-in default locale used as a fallback when no locales are defined. */
+const BuiltInDefaultLocale = {
+	...getLocaleInfo("en"),
+	lang: "en"
+};
+/**
+* Processes the Astro and Starlight i18n configurations to generate/update them accordingly:
+*
+* 	- If no Astro and Starlight i18n configurations are provided, the built-in default locale is
+* used in Starlight and the generated Astro i18n configuration will match it.
+* 	- If only a Starlight i18n configuration is provided, an equivalent Astro i18n configuration is
+* generated.
+* 	- If only an Astro i18n configuration is provided, an equivalent Starlight i18n configuration is
+* used.
+* 	- If both an Astro and Starlight i18n configurations are provided, an error is thrown.
+*/
+function processI18nConfig(starlightConfig, astroI18nConfig) {
+	if (astroI18nConfig && !starlightConfig.isUsingBuiltInDefaultLocale) throw new AstroError("Cannot provide both an Astro `i18n` configuration and a Starlight `locales` configuration.", "Remove one of the two configurations.\nSee more at https://starlight.astro.build/guides/i18n/");
+	else if (astroI18nConfig) return {
+		astroI18nConfig,
+		starlightConfig: {
+			...starlightConfig,
+			...getStarlightI18nConfig(astroI18nConfig)
+		}
+	};
+	return {
+		astroI18nConfig: getAstroI18nConfig(starlightConfig),
+		starlightConfig
+	};
+}
+/** Generate an Astro i18n configuration based on a Starlight configuration. */
+function getAstroI18nConfig(config) {
+	return {
+		defaultLocale: (config.defaultLocale.locale === "root" ? config.defaultLocale.lang : config.defaultLocale.locale ?? config.defaultLocale.lang) ?? BuiltInDefaultLocale.lang,
+		locales: config.locales ? Object.entries(config.locales).map(([locale, localeConfig]) => {
+			return {
+				codes: [localeConfig?.lang ?? locale],
+				path: locale === "root" ? localeConfig?.lang ?? BuiltInDefaultLocale.lang : locale
+			};
+		}) : [config.defaultLocale.lang],
+		routing: {
+			prefixDefaultLocale: config.isMultilingual && config.locales?.root === void 0 || !config.isMultilingual && config.locales !== void 0,
+			redirectToDefaultLocale: false,
+			fallbackType: "redirect"
+		}
+	};
+}
+/** Generate a Starlight i18n configuration based on an Astro configuration. */
+function getStarlightI18nConfig(astroI18nConfig) {
+	if (astroI18nConfig.routing === "manual") throw new AstroError("Starlight is not compatible with the `manual` routing option in the Astro i18n configuration.");
+	const prefixDefaultLocale = astroI18nConfig.routing.prefixDefaultLocale;
+	const isMultilingual = astroI18nConfig.locales.length > 1;
+	const isMonolingualWithRootLocale = !isMultilingual && !prefixDefaultLocale;
+	const locales = isMonolingualWithRootLocale ? void 0 : Object.fromEntries(astroI18nConfig.locales.map((locale) => [isDefaultAstroLocale(astroI18nConfig, locale) && !prefixDefaultLocale ? "root" : isAstroLocaleExtendedConfig(locale) ? locale.path : locale, inferStarlightLocaleFromAstroLocale(locale)]));
+	const defaultAstroLocale = astroI18nConfig.locales.find((locale) => isDefaultAstroLocale(astroI18nConfig, locale));
+	if (!defaultAstroLocale) throw new AstroError("Astro default locale not found.", "This should never happen. Please open a new issue: https://github.com/withastro/starlight/issues/new?template=---01-bug-report.yml");
+	return {
+		isMultilingual,
+		locales,
+		defaultLocale: {
+			...inferStarlightLocaleFromAstroLocale(defaultAstroLocale),
+			locale: isMonolingualWithRootLocale || isMultilingual && !prefixDefaultLocale ? void 0 : isAstroLocaleExtendedConfig(defaultAstroLocale) ? defaultAstroLocale.codes[0] : defaultAstroLocale
+		}
+	};
+}
+/** Infer Starlight locale information based on a locale from an Astro i18n configuration. */
+function inferStarlightLocaleFromAstroLocale(astroLocale) {
+	const lang = isAstroLocaleExtendedConfig(astroLocale) ? astroLocale.codes[0] : astroLocale;
+	return {
+		...getLocaleInfo(lang),
+		lang
+	};
+}
+/** Check if the passed locale is the default locale in an Astro i18n configuration. */
+function isDefaultAstroLocale(astroI18nConfig, locale) {
+	return (isAstroLocaleExtendedConfig(locale) ? locale.path : locale) === astroI18nConfig.defaultLocale;
+}
+/**
+* Check if the passed Astro locale is using the object variant.
+* @see AstroLocaleExtendedConfig
+*/
+function isAstroLocaleExtendedConfig(locale) {
+	return typeof locale !== "string";
+}
+/** Returns the locale information such as a label and a direction based on a BCP-47 tag. */
+function getLocaleInfo(lang) {
+	try {
+		const locale = new Intl.Locale(lang);
+		const label = new Intl.DisplayNames(locale, { type: "language" }).of(lang);
+		if (!label || lang === label) throw new Error("Label not found.");
+		return {
+			label: label[0]?.toLocaleUpperCase(locale) + label.slice(1),
+			dir: getLocaleDir(locale)
+		};
+	} catch {
+		throw new AstroError(`Failed to get locale information for the '${lang}' locale.`, "Make sure to provide a valid BCP-47 tags (e.g. en, ar, or zh-CN).");
+	}
+}
+/**
+* Returns the direction of the passed locale.
+* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo
+*/
+function getLocaleDir(locale) {
+	if ("textInfo" in locale) return locale.textInfo.direction;
+	else if ("getTextInfo" in locale) return locale.getTextInfo().direction;
+	return wellKnownRTL.includes(locale.language) ? "rtl" : "ltr";
+}
+/**
+* Get the string for the passed language from a dictionary object.
+*
+* TODO: Make this clever. Currently a simple key look-up, but should use
+* BCP-47 mapping so that e.g. `en-US` returns `en` strings, and use the
+* site’s default locale as a last resort.
+*
+* @example
+* pickLang({ en: 'Hello', fr: 'Bonjour' }, 'en'); // => 'Hello'
+*/
+function pickLang(dictionary, lang) {
+	return dictionary[lang];
+}
+//#endregion
+export { BuiltInDefaultLocale, pickLang, processI18nConfig };

package/dist/utils/localizedUrl.d.ts

@@ -0,0 +1,8 @@
+import { AstroConfig } from "astro";
+//#region src/utils/localizedUrl.d.ts
+/**
+ * Get the equivalent of the passed URL for the passed locale.
+ */
+declare function localizedUrl(url: URL, locale: string | undefined, trailingSlash: AstroConfig['trailingSlash']): URL;
+//#endregion
+export { localizedUrl };

package/dist/utils/localizedUrl.js

@@ -0,0 +1,28 @@
+import { stripTrailingSlash } from "./path.js";
+import config from "virtual:starlight/user-config";
+//#region src/utils/localizedUrl.ts
+/**
+* Get the equivalent of the passed URL for the passed locale.
+*/
+function localizedUrl(url, locale, trailingSlash) {
+	url = new URL(url);
+	if (!config.locales) return url;
+	if (locale === "root") locale = "";
+	/** Base URL with trailing `/` stripped. */
+	const base = stripTrailingSlash(import.meta.env.BASE_URL);
+	const hasBase = url.pathname.startsWith(base);
+	if (hasBase) url.pathname = url.pathname.replace(base, "");
+	const [_leadingSlash, baseSegment] = url.pathname.split("/");
+	const isRootHtml = baseSegment?.endsWith(".html");
+	const baseSlug = isRootHtml ? baseSegment?.slice(0, -5) : baseSegment;
+	if (baseSlug && baseSlug in config.locales) if (locale) url.pathname = url.pathname.replace(baseSlug, locale);
+	else if (isRootHtml) url.pathname = "/index.html";
+	else url.pathname = url.pathname.replace("/" + baseSlug, "");
+	else if (locale) if (baseSegment === "index.html") url.pathname = "/" + locale + ".html";
+	else url.pathname = "/" + locale + url.pathname;
+	if (hasBase) url.pathname = base + url.pathname;
+	if (trailingSlash === "never") url.pathname = stripTrailingSlash(url.pathname);
+	return url;
+}
+//#endregion
+export { localizedUrl };

package/dist/utils/navigation.d.ts

@@ -0,0 +1,19 @@
+import { StarlightConfig } from "./user-config.js";
+import { PaginationLinks, SidebarEntry, SidebarLink } from "./routing/types.js";
+import { PrevNextLinkConfig } from "../schemas/prevNextLink.js";
+//#region src/utils/navigation.d.ts
+/** Get the sidebar for the current page using the global config. */
+declare function getSidebar(pathname: string, locale: string | undefined): SidebarEntry[];
+/** Get the sidebar for the current page using the specified sidebar config. */
+declare function getSidebarFromConfig(sidebarConfig: StarlightConfig['sidebar'], pathname: string, locale: string | undefined): SidebarEntry[];
+/** Generates a deterministic string based on the content of the passed sidebar. */
+declare function getSidebarHash(sidebar: SidebarEntry[]): string;
+/** Turn the nested tree structure of a sidebar into a flat list of all the links. */
+declare function flattenSidebar(sidebar: SidebarEntry[]): SidebarLink[];
+/** Get previous/next pages in the sidebar or the ones from the frontmatter if any. */
+declare function getPrevNextLinks(sidebar: SidebarEntry[], paginationEnabled: boolean, config: {
+  prev?: PrevNextLinkConfig;
+  next?: PrevNextLinkConfig;
+}): PaginationLinks;
+//#endregion
+export { flattenSidebar, getPrevNextLinks, getSidebar, getSidebarFromConfig, getSidebarHash };

package/dist/utils/navigation.js

@@ -0,0 +1,353 @@
+import { getCollectionPathFromRoot } from "./collection.js";
+import { ensureLeadingSlash, ensureTrailingSlash, stripExtension, stripLeadingAndTrailingSlashes } from "./path.js";
+import { BuiltInDefaultLocale, pickLang } from "./i18n.js";
+import { createPathFormatter } from "./createPathFormatter.js";
+import { formatPath } from "./format-path.js";
+import { hasProtocol } from "./url.js";
+import { localeToLang, localizedFilePath, slugToPathname } from "./slugs.js";
+import { getLocaleRoutes, getRouteById } from "./routing/index.js";
+import { AstroError } from "astro/errors";
+import config from "virtual:starlight/user-config";
+import project from "virtual:starlight/project-context";
+//#region src/utils/navigation.ts
+const DirKey = Symbol("DirKey");
+const SlugKey = Symbol("SlugKey");
+const rootAutogenerate = { directory: "" };
+const neverPathFormatter = createPathFormatter({ trailingSlash: "never" });
+const sidebarCollator = new Intl.Collator(localeToLang(void 0));
+const docsCollectionPathFromRoot = getCollectionPathFromRoot("docs", project);
+/** Create a new directory object. */
+function makeDir(slug) {
+	const dir = {};
+	Object.defineProperty(dir, DirKey, { enumerable: false });
+	Object.defineProperty(dir, SlugKey, {
+		value: slug,
+		enumerable: false
+	});
+	return dir;
+}
+/** Test if the passed object is a directory record.  */
+function isDir(data) {
+	return DirKey in data;
+}
+/** Convert an item in a user’s sidebar config to a sidebar entry. */
+function configItemToEntry(item, locale, routes) {
+	if ("link" in item) return linkFromSidebarLinkItem(item, locale);
+	else if ("autogenerate" in item) return entriesFromAutogenerateConfig(item, locale, routes);
+	else if ("slug" in item) return linkFromInternalSidebarLinkItem(item, locale);
+	else {
+		const label = pickLang(item.translations, localeToLang(locale)) || item.label;
+		return {
+			type: "group",
+			label,
+			entries: item.items.flatMap((i) => configItemToEntry(i, locale, routes)),
+			collapsed: item.collapsed,
+			badge: getSidebarBadge(item.badge, locale, label)
+		};
+	}
+}
+/** Autogenerate links and groups from a user’s sidebar config. */
+function entriesFromAutogenerateConfig(item, locale, routes) {
+	const { attrs, collapsed, directory } = item.autogenerate;
+	const localeDir = locale ? locale + "/" + directory : directory;
+	const autogenerate = { directory };
+	return sidebarFromDir(treeify(routes.filter((doc) => {
+		const filePathFromContentDir = getRoutePathRelativeToCollectionRoot(doc, locale);
+		return stripExtension(filePathFromContentDir) === localeDir || filePathFromContentDir.startsWith(localeDir + "/");
+	}), locale, localeDir), {
+		collapsed: collapsed ?? false,
+		attrs
+	}, autogenerate);
+}
+/** Create a link entry from a manual link item in user config. */
+function linkFromSidebarLinkItem(item, locale) {
+	let href = item.link;
+	if (!hasProtocol(href)) {
+		href = ensureLeadingSlash(href);
+		if (locale) href = "/" + locale + href;
+	}
+	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
+	return makeSidebarLink({
+		href,
+		label,
+		badge: getSidebarBadge(item.badge, locale, label),
+		attrs: item.attrs
+	});
+}
+/** Create a link entry from an automatic internal link item in user config. */
+function linkFromInternalSidebarLinkItem(item, locale) {
+	const slug = item.slug === "index" ? "" : item.slug;
+	const localizedSlug = locale ? slug ? locale + "/" + slug : locale : slug;
+	const route = getRouteById(localizedSlug);
+	if (!route) if (item.slug.at(0) === "/" || item.slug.at(-1) === "/") throw new AstroError(`The slug \`"${item.slug}"\` specified in the Starlight sidebar config must not start or end with a slash.`, `Please try updating \`"${item.slug}"\` to \`"${stripLeadingAndTrailingSlashes(item.slug)}"\`.`);
+	else throw new AstroError(`The slug \`"${item.slug}"\` specified in the Starlight sidebar config does not exist.`, "Update the Starlight config to reference a valid entry slug in the docs content collection.\nLearn more about Astro content collection slugs at https://docs.astro.build/en/reference/modules/astro-content/#getentry");
+	const frontmatter = route.entry.data;
+	const label = pickLang(item.translations, localeToLang(locale)) || item.label || frontmatter.sidebar?.label || frontmatter.title;
+	const badge = item.badge ?? frontmatter.sidebar?.badge;
+	const attrs = {
+		...frontmatter.sidebar?.attrs,
+		...item.attrs
+	};
+	return makeSidebarLink({
+		href: slugToPathname(route.id),
+		label,
+		badge: getSidebarBadge(badge, locale, label),
+		attrs
+	});
+}
+function makeSidebarLink({ attrs, badge, href, label, autogenerate }) {
+	if (!hasProtocol(href)) href = formatPath(href);
+	return makeLink({
+		label,
+		href,
+		badge,
+		attrs,
+		autogenerate
+	});
+}
+/** Create a link entry */
+function makeLink({ attrs = {}, badge, autogenerate, ...opts }) {
+	return {
+		type: "link",
+		...opts,
+		badge,
+		isCurrent: false,
+		attrs,
+		...autogenerate ? { autogenerate } : {}
+	};
+}
+/** Get the segments leading to a page. */
+function getBreadcrumbs(path, baseDir) {
+	const pathWithoutExt = stripExtension(path);
+	if (pathWithoutExt === baseDir) return [];
+	baseDir = ensureTrailingSlash(baseDir);
+	return (pathWithoutExt.startsWith(baseDir) ? pathWithoutExt.replace(baseDir, "") : pathWithoutExt).split("/");
+}
+/** Return the path of a route relative to the root of the collection. */
+function getRoutePathRelativeToCollectionRoot(route, locale) {
+	return localizedFilePath(route.entry.filePath.replace(`${docsCollectionPathFromRoot}/`, ""), locale);
+}
+/** Turn a flat array of routes into a tree structure. */
+function treeify(routes, locale, baseDir) {
+	const treeRoot = makeDir(baseDir);
+	routes.filter((doc) => !doc.entry.data.sidebar.hidden).map((doc) => [getRoutePathRelativeToCollectionRoot(doc, locale), doc]).sort(([a], [b]) => b.split("/").length - a.split("/").length).forEach(([filePathFromContentDir, doc]) => {
+		const parts = getBreadcrumbs(filePathFromContentDir, baseDir);
+		let currentNode = treeRoot;
+		parts.forEach((part, index) => {
+			const isLeaf = index === parts.length - 1;
+			if (isLeaf && Object.hasOwn(currentNode, part)) {
+				currentNode = currentNode[part];
+				part = "index";
+			}
+			if (!isLeaf) {
+				const path = currentNode[SlugKey];
+				currentNode[part] ||= makeDir(stripLeadingAndTrailingSlashes(path + "/" + part));
+				currentNode = currentNode[part];
+			} else currentNode[part] = doc;
+		});
+	});
+	return treeRoot;
+}
+/** Create a link entry for a given content collection entry. */
+function linkFromRoute(route, attrs, autogenerate) {
+	return makeSidebarLink({
+		href: slugToPathname(route.id),
+		label: route.entry.data.sidebar.label || route.entry.data.title,
+		badge: route.entry.data.sidebar.badge,
+		attrs: {
+			...attrs,
+			...route.entry.data.sidebar.attrs
+		},
+		autogenerate
+	});
+}
+/**
+* Get the sort weight for a given route or directory. Lower numbers rank higher.
+* Directories have the weight of the lowest weighted route they contain.
+*/
+function getOrder(routeOrDir) {
+	const cachedOrder = orderByEntry.get(routeOrDir);
+	if (cachedOrder !== void 0) return cachedOrder;
+	const order = isDir(routeOrDir) ? Math.min(...Object.values(routeOrDir).flatMap(getOrder)) : routeOrDir.entry.data.sidebar.order ?? Number.MAX_VALUE;
+	orderByEntry.set(routeOrDir, order);
+	return order;
+}
+const orderByEntry = /* @__PURE__ */ new WeakMap();
+/** Sort a directory’s entries by user-specified order or alphabetically if no order specified. */
+function sortDirEntries(dir) {
+	return dir.sort(([_keyA, a], [_keyB, b]) => {
+		const [aOrder, bOrder] = [getOrder(a), getOrder(b)];
+		if (aOrder !== bOrder) return aOrder < bOrder ? -1 : 1;
+		return sidebarCollator.compare(isDir(a) ? a[SlugKey] : a.id, isDir(b) ? b[SlugKey] : b.id);
+	});
+}
+/** Create a group entry for a given content collection directory. */
+function groupFromDir(dir, context) {
+	const { fullPath, dirName, collapsed, autogenerate } = context;
+	return {
+		type: "group",
+		label: dirName,
+		entries: sortDirEntries(Object.entries(dir)).map(([key, dirOrRoute]) => dirToItem(dirOrRoute, {
+			...context,
+			fullPath: `${fullPath}/${key}`,
+			dirName: key
+		})),
+		collapsed,
+		badge: void 0,
+		autogenerate
+	};
+}
+/** Create a sidebar entry for a directory or content entry. */
+function dirToItem(dirOrRoute, context) {
+	const { attrs, autogenerate } = context;
+	return isDir(dirOrRoute) ? groupFromDir(dirOrRoute, context) : linkFromRoute(dirOrRoute, attrs, autogenerate);
+}
+/** Create a sidebar entry for a given content directory. */
+function sidebarFromDir(tree, options, autogenerate = rootAutogenerate) {
+	return sortDirEntries(Object.entries(tree)).map(([key, dirOrRoute]) => dirToItem(dirOrRoute, {
+		...options,
+		fullPath: key,
+		dirName: key,
+		autogenerate
+	}));
+}
+/**
+* Intermediate sidebar represents sidebar entries generated from the user config for a specific
+* locale. These representations are cached per locale to avoid regenerating them for each page.
+* When generating the final sidebar for a page, the current page entry in the sidebar is marked
+* with `isCurrent` and cached. Subsequent runs then reset the previous current entry before marking
+* the new current page.
+*
+* Sidebars, like all route data, are deep cloned before the data is passed to users for mutation,
+* so optimising with a single mutable object per locale is safe.
+*
+* @see getSidebarFromIntermediateSidebar
+*/
+const intermediateSidebars = /* @__PURE__ */ new Map();
+const lastCurrentEntryByLocale = /* @__PURE__ */ new Map();
+/** Get the sidebar for the current page using the global config. */
+function getSidebar(pathname, locale) {
+	let intermediateSidebar = intermediateSidebars.get(locale);
+	if (!intermediateSidebar) {
+		intermediateSidebar = getIntermediateSidebarFromConfig(config.sidebar, locale);
+		intermediateSidebars.set(locale, intermediateSidebar);
+	}
+	setIntermediateSidebarCurrentEntry(intermediateSidebar, pathname, locale);
+	return intermediateSidebar;
+}
+/** Get the sidebar for the current page using the specified sidebar config. */
+function getSidebarFromConfig(sidebarConfig, pathname, locale) {
+	const sidebar = getIntermediateSidebarFromConfig(sidebarConfig, locale);
+	const currentEntry = getSidebarCurrentEntry(sidebar, pathname);
+	if (currentEntry) currentEntry.isCurrent = true;
+	return sidebar;
+}
+/** Get the intermediate sidebar for a locale using the specified sidebar config. */
+function getIntermediateSidebarFromConfig(sidebarConfig, locale) {
+	const routes = getLocaleRoutes(locale);
+	if (sidebarConfig) return sidebarConfig.flatMap((group) => configItemToEntry(group, locale, routes));
+	else return sidebarFromDir(treeify(routes, locale, locale || ""), {
+		collapsed: false,
+		attrs: void 0
+	});
+}
+/** Marks the current page in an intermediate sidebar. */
+function setIntermediateSidebarCurrentEntry(intermediateSidebar, pathname, locale) {
+	const lastCurrentEntry = lastCurrentEntryByLocale.get(locale);
+	if (lastCurrentEntry) lastCurrentEntry.isCurrent = false;
+	const entry = getSidebarCurrentEntry(intermediateSidebar, pathname);
+	if (entry) {
+		entry.isCurrent = true;
+		lastCurrentEntryByLocale.set(locale, entry);
+	}
+}
+/** Finds the current page in a sidebar. */
+function getSidebarCurrentEntry(sidebar, pathname) {
+	let entriesByPath = sidebarEntriesByPath.get(sidebar);
+	if (!entriesByPath) {
+		entriesByPath = /* @__PURE__ */ new Map();
+		for (const entry of flattenSidebar(sidebar)) {
+			const path = neverPathFormatter(encodeURI(entry.href));
+			if (!entriesByPath.has(path)) entriesByPath.set(path, entry);
+		}
+		sidebarEntriesByPath.set(sidebar, entriesByPath);
+	}
+	return entriesByPath.get(neverPathFormatter(pathname)) ?? null;
+}
+const sidebarEntriesByPath = /* @__PURE__ */ new WeakMap();
+/** Generates a deterministic string based on the content of the passed sidebar. */
+function getSidebarHash(sidebar) {
+	let hash = 0;
+	const sidebarIdentity = recursivelyBuildSidebarIdentity(sidebar);
+	for (let i = 0; i < sidebarIdentity.length; i++) {
+		const char = sidebarIdentity.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+	}
+	return (hash >>> 0).toString(36).padStart(7, "0");
+}
+/** Recurses through a sidebar tree to generate a string concatenating labels and link hrefs. */
+function recursivelyBuildSidebarIdentity(sidebar) {
+	return sidebar.flatMap((entry) => entry.type === "group" ? entry.label + recursivelyBuildSidebarIdentity(entry.entries) : entry.label + entry.href).join("");
+}
+/** Turn the nested tree structure of a sidebar into a flat list of all the links. */
+function flattenSidebar(sidebar) {
+	const cachedSidebar = flattenedSidebars.get(sidebar);
+	if (cachedSidebar) return cachedSidebar;
+	const flattenedSidebar = sidebar.flatMap((entry) => entry.type === "group" ? flattenSidebar(entry.entries) : entry);
+	flattenedSidebars.set(sidebar, flattenedSidebar);
+	return flattenedSidebar;
+}
+const flattenedSidebars = /* @__PURE__ */ new WeakMap();
+/** Get previous/next pages in the sidebar or the ones from the frontmatter if any. */
+function getPrevNextLinks(sidebar, paginationEnabled, config) {
+	const entries = flattenSidebar(sidebar);
+	const currentIndex = entries.findIndex((entry) => entry.isCurrent);
+	return {
+		prev: applyPrevNextLinkConfig(entries[currentIndex - 1], paginationEnabled, config.prev),
+		next: applyPrevNextLinkConfig(currentIndex > -1 ? entries[currentIndex + 1] : void 0, paginationEnabled, config.next)
+	};
+}
+/** Apply a prev/next link config to a navigation link. */
+function applyPrevNextLinkConfig(link, paginationEnabled, config) {
+	if (config === false) return void 0;
+	else if (config === true) return link;
+	else if (typeof config === "string" && link) return {
+		...link,
+		label: config
+	};
+	else if (typeof config === "object") {
+		if (link) return {
+			...link,
+			label: config.label ?? link.label,
+			href: config.link ?? link.href,
+			attrs: {}
+		};
+		else if (config.link && config.label) return makeLink({
+			href: config.link,
+			label: config.label
+		});
+	}
+	return paginationEnabled ? link : void 0;
+}
+/** Get a sidebar badge for a given item. */
+function getSidebarBadge(config, locale, itemLabel) {
+	if (!config) return;
+	if (typeof config === "string") return {
+		variant: "default",
+		text: config
+	};
+	return {
+		...config,
+		text: getSidebarBadgeText(config.text, locale, itemLabel)
+	};
+}
+/** Get the badge text for a sidebar item. */
+function getSidebarBadgeText(text, locale, itemLabel) {
+	if (typeof text === "string") return text;
+	const defaultLang = config.defaultLocale?.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang;
+	const defaultText = text[defaultLang];
+	if (!defaultText) throw new AstroError(`The badge text for "${itemLabel}" must have a key for the default language "${defaultLang}".`, "Update the Starlight config to include a badge text for the default language.\nLearn more about sidebar badges internationalization at https://starlight.astro.build/guides/sidebar/#internationalization-with-badges");
+	return pickLang(text, localeToLang(locale)) || defaultText;
+}
+//#endregion
+export { flattenSidebar, getPrevNextLinks, getSidebar, getSidebarFromConfig, getSidebarHash };

package/dist/utils/path.d.ts

@@ -0,0 +1,21 @@
+//#region src/utils/path.d.ts
+/** Ensure the passed path starts with a leading slash. */
+declare function ensureLeadingSlash(href: string): string;
+/** Ensure the passed path ends with a trailing slash. */
+declare function ensureTrailingSlash(href: string): string;
+/** Ensure the passed path starts and ends with slashes. */
+declare function ensureLeadingAndTrailingSlashes(href: string): string;
+/** Ensure the passed path does not start with a leading slash. */
+declare function stripLeadingSlash(href: string): string;
+/** Ensure the passed path does not end with a trailing slash. */
+declare function stripTrailingSlash(href: string): string;
+/** Ensure the passed path does not start and end with slashes. */
+declare function stripLeadingAndTrailingSlashes(href: string): string;
+/** Remove the extension from a path. */
+declare function stripHtmlExtension(path: string): string;
+/** Add '.html' extension to a path. */
+declare function ensureHtmlExtension(path: string): string;
+/** Remove the extension from a path. */
+declare function stripExtension(path: string): string;
+//#endregion
+export { ensureHtmlExtension, ensureLeadingAndTrailingSlashes, ensureLeadingSlash, ensureTrailingSlash, stripExtension, stripHtmlExtension, stripLeadingAndTrailingSlashes, stripLeadingSlash, stripTrailingSlash };

package/dist/utils/path.js

@@ -0,0 +1,51 @@
+//#region src/utils/path.ts
+/** Ensure the passed path starts with a leading slash. */
+function ensureLeadingSlash(href) {
+	if (href[0] !== "/") href = "/" + href;
+	return href;
+}
+/** Ensure the passed path ends with a trailing slash. */
+function ensureTrailingSlash(href) {
+	if (href[href.length - 1] !== "/") href += "/";
+	return href;
+}
+/** Ensure the passed path starts and ends with slashes. */
+function ensureLeadingAndTrailingSlashes(href) {
+	href = ensureLeadingSlash(href);
+	href = ensureTrailingSlash(href);
+	return href;
+}
+/** Ensure the passed path does not start with a leading slash. */
+function stripLeadingSlash(href) {
+	if (href[0] === "/") href = href.slice(1);
+	return href;
+}
+/** Ensure the passed path does not end with a trailing slash. */
+function stripTrailingSlash(href) {
+	if (href[href.length - 1] === "/") href = href.slice(0, -1);
+	return href;
+}
+/** Ensure the passed path does not start and end with slashes. */
+function stripLeadingAndTrailingSlashes(href) {
+	href = stripLeadingSlash(href);
+	href = stripTrailingSlash(href);
+	return href;
+}
+/** Remove the extension from a path. */
+function stripHtmlExtension(path) {
+	const pathWithoutTrailingSlash = stripTrailingSlash(path);
+	return pathWithoutTrailingSlash.endsWith(".html") ? pathWithoutTrailingSlash.slice(0, -5) : path;
+}
+/** Add '.html' extension to a path. */
+function ensureHtmlExtension(path) {
+	path = stripLeadingAndTrailingSlashes(path);
+	if (!path.endsWith(".html")) path = path ? path + ".html" : "/index.html";
+	return ensureLeadingSlash(path);
+}
+/** Remove the extension from a path. */
+function stripExtension(path) {
+	const periodIndex = path.lastIndexOf(".");
+	return path.slice(0, periodIndex > -1 ? periodIndex : void 0);
+}
+//#endregion
+export { ensureHtmlExtension, ensureLeadingAndTrailingSlashes, ensureLeadingSlash, ensureTrailingSlash, stripExtension, stripHtmlExtension, stripLeadingAndTrailingSlashes, stripLeadingSlash, stripTrailingSlash };