@astrojs/starlight 0.37.7 → 0.38.1

package/schemas/sidebar.ts

@@ -8,12 +8,13 @@ const SidebarBaseSchema = z.object({
 	/** The visible label for this item in the sidebar. */
 	label: z.string(),
 	/** Translations of the `label` for each supported language. */
-	translations: z.record(z.string()).default({}),
+	translations: z.record(z.string(), z.string()).default({}),
 	/** Adds a badge to the item */
 	badge: I18nBadgeConfigSchema(),
 });
 
-const SidebarGroupSchema = SidebarBaseSchema.extend({
+const SidebarGroupSchema = z.object({
+	...SidebarBaseSchema.shape,
 	/**
 	 * Explicitly prevent custom attributes on groups as the final type for supported sidebar item
 	 * is a non-discriminated union where TypeScript will not perform excess property checks.
@@ -30,21 +31,27 @@ const SidebarGroupSchema = SidebarBaseSchema.extend({
 // `Record<string, string | number | boolean | undefined>` but typed as `HTMLAttributes<'a'>`
 // for user convenience.
 const linkHTMLAttributesSchema = z.record(
+	z.string(),
 	z.union([z.string(), z.number(), z.boolean(), z.undefined(), z.null()])
-) as z.Schema<Omit<HTMLAttributes<'a'>, keyof AstroBuiltinAttributes | 'children'>>;
-export type LinkHTMLAttributes = z.infer<typeof linkHTMLAttributesSchema>;
+) as z.ZodType<LinkHTMLAttributes, LinkHTMLAttributes>;
+export type LinkHTMLAttributes = Omit<
+	HTMLAttributes<'a'>,
+	keyof AstroBuiltinAttributes | 'children'
+>;
 
 export const SidebarLinkItemHTMLAttributesSchema = () => linkHTMLAttributesSchema.default({});
 
-const SidebarLinkItemSchema = SidebarBaseSchema.extend({
+const SidebarLinkItemSchema = z.strictObject({
+	...SidebarBaseSchema.shape,
 	/** The link to this item’s content. Can be a relative link to local files or the full URL of an external page. */
 	link: z.string(),
 	/** HTML attributes to add to the link item. */
 	attrs: SidebarLinkItemHTMLAttributesSchema(),
-}).strict();
+});
 export type SidebarLinkItem = z.infer<typeof SidebarLinkItemSchema>;
 
-const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
+const AutoSidebarGroupSchema = z.strictObject({
+	...SidebarGroupSchema.shape,
 	/** Enable autogenerating a sidebar category from a specific docs directory. */
 	autogenerate: z.object({
 		/** The directory to generate sidebar items for. */
@@ -60,7 +67,7 @@ const AutoSidebarGroupSchema = SidebarGroupSchema.extend({
 		/** How many directories deep to include from this directory in the sidebar. Default: `Infinity`. */
 		// depth: z.number().optional(),
 	}),
-}).strict();
+});
 export type AutoSidebarGroup = z.infer<typeof AutoSidebarGroupSchema>;
 
 type ManualSidebarGroupInput = z.input<typeof SidebarGroupSchema> & {
@@ -85,26 +92,25 @@ type ManualSidebarGroupOutput = z.output<typeof SidebarGroupSchema> & {
 	>;
 };
 
-const ManualSidebarGroupSchema: z.ZodType<
-	ManualSidebarGroupOutput,
-	z.ZodTypeDef,
-	ManualSidebarGroupInput
-> = SidebarGroupSchema.extend({
-	/** Array of links and subcategories to display in this category. */
-	items: z.lazy(() =>
-		z
-			.union([
-				SidebarLinkItemSchema,
-				ManualSidebarGroupSchema,
-				AutoSidebarGroupSchema,
-				InternalSidebarLinkItemSchema,
-				InternalSidebarLinkItemShorthandSchema,
-			])
-			.array()
-	),
-}).strict();
+const ManualSidebarGroupSchema: z.ZodType<ManualSidebarGroupOutput, ManualSidebarGroupInput> =
+	z.strictObject({
+		...SidebarGroupSchema.shape,
+		/** Array of links and subcategories to display in this category. */
+		items: z.lazy(() =>
+			z
+				.union([
+					SidebarLinkItemSchema,
+					ManualSidebarGroupSchema,
+					AutoSidebarGroupSchema,
+					InternalSidebarLinkItemSchema,
+					InternalSidebarLinkItemShorthandSchema,
+				])
+				.array()
+		),
+	});
 
-const InternalSidebarLinkItemSchema = SidebarBaseSchema.partial({ label: true }).extend({
+const InternalSidebarLinkItemSchema = z.object({
+	...SidebarBaseSchema.partial({ label: true }).shape,
 	/** The link to this item’s content. Must be a slug of a Content Collection entry. */
 	slug: z.string(),
 	/** HTML attributes to add to the link item. */

package/schemas/site-title.ts

@@ -1,9 +1,6 @@
 import { z } from 'astro/zod';
 
-export const TitleConfigSchema = () =>
-	z
-		.union([z.string(), z.record(z.string())])
-		.describe('Title for your website. Will be used in metadata and as browser tab title.');
+export const TitleConfigSchema = () => z.union([z.string(), z.record(z.string(), z.string())]);
 
 // transform the title for runtime use
 export const TitleTransformConfigSchema = (defaultLang: string) =>
@@ -12,9 +9,10 @@ export const TitleTransformConfigSchema = (defaultLang: string) =>
 			return { [defaultLang]: title };
 		}
 		if (!title[defaultLang] && title[defaultLang] !== '') {
-			ctx.addIssue({
-				code: z.ZodIssueCode.custom,
+			ctx.issues.push({
+				code: 'custom',
 				message: `Title must have a key for the default language "${defaultLang}"`,
+				input: title,
 			});
 			return z.NEVER;
 		}

package/schemas/social.ts

@@ -11,11 +11,12 @@ export const SocialLinksSchema = () =>
 	// TODO: remove once most people have updated to v0.33 or higher (e.g. when releasing Starlight v1)
 	z.preprocess((value, ctx) => {
 		if (value && typeof value === 'object' && !Array.isArray(value)) {
-			ctx.addIssue({
-				code: z.ZodIssueCode.custom,
+			ctx.issues.push({
+				code: 'custom',
 				message:
 					'Starlight v0.33.0 changed the `social` configuration syntax. Please specify an array of link items instead of an object.\n' +
 					'See the Starlight changelog for details: https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md#0330\n',
+				input: value,
 			});
 		}
 		return value;

package/schemas/tableOfContents.ts

@@ -2,18 +2,20 @@ import { z } from 'astro/zod';
 
 const defaults = { minHeadingLevel: 2, maxHeadingLevel: 3 };
 
-export const TableOfContentsSchema = () =>
-	z
-		.union([
-			z.object({
-				/** The level to start including headings at in the table of contents. Default: 2. */
-				minHeadingLevel: z.number().int().min(1).max(6).optional().default(2),
-				/** The level to stop including headings at in the table of contents. Default: 3. */
-				maxHeadingLevel: z.number().int().min(1).max(6).optional().default(3),
-			}),
-			z.boolean().transform((enabled) => (enabled ? defaults : false)),
-		])
-		.default(defaults)
-		.refine((toc) => (toc ? toc.minHeadingLevel <= toc.maxHeadingLevel : true), {
-			message: 'minHeadingLevel must be less than or equal to maxHeadingLevel',
-		});
+const TableOfContentsBaseSchema = z
+	.union([
+		z.object({
+			/** The level to start including headings at in the table of contents. Default: 2. */
+			minHeadingLevel: z.int().min(1).max(6).optional().default(2),
+			/** The level to stop including headings at in the table of contents. Default: 3. */
+			maxHeadingLevel: z.int().min(1).max(6).optional().default(3),
+		}),
+		z.boolean().transform((enabled) => (enabled ? defaults : false)),
+	])
+	.refine((toc) => (toc ? toc.minHeadingLevel <= toc.maxHeadingLevel : true), {
+		error: 'minHeadingLevel must be less than or equal to maxHeadingLevel',
+	});
+
+export const UserConfigTableOfContentsSchema = () => TableOfContentsBaseSchema.default(defaults);
+
+export const FrontmatterTableOfContentsSchema = () => TableOfContentsBaseSchema.optional();

package/style/props.css

@@ -84,8 +84,13 @@
 		--sl-line-height: 1.75;
 		--sl-line-height-headings: 1.2;
 
-		--sl-font-system: ui-sans-serif, system-ui, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
-			'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
+		/*
+			Although technically superseded by the `system-ui` font-family, we use `-apple-system` and
+			`BlinkMacSystemFont` because `system-ui` causes issues on Windows computers in some languages.
+			See: https://github.com/withastro/starlight/issues/3721
+		*/
+		--sl-font-system: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue',
+			'Noto Sans', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
 			'Noto Color Emoji';
 		--sl-font-system-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
 			'Courier New', monospace;

package/types.ts

@@ -4,4 +4,4 @@ export type {
 	StarlightUserConfigWithPlugins as StarlightUserConfig,
 	HookParameters,
 } from './utils/plugins';
-export type { StarlightIcon } from './components/Icons';
+export type { StarlightIcon } from './components-internals/Icons';

package/user-components/Aside.astro

@@ -1,7 +1,7 @@
 ---
 import { AstroError } from 'astro/errors';
 import Icon from './Icon.astro';
-import { Icons, type StarlightIcon } from '../components/Icons';
+import { Icons, type StarlightIcon } from '../components-internals/Icons';
 import { throwInvalidAsideIconError } from '../integrations/asides-error';
 
 const asideVariants = ['note', 'tip', 'caution', 'danger'] as const;

package/user-components/Card.astro

@@ -1,6 +1,6 @@
 ---
 import Icon from './Icon.astro';
-import type { StarlightIcon } from '../components/Icons';
+import type { StarlightIcon } from '../components-internals/Icons';
 
 interface Props {
 	icon?: StarlightIcon;

package/user-components/Icon.astro

@@ -1,5 +1,5 @@
 ---
-import { Icons, type StarlightIcon } from '../components/Icons';
+import { Icons, type StarlightIcon } from '../components-internals/Icons';
 
 interface Props {
 	name: StarlightIcon;

package/user-components/LinkButton.astro

@@ -1,6 +1,6 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
-import type { StarlightIcon } from '../components/Icons';
+import type { StarlightIcon } from '../components-internals/Icons';
 import Icon from './Icon.astro';
 
 interface Props extends Omit<HTMLAttributes<'a'>, 'href'> {

package/user-components/TabItem.astro

@@ -1,6 +1,6 @@
 ---
 import { TabItemTagname } from './rehype-tabs';
-import type { StarlightIcon } from '../components/Icons';
+import type { StarlightIcon } from '../components-internals/Icons';
 
 interface Props {
 	icon?: StarlightIcon;

package/user-components/rehype-file-tree.ts

@@ -6,7 +6,7 @@ import { fromHtml } from 'hast-util-from-html';
 import { toString } from 'hast-util-to-string';
 import { rehype } from 'rehype';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import { Icons, type StarlightIcon } from '../components/Icons';
+import { Icons, type StarlightIcon } from '../components-internals/Icons';
 import { definitions } from './file-tree-icons';
 
 declare module 'vfile' {

package/user-components/rehype-tabs.ts

@@ -2,7 +2,7 @@ import type { Element } from 'hast';
 import { select } from 'hast-util-select';
 import { rehype } from 'rehype';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import type { StarlightIcon } from '../components/Icons';
+import type { StarlightIcon } from '../components-internals/Icons';
 
 interface Panel {
 	panelId: string;

package/utils/createTranslationSystem.ts

@@ -107,7 +107,7 @@ function localeToLang(
 type BuiltInStrings = (typeof builtinTranslations)['en'];
 
 /** Build an i18next resources dictionary by layering preferred translation sources. */
-function buildResources<T extends Record<string, string | undefined>>(
+function buildResources<T extends i18nSchemaOutput>(
 	...dictionaries: (T | BuiltInStrings | undefined)[]
 ): { [I18nextNamespace]: BuiltInStrings & T } {
 	const dictionary: Partial<BuiltInStrings> = {};

package/utils/error-map.ts

@@ -4,12 +4,16 @@
  */
 
 import { AstroError } from 'astro/errors';
-import type { z } from 'astro:content';
+import { z, locales } from 'astro/zod';
 
-type TypeOrLiteralErrByPathEntry = {
-	code: 'invalid_type' | 'invalid_literal';
+// The default Zod error map that we use to retrieve default error messages.
+const zodErrorMap = locales.en().localeError;
+
+type TypeErrByPathEntry = {
+	code: 'invalid_type';
 	received: unknown;
 	expected: unknown[];
+	message: string | undefined;
 };
 
 /**
@@ -20,12 +24,15 @@ type TypeOrLiteralErrByPathEntry = {
  * @param message Error message preamble to use if the input fails to parse.
  * @returns Validated data parsed by Zod.
  */
-export function parseWithFriendlyErrors<T extends z.Schema>(
+export function parseWithFriendlyErrors<T extends z.ZodType>(
 	schema: T,
 	input: z.input<T>,
 	message: string
 ): z.output<T> {
-	return processParsedData<T>(schema.safeParse(input, { errorMap }), message);
+	return processParsedData<T>(
+		schema.safeParse(input, { error: errorMap, reportInput: true }),
+		message
+	);
 }
 
 /**
@@ -37,16 +44,19 @@ export function parseWithFriendlyErrors<T extends z.Schema>(
  * @param message Error message preamble to use if the input fails to parse.
  * @returns Validated data parsed by Zod.
  */
-export async function parseAsyncWithFriendlyErrors<T extends z.Schema>(
+export async function parseAsyncWithFriendlyErrors<T extends z.ZodType>(
 	schema: T,
 	input: z.input<T>,
 	message: string
 ): Promise<z.output<T>> {
-	return processParsedData<T>(await schema.safeParseAsync(input, { errorMap }), message);
+	return processParsedData<T>(
+		await schema.safeParseAsync(input, { error: errorMap, reportInput: true }),
+		message
+	);
 }
 
-function processParsedData<T extends z.Schema>(
-	parsedData: z.SafeParseReturnType<T, T>,
+function processParsedData<T extends z.ZodType>(
+	parsedData: z.ZodSafeParseResult<z.output<T>>,
 	message: string
 ) {
 	if (!parsedData.success) {
@@ -55,25 +65,27 @@ function processParsedData<T extends z.Schema>(
 	return parsedData.data;
 }
 
-const errorMap: z.ZodErrorMap = (baseError, ctx) => {
-	const baseErrorPath = flattenErrorPath(baseError.path);
-	if (baseError.code === 'invalid_union') {
+const errorMap: z.core.$ZodErrorMap = (issue) => {
+	const baseErrorPath = flattenErrorPath(issue.path ?? []);
+	if (issue.code === 'invalid_union') {
 		// Optimization: Combine type and literal errors for keys that are common across ALL union types
 		// Ex. a union between `{ key: z.literal('tutorial') }` and `{ key: z.literal('blog') }` will
 		// raise a single error when `key` does not match:
 		// > Did not match union.
 		// > key: Expected `'tutorial' | 'blog'`, received 'foo'
-		const typeOrLiteralErrByPath: Map<string, TypeOrLiteralErrByPathEntry> = new Map();
-		for (const unionError of baseError.unionErrors.map((e) => e.errors).flat()) {
-			if (unionError.code === 'invalid_type' || unionError.code === 'invalid_literal') {
-				const flattenedErrorPath = flattenErrorPath(unionError.path);
+		const unionErrors = issue.errors.flat();
+		const typeOrLiteralErrByPath: Map<string, TypeErrByPathEntry> = new Map();
+		for (const unionError of unionErrors) {
+			if (unionError.code === 'invalid_type') {
+				const flattenedErrorPath = flattenErrorPath([baseErrorPath, ...unionError.path]);
 				if (typeOrLiteralErrByPath.has(flattenedErrorPath)) {
 					typeOrLiteralErrByPath.get(flattenedErrorPath)!.expected.push(unionError.expected);
 				} else {
 					typeOrLiteralErrByPath.set(flattenedErrorPath, {
 						code: unionError.code,
-						received: unionError.received,
+						received: parsedType(issue.input),
 						expected: [unionError.expected],
+						message: unionError.message,
 					});
 				}
 			}
@@ -82,83 +94,84 @@ const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 		const details: string[] = [...typeOrLiteralErrByPath.entries()]
 			// If type or literal error isn't common to ALL union types,
 			// filter it out. Can lead to confusing noise.
-			.filter(([, error]) => error.expected.length === baseError.unionErrors.length)
+			.filter(([, error]) => error.expected.length === unionErrors.length)
 			.map(([key, error]) =>
 				key === baseErrorPath
 					? // Avoid printing the key again if it's a base error
-						`> ${getTypeOrLiteralMsg(error)}`
-					: `> ${prefix(key, getTypeOrLiteralMsg(error))}`
+						`> ${getTypeErrMsg(error)}`
+					: `> ${prefix(key, getTypeErrMsg(error))}`
 			);
 
 		if (details.length === 0) {
 			const expectedShapes: string[] = [];
-			for (const unionError of baseError.unionErrors) {
+			for (const unionError of issue.errors) {
 				const expectedShape: string[] = [];
-				for (const issue of unionError.issues) {
+				for (const issue of unionError) {
 					// If the issue is a nested union error, show the associated error message instead of the
 					// base error message.
 					if (issue.code === 'invalid_union') {
-						return errorMap(issue, ctx);
+						return errorMap({ ...issue, input: issue.input, path: [baseErrorPath, ...issue.path] });
 					}
 					const relativePath = flattenErrorPath(issue.path)
 						.replace(baseErrorPath, '')
 						.replace(leadingPeriod, '');
-					if ('expected' in issue && typeof issue.expected === 'string') {
+					if (issue.code === 'invalid_type') {
 						expectedShape.push(
 							relativePath ? `${relativePath}: ${issue.expected}` : issue.expected
 						);
-					} else {
+					} else if (issue.code === 'custom') {
 						expectedShape.push(relativePath);
 					}
 				}
 				if (expectedShape.length === 1 && !expectedShape[0]?.includes(':')) {
 					// In this case the expected shape is not an object, but probably a literal type, e.g. `['string']`.
 					expectedShapes.push(expectedShape.join(''));
-				} else {
+				} else if (expectedShape.length > 0) {
 					expectedShapes.push(`{ ${expectedShape.join('; ')} }`);
 				}
 			}
 			if (expectedShapes.length) {
 				details.push('> Expected type `' + expectedShapes.join(' | ') + '`');
-				details.push('> Received `' + stringify(ctx.data) + '`');
+				details.push('> Received `' + stringify(issue.input) + '`');
 			}
 		}
 
-		return {
-			message: messages.concat(details).join('\n'),
-		};
-	} else if (baseError.code === 'invalid_literal' || baseError.code === 'invalid_type') {
-		return {
-			message: prefix(
-				baseErrorPath,
-				getTypeOrLiteralMsg({
-					code: baseError.code,
-					received: baseError.received,
-					expected: [baseError.expected],
-				})
-			),
-		};
-	} else if (baseError.message) {
-		return { message: prefix(baseErrorPath, baseError.message) };
+		return messages.concat(details).join('\n');
+	} else if (issue.code === 'invalid_type') {
+		return prefix(
+			baseErrorPath,
+			getTypeErrMsg({
+				code: issue.code,
+				received: parsedType(issue.input),
+				expected: [issue.expected],
+				message: issue.message,
+			})
+		);
+	} else if (issue.message) {
+		return prefix(baseErrorPath, issue.message);
 	} else {
-		return { message: prefix(baseErrorPath, ctx.defaultError) };
+		// By design, the default Zod error may not be provided in Zod 4 error maps. Instead, error
+		// maps are supposed to return `undefined` in order to yield control to the next error map in
+		// the precedence chain. Unfortunately, this prevents us from prefixing all errors with their
+		// paths so we have to manually invoke the default Zod error map here.
+		const defaultError = zodErrorMap(issue);
+		if (!defaultError) return;
+
+		return prefix(
+			baseErrorPath,
+			typeof defaultError === 'string' ? defaultError : defaultError.message
+		);
 	}
 };
 
-const getTypeOrLiteralMsg = (error: TypeOrLiteralErrByPathEntry): string => {
+const getTypeErrMsg = (error: TypeErrByPathEntry): string => {
 	// received could be `undefined` or the string `'undefined'`
-	if (typeof error.received === 'undefined' || error.received === 'undefined') return 'Required';
+	if (typeof error.received === 'undefined' || error.received === 'undefined')
+		return error.message ?? 'Required';
 	const expectedDeduped = new Set(error.expected);
-	switch (error.code) {
-		case 'invalid_type':
-			return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
-				error.received
-			)}\``;
-		case 'invalid_literal':
-			return `Expected \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
-				error.received
-			)}\``;
-	}
+	return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
+		error.received
+	)}\``;
 };
 
 const prefix = (key: string, msg: string) => (key.length ? `**${key}**: ${msg}` : msg);
@@ -166,10 +179,38 @@ const prefix = (key: string, msg: string) => (key.length ? `**${key}**: ${msg}`
 const unionExpectedVals = (expectedVals: Set<unknown>) =>
 	[...expectedVals].map((expectedVal) => stringify(expectedVal)).join(' | ');
 
-const flattenErrorPath = (errorPath: (string | number)[]) => errorPath.join('.');
+const flattenErrorPath = (errorPath: PropertyKey[]) => errorPath.join('.');
 
 /** `JSON.stringify()` a value with spaces around object/array entries. */
 const stringify = (val: unknown) =>
 	JSON.stringify(val, null, 1).split(newlinePlusWhitespace).join(' ');
 const newlinePlusWhitespace = /\n\s*/;
 const leadingPeriod = /^\./;
+
+/**
+ * In Zod 4, we don't necessarily get a human-readable representation of input data types. For such
+ * cases, we use the same logic as Zod's own `parsedType()` function.
+ * @see https://github.com/colinhacks/zod/blob/73b071d7d08825dedb6b48b78718739118ee1308/packages/zod/src/v4/locales/en.ts#L5
+ */
+const parsedType = (data: unknown): string => {
+	const t = typeof data;
+
+	switch (t) {
+		case 'number': {
+			return Number.isNaN(data) ? 'NaN' : 'number';
+		}
+		case 'object': {
+			if (Array.isArray(data)) {
+				return 'array';
+			}
+			if (data === null) {
+				return 'null';
+			}
+
+			if (data && Object.getPrototypeOf(data) !== Object.prototype && data.constructor) {
+				return data.constructor.name;
+			}
+		}
+	}
+	return t;
+};

package/utils/navigation.ts

@@ -28,7 +28,7 @@ import type {
 	Route,
 	SidebarEntry,
 } from './routing/types';
-import { localeToLang, localizedId, slugToPathname } from './slugs';
+import { localeToLang, localizedFilePath, slugToPathname } from './slugs';
 import { isAbsoluteUrl } from './url';
 import type { StarlightConfig } from './user-config';
 
@@ -145,7 +145,7 @@ function linkFromInternalSidebarLinkItem(
 	// Astro passes root `index.[md|mdx]` entries with a slug of `index`
 	const slug = item.slug === 'index' ? '' : item.slug;
 	const localizedSlug = locale ? (slug ? locale + '/' + slug : locale) : slug;
-	const route = routes.find((entry) => localizedSlug === entry.slug);
+	const route = routes.find((entry) => localizedSlug === entry.id);
 	if (!route) {
 		const hasExternalSlashes = item.slug.at(0) === '/' || item.slug.at(-1) === '/';
 		if (hasExternalSlashes) {
@@ -170,7 +170,7 @@ function linkFromInternalSidebarLinkItem(
 	const badge = item.badge ?? frontmatter.sidebar?.badge;
 	const attrs = { ...frontmatter.sidebar?.attrs, ...item.attrs };
 	return makeSidebarLink(
-		slugToPathname(route.slug),
+		slugToPathname(route.id),
 		label,
 		getSidebarBadge(badge, locale, label),
 		attrs
@@ -225,12 +225,13 @@ function getBreadcrumbs(path: string, baseDir: string): string[] {
 	return relativePath.split('/');
 }
 
-/** Return the path of a route relative to the root of the collection, which is equivalent to legacy IDs. */
+/** Return the path of a route relative to the root of the collection. */
 function getRoutePathRelativeToCollectionRoot(route: Route, locale: string | undefined) {
-	return project.legacyCollections
-		? route.id
-		: // For collections with a loader, use a localized filePath relative to the collection
-			localizedId(route.entry.filePath.replace(`${docsCollectionPathFromRoot}/`, ''), locale);
+	// Use a localized filePath relative to the collection
+	return localizedFilePath(
+		route.entry.filePath.replace(`${docsCollectionPathFromRoot}/`, ''),
+		locale
+	);
 }
 
 /** Turn a flat array of routes into a tree structure. */
@@ -274,7 +275,7 @@ function treeify(routes: Route[], locale: string | undefined, baseDir: string):
 /** Create a link entry for a given content collection entry. */
 function linkFromRoute(route: Route, attrs?: LinkHTMLAttributes): SidebarLink {
 	return makeSidebarLink(
-		slugToPathname(route.slug),
+		slugToPathname(route.id),
 		route.entry.data.sidebar.label || route.entry.data.title,
 		route.entry.data.sidebar.badge,
 		{ ...attrs, ...route.entry.data.sidebar.attrs }
@@ -300,7 +301,7 @@ function sortDirEntries(dir: [string, Dir | Route][]): [string, Dir | Route][] {
 		// Pages are sorted by order in ascending order.
 		if (aOrder !== bOrder) return aOrder < bOrder ? -1 : 1;
 		// If two pages have the same order value they will be sorted by their slug.
-		return collator.compare(isDir(a) ? a[SlugKey] : a.slug, isDir(b) ? b[SlugKey] : b.slug);
+		return collator.compare(isDir(a) ? a[SlugKey] : a.id, isDir(b) ? b[SlugKey] : b.id);
 	});
 }