@astrojs/starlight 0.31.1 → 0.32.1

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 };
+}

package/utils/{routing.ts → routing/index.ts}

@@ -1,55 +1,17 @@
 import type { GetStaticPathsItem } from 'astro';
-import { type CollectionEntry, getCollection } from 'astro:content';
+import { getCollection } from 'astro:content';
 import config from 'virtual:starlight/user-config';
 import project from 'virtual:starlight/project-context';
-import { getCollectionPathFromRoot } from './collection';
-import {
-	type LocaleData,
-	localizedId,
-	localizedSlug,
-	slugToLocaleData,
-	slugToParam,
-} from './slugs';
-import { validateLogoImports } from './validateLogoImports';
-import { BuiltInDefaultLocale } from './i18n';
+import { getCollectionPathFromRoot } from '../collection';
+import { localizedId, localizedSlug, slugToLocaleData, slugToParam } from '../slugs';
+import { validateLogoImports } from '../validateLogoImports';
+import { BuiltInDefaultLocale } from '../i18n';
+import type { Route, StarlightDocsCollectionEntry, StarlightDocsEntry } from './types';
 
 // Validate any user-provided logos imported correctly.
 // We do this here so all pages trigger it and at the top level so it runs just once.
 validateLogoImports();
 
-// 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;
-};
-
-export type StarlightDocsEntry = StarlightDocsCollectionEntry & {
-	filePath: string;
-	slug: string;
-};
-
-export interface Route extends LocaleData {
-	/** Content collection entry for the current page. Includes frontmatter at `data`. */
-	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. */
-	id: string;
-	/** True if this page is untranslated in the current language and using fallback content from the default locale. */
-	isFallback?: true;
-	[key: string]: unknown;
-}
-
 interface Path extends GetStaticPathsItem {
 	params: { slug: string | undefined };
 	props: Route;

package/utils/routing/middleware.ts

@@ -0,0 +1,81 @@
+import type { APIContext } from 'astro';
+import { klona } from 'klona/lite';
+import { routeMiddleware } from 'virtual:starlight/route-middleware';
+import type { StarlightRouteData } from './types';
+
+/**
+ * Adds a deep clone of the passed `routeData` object to locals and then runs middleware.
+ * @param context Astro context object
+ * @param routeData Initial route data object to attach.
+ */
+export async function attachRouteDataAndRunMiddleware(
+	context: APIContext,
+	routeData: StarlightRouteData
+) {
+	context.locals.starlightRoute = klona(routeData);
+	const runner = new MiddlewareRunner(context, routeMiddleware);
+	await runner.run();
+}
+
+type MiddlewareHandler<T> = (context: T, next: () => Promise<void>) => void | Promise<void>;
+
+/**
+ * A middleware function wrapper that only allows a single execution of the wrapped function.
+ * Subsequent calls to `run()` are no-ops.
+ */
+class MiddlewareRunnerStep<T> {
+	#callback: MiddlewareHandler<T> | null;
+	constructor(callback: MiddlewareHandler<T>) {
+		this.#callback = callback;
+	}
+	async run(context: T, next: () => Promise<void>): Promise<void> {
+		if (this.#callback) {
+			await this.#callback(context, next);
+			this.#callback = null;
+		}
+	}
+}
+
+/**
+ * Class that runs a stack of middleware handlers with an initial context object.
+ * Middleware functions can mutate properties of the `context` object, but cannot replace it.
+ *
+ * @example
+ * const context = { value: 10 };
+ * const timesTwo = async (ctx, next) => {
+ *   await next();
+ *   ctx.value *= 2;
+ * };
+ * const addFive = async (ctx) => {
+ *   ctx.value += 5;
+ * }
+ * const runner = new MiddlewareRunner(context, [timesTwo, addFive]);
+ * runner.run();
+ * console.log(context); // { value: 30 }
+ */
+class MiddlewareRunner<T> {
+	#context: T;
+	#steps: Array<MiddlewareRunnerStep<T>>;
+
+	constructor(
+		/** Context object passed as the first argument to each middleware function. */
+		context: T,
+		/** Array of middleware functions to run in sequence. */
+		stack: Array<MiddlewareHandler<T>> = []
+	) {
+		this.#context = context;
+		this.#steps = stack.map((callback) => new MiddlewareRunnerStep(callback));
+	}
+
+	async #stepThrough(steps: Array<MiddlewareRunnerStep<T>>) {
+		let currentStep: MiddlewareRunnerStep<T>;
+		while (steps.length > 0) {
+			[currentStep, ...steps] = steps as [MiddlewareRunnerStep<T>, ...MiddlewareRunnerStep<T>[]];
+			await currentStep.run(this.#context, async () => this.#stepThrough(steps));
+		}
+	}
+
+	async run() {
+		await this.#stepThrough(this.#steps);
+	}
+}

package/utils/routing/types.ts

@@ -0,0 +1,96 @@
+import type { MarkdownHeading } from 'astro';
+import type { CollectionEntry, RenderResult } from 'astro:content';
+import type { TocItem } from '../generateToC';
+import type { LinkHTMLAttributes } from '../../schemas/sidebar';
+import type { Badge } from '../../schemas/badge';
+
+export interface LocaleData {
+	/** Writing direction. */
+	dir: 'ltr' | 'rtl';
+	/** BCP-47 language tag. */
+	lang: string;
+	/** The base path at which a language is served. `undefined` for root locale slugs. */
+	locale: string | undefined;
+}
+
+export interface SidebarLink {
+	type: 'link';
+	label: string;
+	href: string;
+	isCurrent: boolean;
+	badge: Badge | undefined;
+	attrs: LinkHTMLAttributes;
+}
+
+export interface SidebarGroup {
+	type: 'group';
+	label: string;
+	entries: (SidebarLink | SidebarGroup)[];
+	collapsed: boolean;
+	badge: Badge | undefined;
+}
+
+export type SidebarEntry = SidebarLink | SidebarGroup;
+
+export interface PaginationLinks {
+	/** Link to previous page in the sidebar. */
+	prev: SidebarLink | undefined;
+	/** Link to next page in the sidebar. */
+	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;
+};
+
+export type StarlightDocsEntry = StarlightDocsCollectionEntry & {
+	filePath: string;
+	slug: string;
+};
+
+export interface Route extends LocaleData {
+	/** Content collection entry for the current page. Includes frontmatter at `data`. */
+	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. */
+	id: string;
+	/** True if this page is untranslated in the current language and using fallback content from the default locale. */
+	isFallback?: true;
+	[key: string]: unknown;
+}
+
+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: PaginationLinks;
+	/** 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;
+	/** An Astro component to render the current page’s content if this route is a Markdown page. */
+	Content?: RenderResult['Content'];
+}

package/utils/slugs.ts

@@ -1,16 +1,8 @@
 import config from 'virtual:starlight/user-config';
+import { slugToLocale as getLocaleFromSlug } from '../integrations/shared/slugToLocale';
 import { BuiltInDefaultLocale } from './i18n';
 import { stripTrailingSlash } from './path';
-import { slugToLocale as getLocaleFromSlug } from '../integrations/shared/slugToLocale';
-
-export interface LocaleData {
-	/** Writing direction. */
-	dir: 'ltr' | 'rtl';
-	/** BCP-47 language tag. */
-	lang: string;
-	/** The base path at which a language is served. `undefined` for root locale slugs. */
-	locale: string | undefined;
-}
+import type { LocaleData } from './routing/types';
 
 /**
  * Get the “locale” of a slug. This is the base path at which a language is served.

package/utils/starlight-page.ts

@@ -5,19 +5,12 @@ import config from 'virtual:starlight/user-config';
 import { getCollectionPathFromRoot } from './collection';
 import { parseWithFriendlyErrors, parseAsyncWithFriendlyErrors } from './error-map';
 import { stripLeadingAndTrailingSlashes } from './path';
-import {
-	getSiteTitle,
-	getSiteTitleHref,
-	getToC,
-	type PageProps,
-	type StarlightRouteData,
-} from './route-data';
-import type { StarlightDocsEntry } from './routing';
+import { getSiteTitle, getSiteTitleHref, getToC, type PageProps } from './routing/data';
+import type { StarlightDocsEntry, StarlightRouteData } from './routing/types';
 import { slugToLocaleData, urlToSlug } from './slugs';
 import { getPrevNextLinks, getSidebar, getSidebarFromConfig } from './navigation';
 import { docsSchema } from '../schema';
 import type { Prettify, RemoveIndexSignature } from './types';
-import { DeprecatedLabelsPropProxy } from './i18n';
 import { SidebarItemSchema } from '../schemas/sidebar';
 import type { StarlightConfig, StarlightUserConfig } from './user-config';
 
@@ -153,7 +146,6 @@ export async function generateStarlightPageRouteData({
 		entryMeta,
 		hasSidebar: props.hasSidebar ?? entry.data.template !== 'splash',
 		headings,
-		labels: DeprecatedLabelsPropProxy,
 		lastUpdated,
 		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
 		sidebar,

package/utils/user-config.ts

@@ -226,6 +226,14 @@ const UserConfigSchema = z.object({
 		.boolean()
 		.default(false)
 		.describe('Enable displaying a “Built with Starlight” link in your site’s footer.'),
+
+	/** Add middleware to process Starlight’s route data for each page. */
+	routeMiddleware: z
+		.string()
+		.transform((string) => [string])
+		.or(z.string().array())
+		.default([])
+		.describe('Add middleware to process Starlight’s route data for each page.'),
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict()

package/virtual-internal.d.ts

@@ -16,6 +16,10 @@ declare module 'virtual:starlight/collection-config' {
 	export const collections: import('astro:content').ContentConfig['collections'] | undefined;
 }
 
+declare module 'virtual:starlight/route-middleware' {
+	export const routeMiddleware: Array<import('./route-data').RouteMiddlewareHandler>;
+}
+
 declare module 'virtual:starlight/pagefind-config' {
 	export const pagefindUserConfig: Partial<
 		Extract<import('./types').StarlightConfig['pagefind'], object>