@astrojs/starlight 0.31.1 → 0.32.1

package/components/ThemeSelect.astro

@@ -1,6 +1,5 @@
 ---
 import Select from './Select.astro';
-import type { Props } from '../props';
 ---
 
 <starlight-theme-select>

package/components/TwoColumnContent.astro

@@ -1,10 +1,6 @@
----
-import type { Props } from '../props';
----
-
 <div class="lg:sl-flex">
 	{
-		Astro.props.toc && (
+		Astro.locals.starlightRoute.toc && (
 			<aside class="right-sidebar-container print:hidden">
 				<div class="right-sidebar">
 					<slot name="right-sidebar" />

package/index.ts

@@ -18,7 +18,6 @@ import { starlightExpressiveCode } from './integrations/expressive-code/index';
 import { starlightSitemap } from './integrations/sitemap';
 import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
 import { rehypeRtlCodeSupport } from './integrations/code-rtl-support';
-import { createTranslationSystemFromFs } from './utils/translations-fs';
 import {
 	injectPluginTranslationsTypes,
 	runPlugins,
@@ -65,16 +64,10 @@ export default function StarlightIntegration(
 					config.i18n
 				);
 
-				const integrations = pluginResult.integrations;
+				const { integrations, useTranslations, absolutePathToLang } = pluginResult;
 				pluginTranslations = pluginResult.pluginTranslations;
 				userConfig = starlightConfig;
 
-				const useTranslations = createTranslationSystemFromFs(
-					starlightConfig,
-					config,
-					pluginTranslations
-				);
-
 				addMiddleware({ entrypoint: '@astrojs/starlight/locals', order: 'pre' });
 
 				if (!starlightConfig.disable404Route) {
@@ -127,7 +120,12 @@ export default function StarlightIntegration(
 					},
 					markdown: {
 						remarkPlugins: [
-							...starlightAsides({ starlightConfig, astroConfig: config, useTranslations }),
+							...starlightAsides({
+								starlightConfig,
+								astroConfig: config,
+								useTranslations,
+								absolutePathToLang,
+							}),
 						],
 						rehypePlugins: [rehypeRtlCodeSupport()],
 						shikiConfig:

package/integrations/asides.ts

@@ -14,15 +14,13 @@ import { toString } from 'mdast-util-to-string';
 import remarkDirective from 'remark-directive';
 import type { Plugin, Transformer } from 'unified';
 import { visit } from 'unist-util-visit';
-import type { StarlightConfig } from '../types';
-import type { createTranslationSystemFromFs } from '../utils/translations-fs';
-import { pathToLocale } from './shared/pathToLocale';
-import { localeToLang } from './shared/localeToLang';
+import type { HookParameters, StarlightConfig } from '../types';
 
 interface AsidesOptions {
 	starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales'>;
 	astroConfig: { root: AstroConfig['root']; srcDir: AstroConfig['srcDir'] };
-	useTranslations: ReturnType<typeof createTranslationSystemFromFs>;
+	useTranslations: HookParameters<'config:setup'>['useTranslations'];
+	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang'];
 }
 
 /** Hacky function that generates an mdast HTML tree ready for conversion to HTML by rehype. */
@@ -151,8 +149,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 	};
 
 	const transformer: Transformer<Root> = (tree, file) => {
-		const locale = pathToLocale(file.history[0], options);
-		const lang = localeToLang(options.starlightConfig, locale);
+		const lang = options.absolutePathToLang(file.path);
 		const t = options.useTranslations(lang);
 		visit(tree, (node, index, parent) => {
 			if (!parent || index === undefined || !isNodeDirective(node)) {

package/integrations/expressive-code/index.ts

@@ -5,10 +5,10 @@ import {
 } from 'astro-expressive-code';
 import { addClassName } from 'astro-expressive-code/hast';
 import type { AstroIntegration } from 'astro';
-import type { StarlightConfig } from '../../types';
-import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
-import { pathToLocale } from '../shared/pathToLocale';
+import type { HookParameters, StarlightConfig } from '../../types';
+import { absolutePathToLang } from '../shared/absolutePathToLang';
 import { slugToLocale } from '../shared/slugToLocale';
+import { localeToLang } from '../shared/localeToLang';
 import {
 	applyStarlightUiThemeColors,
 	preprocessThemes,
@@ -64,7 +64,7 @@ export type StarlightExpressiveCodeOptions = Omit<AstroExpressiveCodeOptions, 't
 
 type StarlightEcIntegrationOptions = {
 	starlightConfig: StarlightConfig;
-	useTranslations?: ReturnType<typeof createTranslationSystemFromFs> | undefined;
+	useTranslations: HookParameters<'config:setup'>['useTranslations'];
 };
 
 /**
@@ -110,8 +110,8 @@ export function getStarlightEcConfigPreprocessor({
 			},
 		});
 
-		// Add Expressive Code UI translations (if any) for all defined locales
-		if (useTranslations) addTranslations(starlightConfig, useTranslations);
+		// Add Expressive Code UI translations for all defined locales
+		addTranslations(starlightConfig, useTranslations);
 
 		return {
 			themes,
@@ -153,10 +153,15 @@ export function getStarlightEcConfigPreprocessor({
 				},
 				...otherStyleOverrides,
 			},
-			getBlockLocale: ({ file }) =>
-				file.url
-					? slugToLocale(file.url.pathname.slice(1), starlightConfig)
-					: pathToLocale(file.path, { starlightConfig, astroConfig }),
+			getBlockLocale: ({ file }) => {
+				if (file.url) {
+					const locale = slugToLocale(file.url.pathname.slice(1), starlightConfig);
+					return localeToLang(starlightConfig, locale);
+				}
+				// Note that EC cannot use the `absolutePathToLang` helper passed down to plugins as this callback
+				// is also called in the context of the `<Code>` component.
+				return absolutePathToLang(file.path, { starlightConfig, astroConfig });
+			},
 			plugins,
 			...rest,
 		};

package/integrations/shared/{pathToLocale.ts → absolutePathToLang.ts}

@@ -1,11 +1,12 @@
 import type { AstroConfig } from 'astro';
 import type { StarlightConfig } from '../../types';
+import { localeToLang } from './localeToLang';
 import { getCollectionPath } from '../../utils/collection';
 import { slugToLocale } from './slugToLocale';
 
-/** Get current locale from the full file path. */
-export function pathToLocale(
-	path: string | undefined,
+/** Get current language from an absolute file path. */
+export function absolutePathToLang(
+	path: string,
 	{
 		starlightConfig,
 		astroConfig,
@@ -13,7 +14,7 @@ export function pathToLocale(
 		starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales'>;
 		astroConfig: { root: AstroConfig['root']; srcDir: AstroConfig['srcDir'] };
 	}
-): string | undefined {
+): string {
 	const docsPath = getCollectionPath('docs', astroConfig.srcDir);
 	// Format path to unix style path.
 	path = path?.replace(/\\/g, '/');
@@ -23,5 +24,6 @@ export function pathToLocale(
 	// Strip docs path leaving only content collection file ID.
 	// Example: /Users/houston/repo/src/content/docs/en/guide.md => en/guide.md
 	const slug = path?.replace(docsPath, '');
-	return slugToLocale(slug, starlightConfig);
+	const locale = slugToLocale(slug, starlightConfig);
+	return localeToLang(starlightConfig, locale);
 }

package/integrations/virtual-user-config.ts

@@ -100,6 +100,33 @@ export function vitePluginStarlightUserConfig(
 			} catch {}
 			export const collections = userCollections;`,
 		'virtual:starlight/plugin-translations': `export default ${JSON.stringify(pluginTranslations)}`,
+		/**
+		 * Exports an array of route middleware functions.
+		 * For example, might generate a module that looks like:
+		 *
+		 * ```js
+		 * import { onRequest as routeMiddleware0 } from "/users/houston/docs/src/middleware";
+		 * import { onRequest as routeMiddleware1 } from "@houston-inc/plugin/middleware";
+		 *
+		 * export const routeMiddleware = [
+		 * 	routeMiddleware0,
+		 * 	routeMiddleware1,
+		 * ];
+		 * ```
+		 */
+		'virtual:starlight/route-middleware':
+			opts.routeMiddleware
+				.reduce(
+					([imports, entries], id, index) => {
+						const importName = `routeMiddleware${index}`;
+						imports += `import { onRequest as ${importName} } from ${resolveId(id)};\n`;
+						entries += `\t${importName},\n`;
+						return [imports, entries] as [string, string];
+					},
+					['', 'export const routeMiddleware = [\n'] as [string, string]
+				)
+				.join('\n') + '];',
+		/** Map of modules exporting Starlight’s templating components. */
 		'virtual:starlight/pagefind-config': `export const pagefindUserConfig = ${JSON.stringify(opts.pagefind || {})}`,
 		...virtualComponentModules,
 	} satisfies Record<string, string>;

package/locals.d.ts

@@ -12,6 +12,32 @@ declare namespace StarlightApp {
  */
 declare namespace App {
 	interface Locals {
+		/**
+		 * Starlight’s localization API, powered by i18next.
+		 *
+		 * @see https://starlight.astro.build/guides/i18n/#using-ui-translations
+		 *
+		 * @example
+		 * // Render a UI string for the current locale.
+		 * <p>{Astro.locals.t('404.text')}</p>
+		 */
 		t: import('./utils/createTranslationSystem').I18nT;
+
+		/**
+		 * Starlight’s data for the current route.
+		 *
+		 * @see https://starlight.astro.build/guides/route-data/
+		 *
+		 * @throws Will throw an error if accessed on non-Starlight routes.
+		 *
+		 * @example
+		 * // Render the title for the current page
+		 * <h1>{Astro.locals.starlightRoute.entry.data.title}</h1>
+		 *
+		 * @example
+		 * // Check if the current page should render the sidebar
+		 * const { hasSidebar } = Astro.locals.starlightRoute;
+		 */
+		starlightRoute: import('./utils/routing/types').StarlightRouteData;
 	}
 }

package/locals.ts

@@ -1,8 +1,43 @@
+import type { APIContext } from 'astro';
+import { AstroError } from 'astro/errors';
 import { defineMiddleware } from 'astro:middleware';
+import type { StarlightRouteData } from './route-data';
 import { useTranslations } from './utils/translations';
 
-export const onRequest = defineMiddleware((context, next) => {
+export const onRequest = defineMiddleware(async (context, next) => {
 	context.locals.t = useTranslations(context.currentLocale);
-
+	initializeStarlightRoute(context);
 	return next();
 });
+
+/**
+ * Sets up a `starlightRoute` property on locals. Initially, this will throw an error if accessed.
+ * When rendering, Starlight’s routes set `starlightRoute` with the resolved route data object for
+ * the current page.
+ *
+ * This ensures Starlight components can easily access `starlightRoute` without needing type guards,
+ * we can throw a helpful message if `starlightRoute` is accessed on non-Starlight pages, and we
+ * avoid generating route data in this middleware which also runs for non-Starlight route.
+ */
+export function initializeStarlightRoute(context: APIContext) {
+	if ('starlightRoute' in context.locals) return;
+	const state: { routeData: StarlightRouteData | undefined } = { routeData: undefined };
+	Object.defineProperty(context.locals, 'starlightRoute', {
+		get() {
+			if (!state.routeData) {
+				throw new AstroError(
+					'`locals.starlightRoute` is not defined',
+					'This usually means a component that accesses `locals.starlightRoute` is being rendered outside of a Starlight page, which is not supported.\n\n' +
+						'If this is a component you authored, you can do one of the following:\n\n' +
+						'1. Avoid using this component in non-Starlight pages.\n' +
+						'2. Wrap the code that reads `locals.starlightRoute` in a  `try/catch` block and handle the cases where `starlightRoute` is not available.\n\n' +
+						'If this is a Starlight built-in or third-party component, you may need to report a bug or avoid this use of the component.'
+				);
+			}
+			return state.routeData;
+		},
+		set(routeData: StarlightRouteData) {
+			state.routeData = routeData;
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.31.1",
+  "version": "0.32.1",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -159,6 +159,7 @@
     "./props": "./props.ts",
     "./schema": "./schema.ts",
     "./loaders": "./loaders.ts",
+    "./route-data": "./route-data.ts",
     "./types": "./types.ts",
     "./expressive-code": {
       "types": "./expressive-code.d.ts",
@@ -178,10 +179,10 @@
     "@astrojs/markdown-remark": "^6.0.1",
     "@playwright/test": "^1.45.0",
     "@types/node": "^18.16.19",
-    "@vitest/coverage-v8": "^3.0.1",
+    "@vitest/coverage-v8": "^3.0.5",
     "astro": "^5.1.5",
     "linkedom": "^0.18.4",
-    "vitest": "^3.0.1"
+    "vitest": "^3.0.5"
   },
   "dependencies": {
     "@astrojs/mdx": "^4.0.5",
@@ -198,6 +199,7 @@
     "hastscript": "^9.0.0",
     "i18next": "^23.11.5",
     "js-yaml": "^4.1.0",
+    "klona": "^2.0.6",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
     "mdast-util-to-string": "^4.0.0",

package/props.ts

@@ -1,2 +1,14 @@
-export type { StarlightRouteData as Props } from './utils/route-data';
+import type { StarlightRouteData } from './utils/routing/types';
 export type { StarlightPageProps } from './utils/starlight-page';
+
+/**
+ * @deprecated The `Props` type is deprecated. If updating an override to use
+ * `Astro.locals.starlightRoute` instead of `Astro.props`, import the new `StarlightRouteData`
+ * type instead:
+ * ```astro
+ * ---
+ * import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+ * ---
+ * ```
+ */
+export type Props = StarlightRouteData;

package/route-data.ts

@@ -0,0 +1,11 @@
+import type { APIContext } from 'astro';
+export type { StarlightRouteData } from './utils/routing/types';
+
+export type RouteMiddlewareHandler = (
+	context: APIContext,
+	next: () => Promise<void>
+) => void | Promise<void>;
+
+export function defineRouteMiddleware(fn: RouteMiddlewareHandler) {
+	return fn;
+}

package/routes/common.astro

@@ -1,17 +1,11 @@
 ---
-import { render } from 'astro:content';
-import { generateRouteData } from '../utils/route-data';
-import type { Route } from '../utils/routing';
 import Page from '../components/Page.astro';
+import { useRouteData } from '../utils/routing/data';
+import { attachRouteDataAndRunMiddleware } from '../utils/routing/middleware';
 
-export type Props = {
-	route: Route;
-};
+await attachRouteDataAndRunMiddleware(Astro, await useRouteData(Astro));
 
-const { route } = Astro.props;
-
-const { Content, headings } = await render(route.entry);
-const routeData = generateRouteData({ props: { ...route, headings }, url: Astro.url });
+const { Content, entry } = Astro.locals.starlightRoute;
 ---
 
-<Page {...routeData}><Content frontmatter={route.entry.data} /></Page>
+<Page>{Content && <Content frontmatter={entry.data} />}</Page>

package/routes/ssr/index.astro

@@ -11,4 +11,4 @@ if (route === undefined) {
 }
 ---
 
-<CommonPage route={route} />
+<CommonPage />

package/routes/static/404.astro

@@ -1,47 +1,7 @@
 ---
-import { getEntry } from 'astro:content';
-import project from 'virtual:starlight/project-context';
-import config from 'virtual:starlight/user-config';
-import { getCollectionPathFromRoot } from '../../utils/collection';
-import {
-	normalizeCollectionEntry,
-	type Route,
-	type StarlightDocsCollectionEntry,
-	type StarlightDocsEntry,
-} from '../../utils/routing';
-import { BuiltInDefaultLocale } from '../../utils/i18n';
 import CommonPage from '../common.astro';
 
 export const prerender = true;
-
-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: Astro.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;
-const route: Route = { ...entryMeta, entryMeta, entry, id: entry.id, slug: entry.slug };
 ---
 
-<CommonPage {route} />
+<CommonPage />

package/routes/static/index.astro

@@ -1,5 +1,4 @@
 ---
-import type { InferGetStaticPropsType } from 'astro';
 import { paths } from '../../utils/routing';
 import CommonPage from '../common.astro';
 
@@ -8,8 +7,6 @@ export const prerender = true;
 export async function getStaticPaths() {
 	return paths;
 }
-
-type Props = InferGetStaticPropsType<typeof getStaticPaths>;
 ---
 
-<CommonPage route={Astro.props} />
+<CommonPage />

package/schemas/pagefind.ts

@@ -1,43 +1,107 @@
 import { z } from 'astro/zod';
 
+const indexWeightSchema = z.number().nonnegative().optional();
+const pagefindRankingWeightsSchema = z.object({
+	/**
+	 * Set Pagefind’s `pageLength` ranking option.
+	 *
+	 * The default value is `0.1` and values must be in the range `0` to `1`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-page-length
+	 */
+	pageLength: z.number().min(0).max(1).default(0.1),
+	/**
+	 * Set Pagefind’s `termFrequency` ranking option.
+	 *
+	 * The default value is `0.1` and values must be in the range `0` to `1`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-term-frequency
+	 */
+	termFrequency: z.number().min(0).max(1).default(0.1),
+	/**
+	 * Set Pagefind’s `termSaturation` ranking option.
+	 *
+	 * The default value is `2` and values must be in the range `0` to `2`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-term-saturation
+	 */
+	termSaturation: z.number().min(0).max(2).default(2),
+	/**
+	 * Set Pagefind’s `termSimilarity` ranking option.
+	 *
+	 * The default value is `9` and values must be greater than or equal to `0`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-term-similarity
+	 */
+	termSimilarity: z.number().min(0).default(9),
+});
+const pagefindIndexOptionsSchema = z.object({
+	/**
+	 * Overrides the URL path that Pagefind uses to load its search bundle
+	 */
+	basePath: z.string().optional(),
+	/**
+	 * Appends the given baseURL to all search results. May be a path, or a full domain
+	 */
+	baseUrl: z.string().optional(),
+	/**
+	 * Multiply all rankings for this index by the given weight.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#changing-the-weighting-of-individual-indexes
+	 */
+	indexWeight: indexWeightSchema,
+	/**
+	 * Apply this filter configuration to all search results from this index.
+	 *
+	 * Only applies in multisite setups.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#filtering-results-by-index
+	 */
+	mergeFilter: z.record(z.string(), z.string().or(z.array(z.string()).nonempty())).optional(),
+	/**
+	 * Language of this index.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#merging-a-specific-language-index
+	 */
+	language: z.string().optional(),
+	/**
+	 * Configure how search result rankings are calculated by Pagefind.
+	 */
+	ranking: pagefindRankingWeightsSchema.optional(),
+});
+
 const pagefindSchema = z.object({
+	/**
+	 * Configure how search results from the current website are weighted by Pagefind
+	 * compared to results from other sites when using the `mergeIndex` option.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#changing-the-weighting-of-individual-indexes
+	 */
+	indexWeight: indexWeightSchema,
 	/** Configure how search result rankings are calculated by Pagefind. */
-	ranking: z
-		.object({
-			/**
-			 * Set Pagefind’s `pageLength` ranking option.
-			 *
-			 * The default value is `0.1` and values must be in the range `0` to `1`.
-			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-page-length
-			 */
-			pageLength: z.number().min(0).max(1).default(0.1),
-			/**
-			 * Set Pagefind’s `termFrequency` ranking option.
-			 *
-			 * The default value is `0.1` and values must be in the range `0` to `1`.
-			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-term-frequency
-			 */
-			termFrequency: z.number().min(0).max(1).default(0.1),
-			/**
-			 * Set Pagefind’s `termSaturation` ranking option.
-			 *
-			 * The default value is `2` and values must be in the range `0` to `2`.
-			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-term-saturation
-			 */
-			termSaturation: z.number().min(0).max(2).default(2),
+	ranking: pagefindRankingWeightsSchema.default({}),
+	/**
+	 * Configure how search indexes from different sites are merged by Pagefind.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#searching-additional-sites-from-pagefind-ui
+	 */
+	mergeIndex: z
+		.array(
 			/**
-			 * Set Pagefind’s `termSimilarity` ranking option.
-			 *
-			 * The default value is `9` and values must be greater than or equal to `0`.
+			 * Each entry of this array represents a `PagefindIndexOptions` from pagefind.
 			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-term-similarity
+			 * @see https://github.com/CloudCannon/pagefind/blob/v1.3.0/pagefind_web_js/lib/coupled_search.ts#L549
 			 */
-			termSimilarity: z.number().min(0).default(9),
-		})
-		.default({}),
+			pagefindIndexOptionsSchema.extend({
+				/**
+				 * Set Pagefind’s `bundlePath` mergeIndex option.
+				 *
+				 * @see https://pagefind.app/docs/multisite/#searching-additional-sites-from-pagefind-ui
+				 */
+				bundlePath: z.string(),
+			})
+		)
+		.optional(),
 });
 
 export const PagefindConfigSchema = () => pagefindSchema;

package/types.ts

@@ -2,5 +2,6 @@ export type { StarlightConfig } from './utils/user-config';
 export type {
 	StarlightPlugin,
 	StarlightUserConfigWithPlugins as StarlightUserConfig,
+	HookParameters,
 } from './utils/plugins';
 export type { StarlightIcon } from './components/Icons';

package/utils/i18n.ts

@@ -2,26 +2,6 @@ import type { AstroConfig } from 'astro';
 import { AstroError } from 'astro/errors';
 import type { StarlightConfig } from './user-config';
 
-/**
- * A proxy object that throws an error when a user tries to access the deprecated `labels` prop in
- * a component override.
- *
- * @todo Remove in a future release once people have updated — no later than v1.
- */
-export const DeprecatedLabelsPropProxy = new Proxy<Record<string, never>>(
-	{},
-	{
-		get(_, key) {
-			const label = String(key);
-			throw new AstroError(
-				`The \`labels\` prop in component overrides has been removed.`,
-				`Replace \`Astro.props.labels["${label}"]\` with \`Astro.locals.t("${label}")\` instead.\n` +
-					'For more information see https://starlight.astro.build/guides/i18n/#using-ui-translations'
-			);
-		},
-	}
-);
-
 /**
  * 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.