@astrojs/starlight 0.31.0 → 0.32.0

package/utils/plugins.ts

@@ -1,8 +1,15 @@
-import type { AstroIntegration, HookParameters } from 'astro';
+import type { AstroIntegration, HookParameters as AstroHookParameters } from 'astro';
+import { AstroError } from 'astro/errors';
 import { z } from 'astro/zod';
-import { StarlightConfigSchema, type StarlightUserConfig } from '../utils/user-config';
 import { parseWithFriendlyErrors } from '../utils/error-map';
+import {
+	StarlightConfigSchema,
+	type StarlightConfig,
+	type StarlightUserConfig,
+} from '../utils/user-config';
 import type { UserI18nSchema } from './translations';
+import { createTranslationSystemFromFs } from './translations-fs';
+import { absolutePathToLang as getAbsolutePathFromLang } from '../integrations/shared/absolutePathToLang';
 
 /**
  * Runs Starlight plugins in the order that they are configured after validating the user-provided
@@ -30,22 +37,61 @@ export async function runPlugins(
 		'Invalid plugins config passed to starlight integration'
 	);
 
-	// A list of Astro integrations added by the various plugins.
-	const integrations: AstroIntegration[] = [];
 	// A list of translations injected by the various plugins keyed by locale.
 	const pluginTranslations: PluginTranslations = {};
+	// A list of route middleware added by the various plugins.
+	const routeMiddlewareConfigs: Array<z.output<typeof routeMiddlewareConfigSchema>> = [];
+
+	for (const {
+		hooks: { 'i18n:setup': i18nSetup },
+	} of pluginsConfig) {
+		if (i18nSetup) {
+			await i18nSetup({
+				injectTranslations(translations) {
+					// Merge the translations injected by the plugin.
+					for (const [locale, localeTranslations] of Object.entries(translations)) {
+						pluginTranslations[locale] ??= {};
+						Object.assign(pluginTranslations[locale]!, localeTranslations);
+					}
+				},
+			});
+		}
+	}
+
+	const useTranslations = createTranslationSystemFromFs(
+		starlightConfig,
+		context.config,
+		pluginTranslations
+	);
+
+	function absolutePathToLang(path: string) {
+		return getAbsolutePathFromLang(path, { astroConfig: context.config, starlightConfig });
+	}
+
+	// A list of Astro integrations added by the various plugins.
+	const integrations: AstroIntegration[] = [];
 
 	for (const {
 		name,
-		hooks: { setup },
+		hooks: { 'config:setup': configSetup, setup: deprecatedSetup },
 	} of pluginsConfig) {
+		// A refinement in the schema ensures that at least one of the two hooks is defined.
+		const setup = (configSetup ?? deprecatedSetup)!;
+
 		await setup({
 			config: pluginsUserConfig ? { ...userConfig, plugins: pluginsUserConfig } : userConfig,
 			updateConfig(newConfig) {
 				// Ensure that plugins do not update the `plugins` config key.
 				if ('plugins' in newConfig) {
-					throw new Error(
-						`The '${name}' plugin tried to update the 'plugins' config key which is not supported.`
+					throw new AstroError(
+						`The \`${name}\` plugin tried to update the \`plugins\` config key which is not supported.`
+					);
+				}
+				if ('routeMiddleware' in newConfig) {
+					throw new AstroError(
+						`The \`${name}\` plugin tried to update the \`routeMiddleware\` config key which is not supported.`,
+						'Use the `addRouteMiddleware()` utility instead.\n' +
+							'See https://starlight.astro.build/reference/plugins/#addroutemiddleware for more details.'
 					);
 				}
 
@@ -65,6 +111,9 @@ export async function runPlugins(
 				// Collect any Astro integrations added by the plugin.
 				integrations.push(integration);
 			},
+			addRouteMiddleware(middlewareConfig) {
+				routeMiddlewareConfigs.push(middlewareConfig);
+			},
 			astroConfig: {
 				...context.config,
 				integrations: [...context.config.integrations, ...integrations],
@@ -72,22 +121,37 @@ export async function runPlugins(
 			command: context.command,
 			isRestart: context.isRestart,
 			logger: context.logger.fork(name),
-			injectTranslations(translations) {
-				// Merge the translations injected by the plugin.
-				for (const [locale, localeTranslations] of Object.entries(translations)) {
-					pluginTranslations[locale] ??= {};
-					Object.assign(pluginTranslations[locale]!, localeTranslations);
-				}
-			},
+			useTranslations,
+			absolutePathToLang,
 		});
 	}
 
-	return { integrations, starlightConfig, pluginTranslations };
+	applyPluginMiddleware(routeMiddlewareConfigs, starlightConfig);
+
+	return { integrations, starlightConfig, pluginTranslations, useTranslations, absolutePathToLang };
+}
+
+/** Updates `routeMiddleware` in the Starlight config to add plugin middlewares in the correct order. */
+function applyPluginMiddleware(
+	routeMiddlewareConfigs: { entrypoint: string; order: 'default' | 'pre' | 'post' }[],
+	starlightConfig: StarlightConfig
+) {
+	const middlewareBuckets = routeMiddlewareConfigs.reduce<
+		Record<'pre' | 'default' | 'post', string[]>
+	>(
+		(buckets, { entrypoint, order = 'default' }) => {
+			buckets[order].push(entrypoint);
+			return buckets;
+		},
+		{ pre: [], default: [], post: [] }
+	);
+	starlightConfig.routeMiddleware.unshift(...middlewareBuckets.pre);
+	starlightConfig.routeMiddleware.push(...middlewareBuckets.default, ...middlewareBuckets.post);
 }
 
 export function injectPluginTranslationsTypes(
 	translations: PluginTranslations,
-	injectTypes: HookParameters<'astro:config:done'>['injectTypes']
+	injectTypes: AstroHookParameters<'astro:config:done'>['injectTypes']
 ) {
 	const allKeys = new Set<string>();
 
@@ -118,140 +182,246 @@ const astroIntegrationSchema = z.object({
 	hooks: z.object({}).passthrough().default({}),
 }) as z.Schema<AstroIntegration>;
 
+const routeMiddlewareConfigSchema = z.object({
+	entrypoint: z.string(),
+	order: z.enum(['pre', 'post', 'default']).default('default'),
+});
+
 const baseStarlightPluginSchema = z.object({
 	/** Name of the Starlight plugin. */
 	name: z.string(),
 });
 
+const configSetupHookSchema = z
+	.function(
+		z.tuple([
+			z.object({
+				/**
+				 * A read-only copy of the user-supplied Starlight configuration.
+				 *
+				 * Note that this configuration may have been updated by other plugins configured
+				 * before this one.
+				 */
+				config: z.any() as z.Schema<
+					// The configuration passed to plugins should contains the list of plugins.
+					StarlightUserConfig & { plugins?: z.input<typeof baseStarlightPluginSchema>[] }
+				>,
+				/**
+				 * A callback function to update the user-supplied Starlight configuration.
+				 *
+				 * You only need to provide the configuration values that you want to update but no deep
+				 * merge is performed.
+				 *
+				 * @example
+				 * {
+				 * 	name: 'My Starlight Plugin',
+				 *	hooks: {
+				 * 		'config:setup'({ updateConfig }) {
+				 * 			updateConfig({
+				 * 				description: 'Custom description',
+				 * 			});
+				 * 		}
+				 *	}
+				 * }
+				 */
+				updateConfig: z.function(
+					z.tuple([
+						z.record(z.any()) as z.Schema<Partial<Omit<StarlightUserConfig, 'routeMiddleware'>>>,
+					]),
+					z.void()
+				),
+				/**
+				 * A callback function to add an Astro integration required by this plugin.
+				 *
+				 * @see https://docs.astro.build/en/reference/integrations-reference/
+				 *
+				 * @example
+				 * {
+				 * 	name: 'My Starlight Plugin',
+				 * 	hooks: {
+				 * 		'config:setup'({ addIntegration }) {
+				 * 			addIntegration({
+				 * 				name: 'My Plugin Astro Integration',
+				 * 				hooks: {
+				 * 					'astro:config:setup': () => {
+				 * 						// …
+				 * 					},
+				 * 				},
+				 * 			});
+				 * 		}
+				 * 	}
+				 * }
+				 */
+				addIntegration: z.function(z.tuple([astroIntegrationSchema]), z.void()),
+				/**
+				 * A callback function to register additional route middleware handlers.
+				 *
+				 * If the order of execution is important, a plugin can use the `order` option to enforce
+				 * running first or last.
+				 *
+				 * @example
+				 * {
+				 * 	name: 'My Starlight Plugin',
+				 * 	hooks: {
+				 * 		setup({ addRouteMiddleware }) {
+				 * 			addRouteMiddleware({ entrypoint: '@me/my-plugin/route-middleware' });
+				 * 		},
+				 * 	},
+				 * }
+				 */
+				addRouteMiddleware: z.function(z.tuple([routeMiddlewareConfigSchema]), z.void()),
+				/**
+				 * A read-only copy of the user-supplied Astro configuration.
+				 *
+				 * Note that this configuration is resolved before any other integrations have run.
+				 *
+				 * @see https://docs.astro.build/en/reference/integrations-reference/#config-option
+				 */
+				astroConfig: z.any() as z.Schema<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']>,
+				/**
+				 * `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']>,
+				/**
+				 * 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']>,
+				/**
+				 * A callback function to generate a utility function to access UI strings for a given
+				 * language.
+				 *
+				 * @see https://starlight.astro.build/guides/i18n/#using-ui-translations
+				 *
+				 * @example
+				 * {
+				 * 	name: 'My Starlight Plugin',
+				 *	hooks: {
+				 * 		'config:setup'({ useTranslations, logger }) {
+				 * 			const t = useTranslations('en');
+				 * 			logger.info(t('builtWithStarlight.label'));
+				 * 		  // ^ Logs 'Built with Starlight' to the console.
+				 * 		}
+				 *	}
+				 * }
+				 */
+				useTranslations: z.any() as z.Schema<ReturnType<typeof createTranslationSystemFromFs>>,
+				/**
+				 * 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
+				 * language.
+				 *
+				 * This can be particularly useful in remark or rehype plugins to get the language for
+				 * the current file being processed and use it to get the appropriate UI strings for that
+				 * language.
+				 *
+				 * @example
+				 * {
+				 * 	name: 'My Starlight Plugin',
+				 *	hooks: {
+				 * 		'config:setup'({ absolutePathToLang, useTranslations, logger }) {
+				 * 			const lang = absolutePathToLang('/absolute/path/to/project/src/content/docs/fr/index.mdx');
+				 * 			const t = useTranslations(lang);
+				 * 			logger.info(t('aside.tip'));
+				 * 		  // ^ Logs 'Astuce' to the console.
+				 * 		}
+				 *	}
+				 * }
+				 */
+				absolutePathToLang: z.function(z.tuple([z.string()]), z.string()),
+			}),
+		]),
+		z.union([z.void(), z.promise(z.void())])
+	)
+	.optional();
+
 /**
  * A plugin `config` and `updateConfig` argument are purposely not validated using the Starlight
  * 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({
-	/** The different hooks available to the plugin. */
-	hooks: z.object({
-		/**
-		 * Plugin setup function called with an object containing various values that can be used by
-		 * the plugin to interact with Starlight.
-		 */
-		setup: z.function(
-			z.tuple([
-				z.object({
-					/**
-					 * A read-only copy of the user-supplied Starlight configuration.
-					 *
-					 * Note that this configuration may have been updated by other plugins configured
-					 * before this one.
-					 */
-					config: z.any() as z.Schema<
-						// The configuration passed to plugins should contains the list of plugins.
-						StarlightUserConfig & { plugins?: z.input<typeof baseStarlightPluginSchema>[] }
-					>,
-					/**
-					 * A callback function to update the user-supplied Starlight configuration.
-					 *
-					 * You only need to provide the configuration values that you want to update but no deep
-					 * merge is performed.
-					 *
-					 * @example
-					 * {
-					 * 	name: 'My Starlight Plugin',
-					 *	hooks: {
-					 * 		setup({ updateConfig }) {
-					 * 			updateConfig({
-					 * 				description: 'Custom description',
-					 * 			});
-					 * 		}
-					 *	}
-					 * }
-					 */
-					updateConfig: z.function(
-						z.tuple([z.record(z.any()) as z.Schema<Partial<StarlightUserConfig>>]),
-						z.void()
-					),
-					/**
-					 * A callback function to add an Astro integration required by this plugin.
-					 *
-					 * @see https://docs.astro.build/en/reference/integrations-reference/
-					 *
-					 * @example
-					 * {
-					 * 	name: 'My Starlight Plugin',
-					 * 	hooks: {
-					 * 		setup({ addIntegration }) {
-					 * 			addIntegration({
-					 * 				name: 'My Plugin Astro Integration',
-					 * 				hooks: {
-					 * 					'astro:config:setup': () => {
-					 * 						// …
-					 * 					},
-					 * 				},
-					 * 			});
-					 * 		}
-					 * 	}
-					 * }
-					 */
-					addIntegration: z.function(z.tuple([astroIntegrationSchema]), z.void()),
-					/**
-					 * A read-only copy of the user-supplied Astro configuration.
-					 *
-					 * Note that this configuration is resolved before any other integrations have run.
-					 *
-					 * @see https://docs.astro.build/en/reference/integrations-reference/#config-option
-					 */
-					astroConfig: z.any() as z.Schema<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']>,
-					/**
-					 * `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']>,
-					/**
-					 * 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']>,
-					/**
-					 * A callback function to add or update translations strings.
-					 *
-					 * @see https://starlight.astro.build/guides/i18n/#extend-translation-schema
-					 *
-					 * @example
-					 * {
-					 * 	name: 'My Starlight Plugin',
-					 * 	hooks: {
-					 * 		setup({ injectTranslations }) {
-					 * 			injectTranslations({
-					 * 				en: {
-					 * 					'myPlugin.doThing': 'Do the thing',
-					 * 				},
-					 * 				fr: {
-					 * 					'myPlugin.doThing': 'Faire le truc',
-					 * 				},
-					 * 			});
-					 * 		}
-					 * 	}
-					 * }
-					 */
-					injectTranslations: z.function(
-						z.tuple([z.record(z.string(), z.record(z.string(), z.string()))]),
-						z.void()
-					),
-				}),
-			]),
-			z.union([z.void(), z.promise(z.void())])
-		),
-	}),
-});
+const starlightPluginSchema = baseStarlightPluginSchema
+	.extend({
+		/** The different hooks available to the plugin. */
+		hooks: z.object({
+			/**
+			 * Plugin internationalization setup function allowing to inject translations strings for the
+			 * plugin in various locales. These translations will be available in the `config:setup` hook
+			 * and plugin UI.
+			 */
+			'i18n:setup': z
+				.function(
+					z.tuple([
+						z.object({
+							/**
+							 * A callback function to add or update translations strings.
+							 *
+							 * @see https://starlight.astro.build/guides/i18n/#extend-translation-schema
+							 *
+							 * @example
+							 * {
+							 * 	name: 'My Starlight Plugin',
+							 * 	hooks: {
+							 * 		'i18n:setup'({ injectTranslations }) {
+							 * 			injectTranslations({
+							 * 				en: {
+							 * 					'myPlugin.doThing': 'Do the thing',
+							 * 				},
+							 * 				fr: {
+							 * 					'myPlugin.doThing': 'Faire le truc',
+							 * 				},
+							 * 			});
+							 * 		}
+							 * 	}
+							 * }
+							 */
+							injectTranslations: z.function(
+								z.tuple([z.record(z.string(), z.record(z.string(), z.string()))]),
+								z.void()
+							),
+						}),
+					]),
+					z.union([z.void(), z.promise(z.void())])
+				)
+				.optional(),
+			/**
+			 * Plugin configuration setup function called with an object containing various values that
+			 * can be used by the plugin to interact with Starlight.
+			 */
+			'config:setup': configSetupHookSchema,
+			/**
+			 * @deprecated Use the `config:setup` hook instead as `setup` will be removed in a future
+			 * version.
+			 */
+			setup: configSetupHookSchema,
+		}),
+	})
+	.superRefine((plugin, ctx) => {
+		if (!plugin.hooks['config:setup'] && !plugin.hooks.setup) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: 'A plugin must define at least a `config:setup` hook.',
+			});
+		} else if (plugin.hooks['config:setup'] && plugin.hooks.setup) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.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.',
+			});
+		}
+	});
 
 const starlightPluginsConfigSchema = z.array(starlightPluginSchema).default([]);
 
@@ -259,6 +429,11 @@ type StarlightPluginsUserConfig = z.input<typeof starlightPluginsConfigSchema>;
 
 export type StarlightPlugin = z.input<typeof starlightPluginSchema>;
 
+export type HookParameters<
+	Hook extends keyof StarlightPlugin['hooks'],
+	HookFn = StarlightPlugin['hooks'][Hook],
+> = HookFn extends (...args: any) => any ? Parameters<HookFn>[0] : never;
+
 export type StarlightUserConfigWithPlugins = StarlightUserConfig & {
 	/**
 	 * A list of plugins to extend Starlight with.
@@ -273,7 +448,7 @@ export type StarlightUserConfigWithPlugins = StarlightUserConfig & {
 };
 
 export type StarlightPluginContext = Pick<
-	Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0],
+	AstroHookParameters<'astro:config:setup'>,
 	'command' | 'config' | 'isRestart' | 'logger'
 >;
 

package/utils/{route-data.ts → routing/data.ts}

@@ -1,39 +1,34 @@
-import type { MarkdownHeading } from 'astro';
+import type { APIContext, MarkdownHeading } from 'astro';
+import project from 'virtual:starlight/project-context';
 import config from 'virtual:starlight/user-config';
-import { generateToC, type TocItem } from './generateToC';
+import { generateToC } from '../generateToC';
 import { getNewestCommitDate } from 'virtual:starlight/git-info';
-import { getPrevNextLinks, getSidebar, type SidebarEntry } from './navigation';
-import { ensureTrailingSlash } from './path';
-import type { Route } from './routing';
-import { formatPath } from './format-path';
-import { useTranslations } from './translations';
-import { DeprecatedLabelsPropProxy } from './i18n';
+import { getPrevNextLinks, getSidebar } from '../navigation';
+import { ensureTrailingSlash } from '../path';
+import { getRouteBySlugParam, normalizeCollectionEntry } from '../routing';
+import type {
+	Route,
+	StarlightDocsCollectionEntry,
+	StarlightDocsEntry,
+	StarlightRouteData,
+} from './types';
+import { formatPath } from '../format-path';
+import { useTranslations } from '../translations';
+import { BuiltInDefaultLocale } from '../i18n';
+import { getEntry, render } from 'astro:content';
+import { getCollectionPathFromRoot } from '../collection';
 
 export interface PageProps extends Route {
 	headings: MarkdownHeading[];
 }
 
-export interface StarlightRouteData extends Route {
-	/** Title of the site. */
-	siteTitle: string;
-	/** URL or path used as the link when clicking on the site title. */
-	siteTitleHref: string;
-	/** Array of Markdown headings extracted from the current page. */
-	headings: MarkdownHeading[];
-	/** Site navigation sidebar entries for this page. */
-	sidebar: SidebarEntry[];
-	/** Whether or not the sidebar should be displayed on this page. */
-	hasSidebar: boolean;
-	/** Links to the previous and next page in the sidebar if enabled. */
-	pagination: ReturnType<typeof getPrevNextLinks>;
-	/** Table of contents for this page if enabled. */
-	toc: { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined;
-	/** JS Date object representing when this page was last updated if enabled. */
-	lastUpdated: Date | undefined;
-	/** URL object for the address where this page can be edited if enabled. */
-	editUrl: URL | undefined;
-	/** @deprecated Use `Astro.locals.t()` instead. */
-	labels: Record<string, never>;
+export async function useRouteData(context: APIContext): Promise<StarlightRouteData> {
+	const route =
+		('slug' in context.params && getRouteBySlugParam(context.params.slug)) ||
+		(await get404Route(context.locals));
+	const { Content, headings } = await render(route.entry);
+	const routeData = generateRouteData({ props: { ...route, headings }, url: context.url });
+	return { ...routeData, Content };
 }
 
 export function generateRouteData({
@@ -56,7 +51,6 @@ export function generateRouteData({
 		toc: getToC(props),
 		lastUpdated: getLastUpdated(props),
 		editUrl: getEditUrl(props),
-		labels: DeprecatedLabelsPropProxy,
 	};
 }
 
@@ -121,3 +115,35 @@ export function getSiteTitle(lang: string): string {
 export function getSiteTitleHref(locale: string | undefined): string {
 	return formatPath(locale || '/');
 }
+
+/** Generate a route object for Starlight’s 404 page. */
+async function get404Route(locals: App.Locals): Promise<Route> {
+	const { lang = BuiltInDefaultLocale.lang, dir = BuiltInDefaultLocale.dir } =
+		config.defaultLocale || {};
+	let locale = config.defaultLocale?.locale;
+	if (locale === 'root') locale = undefined;
+
+	const entryMeta = { dir, lang, locale };
+
+	const fallbackEntry: StarlightDocsEntry = {
+		slug: '404',
+		id: '404',
+		body: '',
+		collection: 'docs',
+		data: {
+			title: '404',
+			template: 'splash',
+			editUrl: false,
+			head: [],
+			hero: { tagline: locals.t('404.text'), actions: [] },
+			pagefind: false,
+			sidebar: { hidden: false, attrs: {} },
+			draft: false,
+		},
+		filePath: `${getCollectionPathFromRoot('docs', project)}/404.md`,
+	};
+
+	const userEntry = (await getEntry('docs', '404')) as StarlightDocsCollectionEntry;
+	const entry = userEntry ? normalizeCollectionEntry(userEntry) : fallbackEntry;
+	return { ...entryMeta, entryMeta, entry, id: entry.id, slug: entry.slug };
+}