@astrojs/starlight 0.37.7 → 0.38.0

package/utils/plugins.ts

@@ -183,8 +183,8 @@ export function injectPluginTranslationsTypes(
 // https://github.com/withastro/astro/blob/910eb00fe0b70ca80bd09520ae100e8c78b675b5/packages/astro/src/core/config/schema.ts#L113
 const astroIntegrationSchema = z.object({
 	name: z.string(),
-	hooks: z.object({}).passthrough().default({}),
-}) as z.Schema<AstroIntegration>;
+	hooks: z.looseObject({}).default({}),
+}) as z.ZodType<AstroIntegration, AstroIntegration>;
 
 const routeMiddlewareConfigSchema = z.object({
 	entrypoint: z.string(),
@@ -196,9 +196,12 @@ const baseStarlightPluginSchema = z.object({
 	name: z.string(),
 });
 
+type StarlightConfigUpdate = Partial<Omit<StarlightUserConfig, 'routeMiddleware'>>;
+type StarlightI18nTFactory = Awaited<ReturnType<typeof createTranslationSystemFromFs>>;
+
 const configSetupHookSchema = z
-	.function(
-		z.tuple([
+	.function({
+		input: [
 			z.object({
 				/**
 				 * A read-only copy of the user-supplied Starlight configuration.
@@ -206,9 +209,10 @@ const configSetupHookSchema = z
 				 * Note that this configuration may have been updated by other plugins configured
 				 * before this one.
 				 */
-				config: z.any() as z.Schema<
+				config: z.any() as z.ZodType<
 					// The configuration passed to plugins should contains the list of plugins.
-					StarlightUserConfig & { plugins?: z.input<typeof baseStarlightPluginSchema>[] }
+					StarlightUserConfigWithPlugins,
+					StarlightUserConfigWithPlugins
 				>,
 				/**
 				 * A callback function to update the user-supplied Starlight configuration.
@@ -228,12 +232,15 @@ const configSetupHookSchema = z
 				 *	}
 				 * }
 				 */
-				updateConfig: z.function(
-					z.tuple([
-						z.record(z.any()) as z.Schema<Partial<Omit<StarlightUserConfig, 'routeMiddleware'>>>,
-					]),
-					z.void()
-				),
+				updateConfig: z.function({
+					input: [
+						z.record(z.string(), z.any()) as z.ZodType<
+							StarlightConfigUpdate,
+							StarlightConfigUpdate
+						>,
+					],
+					output: z.void(),
+				}),
 				/**
 				 * A callback function to add an Astro integration required by this plugin.
 				 *
@@ -256,7 +263,10 @@ const configSetupHookSchema = z
 				 * 	}
 				 * }
 				 */
-				addIntegration: z.function(z.tuple([astroIntegrationSchema]), z.void()),
+				addIntegration: z.function({
+					input: [astroIntegrationSchema],
+					output: z.void(),
+				}),
 				/**
 				 * A callback function to register additional route middleware handlers.
 				 *
@@ -273,7 +283,10 @@ const configSetupHookSchema = z
 				 * 	},
 				 * }
 				 */
-				addRouteMiddleware: z.function(z.tuple([routeMiddlewareConfigSchema]), z.void()),
+				addRouteMiddleware: z.function({
+					input: [routeMiddlewareConfigSchema],
+					output: z.void(),
+				}),
 				/**
 				 * A read-only copy of the user-supplied Astro configuration.
 				 *
@@ -281,26 +294,38 @@ const configSetupHookSchema = z
 				 *
 				 * @see https://docs.astro.build/en/reference/integrations-reference/#config-option
 				 */
-				astroConfig: z.any() as z.Schema<StarlightPluginContext['config']>,
+				astroConfig: z.any() as z.ZodType<
+					StarlightPluginContext['config'],
+					StarlightPluginContext['config']
+				>,
 				/**
 				 * The command used to run Starlight.
 				 *
 				 * @see https://docs.astro.build/en/reference/integrations-reference/#command-option
 				 */
-				command: z.any() as z.Schema<StarlightPluginContext['command']>,
+				command: z.any() as z.ZodType<
+					StarlightPluginContext['command'],
+					StarlightPluginContext['command']
+				>,
 				/**
 				 * `false` when the dev server starts, `true` when a reload is triggered.
 				 *
 				 * @see https://docs.astro.build/en/reference/integrations-reference/#isrestart-option
 				 */
-				isRestart: z.any() as z.Schema<StarlightPluginContext['isRestart']>,
+				isRestart: z.any() as z.ZodType<
+					StarlightPluginContext['isRestart'],
+					StarlightPluginContext['isRestart']
+				>,
 				/**
 				 * An instance of the Astro integration logger with all logged messages prefixed with the
 				 * plugin name.
 				 *
 				 * @see https://docs.astro.build/en/reference/integrations-reference/#astrointegrationlogger
 				 */
-				logger: z.any() as z.Schema<StarlightPluginContext['logger']>,
+				logger: z.any() as z.ZodType<
+					StarlightPluginContext['logger'],
+					StarlightPluginContext['logger']
+				>,
 				/**
 				 * A callback function to generate a utility function to access UI strings for a given
 				 * language.
@@ -319,9 +344,7 @@ const configSetupHookSchema = z
 				 *	}
 				 * }
 				 */
-				useTranslations: z.any() as z.Schema<
-					Awaited<ReturnType<typeof createTranslationSystemFromFs>>
-				>,
+				useTranslations: z.any() as z.ZodType<StarlightI18nTFactory, StarlightI18nTFactory>,
 				/**
 				 * A callback function to get the language for a given absolute file path. The returned
 				 * language can be used with the `useTranslations` helper to get UI strings for that
@@ -344,11 +367,17 @@ const configSetupHookSchema = z
 				 *	}
 				 * }
 				 */
-				absolutePathToLang: z.function(z.tuple([z.string()]), z.string()),
+				absolutePathToLang: z.function({
+					input: [z.string()],
+					output: z.string(),
+				}),
 			}),
-		]),
-		z.union([z.void(), z.promise(z.void())])
-	)
+		],
+		// We still rely on the deprecated `z.promise()` to define the function output as the only
+		// non-deprecated way to define an async function is to use `.implementAsync()` but we don't
+		// want to implement the function using Zod.
+		output: z.promise(z.void()),
+	})
 	.optional();
 
 /**
@@ -356,8 +385,9 @@ const configSetupHookSchema = z
  * user config schema but properly typed for user convenience because we do not want to run any of
  * the Zod `transform`s used in the user config schema when running plugins.
  */
-const starlightPluginSchema = baseStarlightPluginSchema
-	.extend({
+const starlightPluginSchema = z
+	.object({
+		...baseStarlightPluginSchema.shape,
 		/** The different hooks available to the plugin. */
 		hooks: z.object({
 			/**
@@ -366,8 +396,8 @@ const starlightPluginSchema = baseStarlightPluginSchema
 			 * and plugin UI.
 			 */
 			'i18n:setup': z
-				.function(
-					z.tuple([
+				.function({
+					input: [
 						z.object({
 							/**
 							 * A callback function to add or update translations strings.
@@ -391,14 +421,17 @@ const starlightPluginSchema = baseStarlightPluginSchema
 							 * 	}
 							 * }
 							 */
-							injectTranslations: z.function(
-								z.tuple([z.record(z.string(), z.record(z.string(), z.string()))]),
-								z.void()
-							),
+							injectTranslations: z.function({
+								input: [z.record(z.string(), z.record(z.string(), z.string()))],
+								output: z.void(),
+							}),
 						}),
-					]),
-					z.union([z.void(), z.promise(z.void())])
-				)
+					],
+					// We still rely on the deprecated `z.promise()` to define the function output as the
+					// only non-deprecated way to define an async function is to use `.implementAsync()` but
+					// we don't want to implement the function using Zod.
+					output: z.promise(z.void()),
+				})
 				.optional(),
 			/**
 			 * Plugin configuration setup function called with an object containing various values that
@@ -414,17 +447,19 @@ const starlightPluginSchema = baseStarlightPluginSchema
 	})
 	.superRefine((plugin, ctx) => {
 		if (!plugin.hooks['config:setup'] && !plugin.hooks.setup) {
-			ctx.addIssue({
-				code: z.ZodIssueCode.custom,
+			ctx.issues.push({
+				code: 'custom',
 				message: 'A plugin must define at least a `config:setup` hook.',
+				input: plugin,
 			});
 		} else if (plugin.hooks['config:setup'] && plugin.hooks.setup) {
-			ctx.addIssue({
-				code: z.ZodIssueCode.custom,
+			ctx.issues.push({
+				code: 'custom',
 				message:
 					'A plugin cannot define both a `config:setup` and `setup` hook. ' +
 					'As `setup` is deprecated and will be removed in a future version, ' +
 					'consider using `config:setup` instead.',
+				input: plugin,
 			});
 		}
 	});

package/utils/routing/data.ts

@@ -6,12 +6,7 @@ import { getNewestCommitDate } from 'virtual:starlight/git-info';
 import { getPrevNextLinks, getSidebar } from '../navigation';
 import { ensureTrailingSlash } from '../path';
 import { getRouteBySlugParam, normalizeCollectionEntry } from '../routing';
-import type {
-	Route,
-	StarlightDocsCollectionEntry,
-	StarlightDocsEntry,
-	StarlightRouteData,
-} from './types';
+import type { Route, StarlightDocsEntry, StarlightRouteData } from './types';
 import { formatPath } from '../format-path';
 import { useTranslations } from '../translations';
 import { BuiltInDefaultLocale } from '../i18n';
@@ -137,7 +132,6 @@ async function get404Route(locals: App.Locals): Promise<Route> {
 	const entryMeta = { dir, lang, locale };
 
 	const fallbackEntry: StarlightDocsEntry = {
-		slug: '404',
 		id: '404',
 		body: '',
 		collection: 'docs',
@@ -154,7 +148,7 @@ async function get404Route(locals: App.Locals): Promise<Route> {
 		filePath: `${getCollectionPathFromRoot('docs', project)}/404.md`,
 	};
 
-	const userEntry = (await getEntry('docs', '404')) as StarlightDocsCollectionEntry;
+	const userEntry = await getEntry('docs', '404');
 	const entry = userEntry ? normalizeCollectionEntry(userEntry) : fallbackEntry;
-	return { ...entryMeta, entryMeta, entry, id: entry.id, slug: entry.slug };
+	return { ...entryMeta, entryMeta, entry, id: entry.id };
 }

package/utils/routing/index.ts

@@ -1,9 +1,7 @@
 import type { GetStaticPathsItem } from 'astro';
 import { getCollection } from 'astro:content';
 import config from 'virtual:starlight/user-config';
-import project from 'virtual:starlight/project-context';
-import { getCollectionPathFromRoot } from '../collection';
-import { localizedId, localizedSlug, slugToLocaleData, slugToParam } from '../slugs';
+import { localizedSlug, slugToLocaleData, slugToParam } from '../slugs';
 import { validateLogoImports } from '../validateLogoImports';
 import { BuiltInDefaultLocale } from '../i18n';
 import type { Route, StarlightDocsCollectionEntry, StarlightDocsEntry } from './types';
@@ -24,17 +22,14 @@ interface Path extends GetStaticPathsItem {
  */
 const normalizeIndexSlug = (slug: string) => (slug === 'index' ? '' : slug);
 
-/** Normalize the different collection entry we can get from a legacy collection or a loader. */
+/** Normalize a collection entry. */
 export function normalizeCollectionEntry(entry: StarlightDocsCollectionEntry): StarlightDocsEntry {
-	const slug = normalizeIndexSlug(entry.slug ?? entry.id);
 	return {
 		...entry,
-		// In a collection with a loader, the `id` is a slug and should be normalized.
-		id: entry.slug ? entry.id : slug,
-		// In a legacy collection, the `filePath` property doesn't exist.
-		filePath: entry.filePath ?? `${getCollectionPathFromRoot('docs', project)}/${entry.id}`,
-		// In a collection with a loader, the `slug` property is replaced by the `id`.
-		slug: normalizeIndexSlug(entry.slug ?? entry.id),
+		// The `id` is a slug and should be normalized.
+		id: normalizeIndexSlug(entry.id),
+		// At the moment, Starlight only supports file-based loaders which always include a `filePath`.
+		filePath: entry.filePath!,
 	};
 }
 
@@ -49,10 +44,9 @@ const docs: StarlightDocsEntry[] = (
 function getRoutes(): Route[] {
 	const routes: Route[] = docs.map((entry) => ({
 		entry,
-		slug: entry.slug,
 		id: entry.id,
-		entryMeta: slugToLocaleData(entry.slug),
-		...slugToLocaleData(entry.slug),
+		entryMeta: slugToLocaleData(entry.id),
+		...slugToLocaleData(entry.id),
 	}));
 
 	// In multilingual sites, add required fallback routes.
@@ -68,19 +62,17 @@ function getRoutes(): Route[] {
 			const locale = key === 'root' ? undefined : key;
 			const localeDocs = getLocaleDocs(locale);
 			for (const fallback of defaultLocaleDocs) {
-				const slug = localizedSlug(fallback.slug, locale);
-				const id = project.legacyCollections ? localizedId(fallback.id, locale) : slug;
-				const doesNotNeedFallback = localeDocs.some((doc) => doc.slug === slug);
+				const id = localizedSlug(fallback.id, locale);
+				const doesNotNeedFallback = localeDocs.some((doc) => doc.id === id);
 				if (doesNotNeedFallback) continue;
 				routes.push({
 					entry: fallback,
-					slug,
 					id,
 					isFallback: true,
 					lang: localeConfig.lang || BuiltInDefaultLocale.lang,
 					locale,
 					dir: localeConfig.dir,
-					entryMeta: slugToLocaleData(fallback.slug),
+					entryMeta: slugToLocaleData(fallback.id),
 				});
 			}
 		}
@@ -93,7 +85,7 @@ export const routes = getRoutes();
 function getParamRouteMapping(): ReadonlyMap<string | undefined, Route> {
 	const map = new Map<string | undefined, Route>();
 	for (const route of routes) {
-		map.set(slugToParam(route.slug), route);
+		map.set(slugToParam(route.id), route);
 	}
 	return map;
 }
@@ -105,7 +97,7 @@ export function getRouteBySlugParam(slugParam: string | undefined): Route | unde
 
 function getPaths(): Path[] {
 	return routes.map((route) => ({
-		params: { slug: slugToParam(route.slug) },
+		params: { slug: slugToParam(route.id) },
 		props: route,
 	}));
 }
@@ -128,15 +120,15 @@ function getLocaleDocs(locale: string | undefined): StarlightDocsEntry[] {
 }
 
 /** Filter an array to find items whose slug matches the passed locale. */
-function filterByLocale<T extends { slug: string }>(items: T[], locale: string | undefined): T[] {
+function filterByLocale<T extends { id: string }>(items: T[], locale: string | undefined): T[] {
 	if (config.locales) {
 		if (locale && locale in config.locales) {
-			return items.filter((i) => i.slug === locale || i.slug.startsWith(locale + '/'));
+			return items.filter((i) => i.id === locale || i.id.startsWith(locale + '/'));
 		} else if (config.locales.root) {
 			const langKeys = Object.keys(config.locales).filter((k) => k !== 'root');
 			const isLangIndex = new RegExp(`^(${langKeys.join('|')})$`);
 			const isLangDir = new RegExp(`^(${langKeys.join('|')})/`);
-			return items.filter((i) => !isLangIndex.test(i.slug) && !isLangDir.test(i.slug));
+			return items.filter((i) => !isLangIndex.test(i.id) && !isLangDir.test(i.id));
 		}
 	}
 	return items;

package/utils/routing/types.ts

@@ -40,23 +40,13 @@ export interface PaginationLinks {
 	next: SidebarLink | undefined;
 }
 
-// The type returned from `CollectionEntry` is different for legacy collections and collections
-// using a loader. This type is a common subset of both types.
-export type StarlightDocsCollectionEntry = Omit<
-	CollectionEntry<'docs'>,
-	'id' | 'filePath' | 'render' | 'slug'
-> & {
-	// Update the `id` property to be a string like in the loader type.
-	id: string;
-	// Add the `filePath` property which is only present in the loader type.
-	filePath?: string;
-	// Add the `slug` property which is only present in the legacy type.
-	slug?: string;
-};
+// A type representing a docs collection entry returned by the `docsLoader()`.
+export type StarlightDocsCollectionEntry = CollectionEntry<'docs'>;
 
+// A normalized type representing a docs collection entry used throughout Starlight.
 export type StarlightDocsEntry = StarlightDocsCollectionEntry & {
+	// At the moment, Starlight only supports file-based loaders which always include a `filePath`.
 	filePath: string;
-	slug: string;
 };
 
 export interface Route extends LocaleData {
@@ -64,9 +54,7 @@ export interface Route extends LocaleData {
 	entry: StarlightDocsEntry;
 	/** Locale metadata for the page content. Can be different from top-level locale values when a page is using fallback content. */
 	entryMeta: LocaleData;
-	/** @deprecated Migrate to the new Content Layer API and use `id` instead. */
-	slug: string;
-	/** The slug or unique ID if using the `legacy.collections` flag. */
+	/** The slug. */
 	id: string;
 	/** Whether this page is untranslated in the current language and using fallback content from the default locale. */
 	isFallback?: boolean;

package/utils/slugs.ts

@@ -80,24 +80,23 @@ export function localizedSlug(slug: string, locale: string | undefined): string
 }
 
 /**
- * Convert a legacy collection entry ID or filePath relative to the collection root to a different
- * locale.
- * For example, passing an ID of `en/home.md` and a locale of `fr` results in `fr/home.md`.
+ * Convert a file path relative to the collection root to a different locale.
+ * For example, passing a file path of `en/home.md` and a locale of `fr` results in `fr/home.md`.
  * An undefined locale is treated as the root locale, resulting in `home.md`.
- * @param id A collection entry ID
+ * @param filePath A collection entry file path relative to the collection root
  * @param locale The target locale
  * @example
- * localizedSlug('en/home.md', 'fr')       // => 'fr/home.md'
- * localizedSlug('en/home.md', undefined)  // => 'home.md'
+ * localizedFilePath('en/home.md', 'fr')       // => 'fr/home.md'
+ * localizedFilePath('en/home.md', undefined)  // => 'home.md'
  */
-export function localizedId(id: string, locale: string | undefined): string {
-	const idLocale = slugToLocale(id);
-	if (idLocale) {
-		return id.replace(idLocale + '/', locale ? locale + '/' : '');
+export function localizedFilePath(filePath: string, locale: string | undefined): string {
+	const filePathLocale = slugToLocale(filePath);
+	if (filePathLocale) {
+		return filePath.replace(filePathLocale + '/', locale ? locale + '/' : '');
 	} else if (locale) {
-		return locale + '/' + id;
+		return locale + '/' + filePath;
 	} else {
-		return id;
+		return filePath;
 	}
 }
 

package/utils/starlight-page.ts

@@ -83,7 +83,7 @@ const validateSidebarProp = (
  */
 export type StarlightPageProps = Prettify<
 	// Remove the index signature from `Route`, omit undesired properties and make the rest optional.
-	Partial<Omit<RemoveIndexSignature<PageProps>, 'entry' | 'entryMeta' | 'id' | 'locale' | 'slug'>> &
+	Partial<Omit<RemoveIndexSignature<PageProps>, 'entry' | 'entryMeta' | 'id' | 'locale'>> &
 		// Add the sidebar definitions for a Starlight page.
 		Partial<Pick<StarlightRouteData, 'hasSidebar'>> & {
 			sidebar?: StarlightUserConfig['sidebar'];
@@ -97,13 +97,7 @@ export type StarlightPageProps = Prettify<
  * to a `StarlightDocsEntry`.
  * A Starlight page docs entry cannot be rendered like a content collection entry.
  */
-type StarlightPageDocsEntry = Omit<StarlightDocsEntry, 'id' | 'render'> & {
-	/**
-	 * The unique ID if using the `legacy.collections` for this Starlight page which cannot be
-	 * inferred from codegen like content collection entries or the slug.
-	 */
-	id: string;
-};
+type StarlightPageDocsEntry = Omit<StarlightDocsEntry, 'render'>;
 
 export async function generateStarlightPageRouteData({
 	props,
@@ -114,20 +108,18 @@ export async function generateStarlightPageRouteData({
 }): Promise<StarlightRouteData> {
 	const { frontmatter, ...routeProps } = props;
 	const { url } = context;
-	const slug = urlToSlug(url);
+	const id = urlToSlug(url);
 	const pageFrontmatter = await getStarlightPageFrontmatter(frontmatter);
-	const id = project.legacyCollections ? `${stripLeadingAndTrailingSlashes(slug)}.md` : slug;
-	const localeData = slugToLocaleData(slug);
+	const localeData = slugToLocaleData(id);
 	const sidebar = props.sidebar
 		? getSidebarFromConfig(validateSidebarProp(props.sidebar), url.pathname, localeData.locale)
 		: getSidebar(url.pathname, localeData.locale);
 	const headings = props.headings ?? [];
 	const pageDocsEntry: StarlightPageDocsEntry = {
 		id,
-		slug,
 		body: '',
 		collection: 'docs',
-		filePath: `${getCollectionPathFromRoot('docs', project)}/${stripLeadingAndTrailingSlashes(slug)}.md`,
+		filePath: `${getCollectionPathFromRoot('docs', project)}/${stripLeadingAndTrailingSlashes(id)}.md`,
 		data: {
 			...pageFrontmatter,
 			sidebar: {
@@ -153,7 +145,6 @@ export async function generateStarlightPageRouteData({
 		headings,
 		id,
 		locale: localeData.locale,
-		slug,
 	};
 	const siteTitle = getSiteTitle(localeData.lang);
 	const routeData: StarlightRouteData = {
@@ -171,7 +162,6 @@ export async function generateStarlightPageRouteData({
 		sidebar,
 		siteTitle,
 		siteTitleHref: getSiteTitleHref(localeData.locale),
-		slug,
 		toc: getToC(pageProps),
 	};
 	return routeData;
@@ -185,16 +175,16 @@ async function getStarlightPageFrontmatter(frontmatter: StarlightPageFrontmatter
 			// https://github.com/withastro/astro/blob/cf993bc263b58502096f00d383266cd179f331af/packages/astro/src/assets/types.ts#L32
 			// It uses a custom validation approach because imported SVGs have a type of `function` as
 			// well as containing the metadata properties and this ensures we handle those correctly.
-			z.custom(
+			z.custom<ReturnType<ImageFunction>>(
 				(value) =>
-					(value &&
-						(typeof value === 'function' || typeof value === 'object') &&
-						'src' in value &&
-						'width' in value &&
-						'height' in value &&
-						'format' in value) as ReturnType<ImageFunction>,
+					value &&
+					(typeof value === 'function' || typeof value === 'object') &&
+					'src' in value &&
+					'width' in value &&
+					'height' in value &&
+					'format' in value,
 				'Invalid image passed to `<StarlightPage>` component. Expected imported `ImageMetadata` object.'
-			)) as ImageFunction,
+			)) as unknown as ImageFunction,
 	});
 
 	// Starting with Astro 4.14.0, a frontmatter schema that contains collection references will

package/utils/translations.ts

@@ -32,10 +32,9 @@ async function loadTranslations() {
 		// eslint-disable-next-line @typescript-eslint/ban-ts-comment
 		// @ts-ignore — may be a type error in projects without an i18n collection
 		(await getCollection('i18n')).map(({ id, data, filePath }) => {
-			const lang =
-				project.legacyCollections || !filePath
-					? id
-					: stripExtension(stripLeadingSlash(filePath.replace(i18nCollectionPathFromRoot, '')));
+			const lang = !filePath
+				? id
+				: stripExtension(stripLeadingSlash(filePath.replace(i18nCollectionPathFromRoot, '')));
 			return [lang, data] as const;
 		})
 	);