@astrojs/starlight 0.35.2 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @astrojs/starlight
 
+## 0.36.0
+
+### Minor Changes
+
+- [#3427](https://github.com/withastro/starlight/pull/3427) [`c3b2d0f`](https://github.com/withastro/starlight/commit/c3b2d0fc37bb9b7b6abc6c11b760a4114690ccd4) Thanks [@delucis](https://github.com/delucis)! - Fixes styling of labels that wrap across multiple lines in `<Tabs>` component
+
+  ⚠️ **Potentially breaking change:** Tab labels now have a narrower line-height and additional vertical padding. If you have custom CSS targetting the `<Tabs>` component, you may want to double check the visual appearance of your tabs when updating.
+
+  If you want to preserve the previous styling, you can add the following custom CSS to your site:
+
+  ```css
+  .tab > [role='tab'] {
+    line-height: var(--sl-line-height);
+    padding-block: 0;
+  }
+  ```
+
+- [#3380](https://github.com/withastro/starlight/pull/3380) [`3364af3`](https://github.com/withastro/starlight/commit/3364af31e535d62ee7b045e6d9cf97c7e58df981) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Makes head entry parsing stricter in Starlight config and content frontmatter.
+
+  **⚠️ Potentially breaking change:** Previously Starlight would accept a head entry for a `meta` tag defining some `content` which generates invalid HTML as `<meta>` is a void element which cannot have any child nodes. Now, it is an error to define a `meta` tag including some `content`.
+
+  If you see errors after updating, look for head entries in the Starlight configuration in the `astro.config.mjs` file or in the frontmatter of your content files that include a `content` property for a `meta` tag. To fix the error, move the `content` property to the `attrs` object with at least an additional attribute to identify the kind of metadata it represents:
+
+  ```diff
+  head: {
+    tag: 'meta',
+  - content: 'foo',
+    attrs: {
+      name: 'my-meta',
+  +   content: 'foo',
+    },
+  },
+  ```
+
+- [#3340](https://github.com/withastro/starlight/pull/3340) [`2018c31`](https://github.com/withastro/starlight/commit/2018c31b0f559d51478bfbf9f12cfba76b4e74fc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds missing vertical spacing between Markdown content and UI Framework components using [client directives](https://docs.astro.build/en/reference/directives-reference/#client-directives).
+
+  **⚠️ Potentially breaking change:** By default, Starlight applies some vertical spacing (`--sl-content-gap-y`) between Markdown content blocks. This change introduces similar spacing between Markdown content blocks and UI Framework components using client directives which was not present before.
+
+  If you were relying on the previous behavior, you can manually override the spacing by manually specifying the top margin on the component using [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles), e.g. by relying on a CSS class to target the component.
+
+  ```css
+  .my-custom-component {
+    margin-top: 0;
+  }
+  ```
+
+### Patch Changes
+
+- [#3423](https://github.com/withastro/starlight/pull/3423) [`a0d0670`](https://github.com/withastro/starlight/commit/a0d0670bce5827b90fd0102fa3517814367760e7) Thanks [@andersk](https://github.com/andersk)! - Fixes HTML validity in sidebar groups by ensuring `<summary>` is the first child of `<details>`
+
+## 0.35.3
+
+### Patch Changes
+
+- [#3416](https://github.com/withastro/starlight/pull/3416) [`fcc0633`](https://github.com/withastro/starlight/commit/fcc0633ab14fc602f5c540972446e22c79746042) Thanks [@randomguy-2650](https://github.com/randomguy-2650)! - Updates German UI translations to be more idiomatic.
+
+- [#1640](https://github.com/withastro/starlight/pull/1640) [`d1b3828`](https://github.com/withastro/starlight/commit/d1b3828cdfe8114884ab65049581e37624422ac4) Thanks [@hippotastic](https://github.com/hippotastic)! - Refactors various internal systems, improving code quality and maintainability.
+
+- [#3421](https://github.com/withastro/starlight/pull/3421) [`97e8103`](https://github.com/withastro/starlight/commit/97e8103c5793d583931575dbe17924ef88a5b6fd) Thanks [@andersk](https://github.com/andersk)! - Removes an invalid `value` attribute from the language and theme selectors
+
+- [#3422](https://github.com/withastro/starlight/pull/3422) [`9200fac`](https://github.com/withastro/starlight/commit/9200fac71ebe6e7bbbecee3d1893e744db01dc6e) Thanks [@andersk](https://github.com/andersk)! - Refactors collapsible sidebar sections and “on this page” dropdown to use `<span>` instead of `<div>`
+
 ## 0.35.2
 
 ### Patch Changes

package/components/LanguageSelect.astro

@@ -18,7 +18,6 @@ function localizedPathname(locale: string | undefined): string {
 			<Select
 				icon="translate"
 				label={Astro.locals.t('languageSelect.accessibleLabel')}
-				value={localizedPathname(Astro.locals.starlightRoute.locale)}
 				options={Object.entries(config.locales).map(([code, locale]) => ({
 					value: localizedPathname(code),
 					selected: code === Astro.locals.starlightRoute.locale,

package/components/MobileTableOfContents.astro

@@ -11,10 +11,10 @@ const { toc } = Astro.locals.starlightRoute;
 			<nav aria-labelledby="starlight__on-this-page--mobile">
 				<details id="starlight__mobile-toc">
 					<summary id="starlight__on-this-page--mobile" class="sl-flex">
-						<div class="toggle sl-flex">
+						<span class="toggle sl-flex">
 							{Astro.locals.t('tableOfContents.onThisPage')}
 							<Icon name={'right-caret'} class="caret" size="1rem" />
-						</div>
+						</span>
 						<span class="display-current" />
 					</summary>
 					<div class="dropdown">

package/components/Select.astro

@@ -3,7 +3,6 @@ import Icon from '../user-components/Icon.astro';
 
 interface Props {
 	label: string;
-	value: string;
 	icon: Parameters<typeof Icon>[0]['name'];
 	width?: string;
 	options: Array<{
@@ -26,7 +25,7 @@ interface Props {
 <label style={`--sl-select-width: ${Astro.props.width}`}>
 	<span class="sr-only">{Astro.props.label}</span>
 	<Icon name={Astro.props.icon} class="icon label-icon" />
-	<select value={Astro.props.value} autocomplete="off">
+	<select autocomplete="off">
 		{
 			Astro.props.options.map(({ value, selected, label }) => (
 				<option value={value} selected={selected} set:html={label} />

package/components/SidebarPersistState.ts

@@ -19,11 +19,11 @@ interface SidebarState {
  * and `hash` are read from the current page.
  */
 const getState = (): SidebarState => {
-	let open = [];
+	let open: SidebarState['open'] = [];
 	const hash = target?.dataset.hash || '';
 	try {
 		const rawStoredState = sessionStorage.getItem(storageKey);
-		const storedState = JSON.parse(rawStoredState || '{}');
+		const storedState = JSON.parse(rawStoredState || '{}') as SidebarState;
 		if (Array.isArray(storedState.open) && storedState.hash === hash) open = storedState.open;
 	} catch {}
 	return {

package/components/SidebarSublist.astro

@@ -37,9 +37,8 @@ const { sublist, nested } = Astro.props;
 					<details
 						open={flattenSidebar(entry.entries).some((i) => i.isCurrent) || !entry.collapsed}
 					>
-						<SidebarRestorePoint />
 						<summary>
-							<div class="group-label">
+							<span class="group-label">
 								<span class="large">{entry.label}</span>
 								{entry.badge && (
 									<Badge
@@ -48,9 +47,10 @@ const { sublist, nested } = Astro.props;
 										text={entry.badge.text}
 									/>
 								)}
-							</div>
+							</span>
 							<Icon name="right-caret" class="caret" size="1.25rem" />
 						</summary>
+						<SidebarRestorePoint />
 						<Astro.self sublist={entry.entries} nested />
 					</details>
 				)}

package/components/ThemeSelect.astro

@@ -7,7 +7,6 @@ import Select from './Select.astro';
 	<Select
 		icon="laptop"
 		label={Astro.locals.t('themeSelect.accessibleLabel')}
-		value="auto"
 		options={[
 			{ label: Astro.locals.t('themeSelect.dark'), selected: false, value: 'dark' },
 			{ label: Astro.locals.t('themeSelect.light'), selected: false, value: 'light' },

package/expressive-code.mjs

@@ -15,7 +15,9 @@
 
 export * from 'astro-expressive-code';
 
-// @ts-ignore - Types are provided by the separate `expressive-code.d.ts` file
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - Types are provided by the separate `expressive-code.d.ts` file and this may not be
+// a type error for some users running `tsc --noEmit` depending on their `tsconfig.json` settings.
 export function defineEcConfig(config) {
 	return config;
 }

package/integrations/asides-error.ts

@@ -3,7 +3,7 @@ import { AstroError } from 'astro/errors';
 export function throwInvalidAsideIconError(icon: string) {
 	throw new AstroError(
 		'Invalid aside icon',
-		`An aside custom icon must be set to the name of one of Starlight\’s built-in icons, but received \`${icon}\`.\n\n` +
+		`An aside custom icon must be set to the name of one of Starlight’s built-in icons, but received \`${icon}\`.\n\n` +
 			'See https://starlight.astro.build/reference/icons/#all-icons for a list of available icons.'
 	);
 }

package/integrations/asides.ts

@@ -29,22 +29,22 @@ interface AsidesOptions {
 }
 
 /** Hacky function that generates an mdast HTML tree ready for conversion to HTML by rehype. */
-function h(el: string, attrs: Properties = {}, children: any[] = []): P {
+function h(el: string, attrs: Properties = {}, children: unknown[] = []): P {
 	const { tagName, properties } = _h(el, attrs);
 	return {
 		type: 'paragraph',
 		data: { hName: tagName, hProperties: properties },
-		children,
+		children: children as P['children'],
 	};
 }
 
 /** Hacky function that generates an mdast SVG tree ready for conversion to HTML by rehype. */
-function s(el: string, attrs: Properties = {}, children: any[] = []): P {
+function s(el: string, attrs: Properties = {}, children: unknown[] = []): P {
 	const { tagName, properties } = _s(el, attrs);
 	return {
 		type: 'paragraph',
 		data: { hName: tagName, hProperties: properties },
-		children,
+		children: children as P['children'],
 	};
 }
 
@@ -93,14 +93,16 @@ function transformUnhandledDirective(
 }
 
 /** Hacky function that generates the children of an mdast SVG tree. */
-function makeSvgChildNodes(children: Result['children']): any[] {
+function makeSvgChildNodes(children: Result['children']): P[] {
 	const nodes: P[] = [];
 	for (const child of children) {
 		if (child.type !== 'element') continue;
 		nodes.push({
 			type: 'paragraph',
 			data: { hName: child.tagName, hProperties: child.properties },
-			children: makeSvgChildNodes(child.children),
+			// We are explicitly casting to the expected type here due to the hacky nature of this
+			// function which only works with SVG elements.
+			children: makeSvgChildNodes(child.children) as unknown as P['children'],
 		});
 	}
 	return nodes;

package/integrations/expressive-code/index.ts

@@ -102,7 +102,7 @@ export const starlightExpressiveCode = ({
 			? (starlightConfig.expressiveCode as AstroExpressiveCodeOptions)
 			: {};
 
-	let docsPath = getCollectionPosixPath('docs', astroConfig.srcDir);
+	const docsPath = getCollectionPosixPath('docs', astroConfig.srcDir);
 
 	return [
 		astroExpressiveCode({

package/integrations/expressive-code/translations.ts

@@ -3,10 +3,7 @@ import type { StarlightConfig } from '../../types';
 import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { localeToLang } from '../shared/localeToLang';
 
-export function addTranslations(
-	config: StarlightConfig,
-	useTranslations: ReturnType<typeof createTranslationSystemFromFs>
-) {
+export function addTranslations(config: StarlightConfig, useTranslations: UseTranslations) {
 	addTranslationsForLocale(config.defaultLocale.locale, config, useTranslations);
 	if (config.isMultilingual) {
 		for (const locale in config.locales) {
@@ -19,7 +16,7 @@ export function addTranslations(
 function addTranslationsForLocale(
 	locale: string | undefined,
 	config: StarlightConfig,
-	useTranslations: ReturnType<typeof createTranslationSystemFromFs>
+	useTranslations: UseTranslations
 ) {
 	const lang = localeToLang(config, locale);
 	const t = useTranslations(lang);
@@ -35,3 +32,5 @@ function addTranslationsForLocale(
 		pluginFramesTexts.overrideTexts(lang, { [ecId]: translation });
 	});
 }
+
+type UseTranslations = Awaited<ReturnType<typeof createTranslationSystemFromFs>>;

package/integrations/heading-links.ts

@@ -55,7 +55,7 @@ export default function rehypeAutolinkHeadings(
 				{
 					type: 'element',
 					tagName: 'a',
-					properties: { class: 'sl-anchor-link', href: '#' + node.properties.id },
+					properties: { class: 'sl-anchor-link', href: '#' + String(node.properties.id) },
 					children: [AnchorLinkIcon, h('span', { class: 'sr-only' }, accessibleLabel)],
 				}
 			);

package/integrations/sitemap.ts

@@ -7,7 +7,7 @@ export function getSitemapConfig(opts: StarlightConfig): SitemapOptions {
 		sitemapConfig.i18n = {
 			defaultLocale: opts.defaultLocale.locale || 'root',
 			locales: Object.fromEntries(
-				Object.entries(opts.locales).map(([locale, config]) => [locale, config?.lang!])
+				Object.entries(opts.locales).map(([locale, config]) => [locale, config!.lang!])
 			),
 		};
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.35.2",
+  "version": "0.36.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",

package/routes/common.astro

@@ -15,7 +15,7 @@ const route = await getRoute(Astro);
  */
 const renderResult = await render(route.entry);
 
-await attachRouteDataAndRunMiddleware(Astro, await useRouteData(Astro, route, renderResult));
+await attachRouteDataAndRunMiddleware(Astro, useRouteData(Astro, route, renderResult));
 
 const { Content, entry } = Astro.locals.starlightRoute;
 ---

package/schema.ts

@@ -30,7 +30,7 @@ const StarlightFrontmatterSchema = (context: SchemaContext) =>
 		editUrl: z.union([z.string().url(), z.boolean()]).optional().default(true),
 
 		/** Set custom `<head>` tags just for this page. */
-		head: HeadConfigSchema(),
+		head: HeadConfigSchema({ source: 'content' }),
 
 		/** Override global table of contents configuration for this page. */
 		tableOfContents: TableOfContentsSchema().optional(),
@@ -123,7 +123,7 @@ type BaseSchemaWithoutEffects =
 type BaseSchema = BaseSchemaWithoutEffects | z.ZodEffects<BaseSchemaWithoutEffects>;
 
 /** Type that extends Starlight’s default schema with an optional, user-defined schema. */
-type ExtendedSchema<T extends BaseSchema | never = never> = [T] extends [never]
+type ExtendedSchema<T extends BaseSchema = never> = [T] extends [never]
 	? DefaultSchema
 	: T extends BaseSchema
 		? z.ZodIntersection<DefaultSchema, T>
@@ -155,7 +155,7 @@ interface DocsSchemaOpts<T extends BaseSchema> {
 }
 
 /** Content collection schema for Starlight’s `docs` collection. */
-export function docsSchema<T extends BaseSchema | never = never>(
+export function docsSchema<T extends BaseSchema = never>(
 	...args: [DocsSchemaOpts<T>?]
 ): (context: SchemaContext) => ExtendedSchema<T> {
 	const [options = {}] = args;

package/schemas/expressiveCode.ts

@@ -4,7 +4,9 @@ import type { StarlightExpressiveCodeOptions } from '../integrations/expressive-
 export const ExpressiveCodeSchema = () =>
 	z
 		.union([
-			z.custom<StarlightExpressiveCodeOptions>((value) => typeof value === 'object' && value),
+			z.custom<StarlightExpressiveCodeOptions>(
+				(value) => typeof value === 'object' && (value as StarlightExpressiveCodeOptions)
+			),
 			z.boolean(),
 		])
 		.describe(

package/schemas/head.ts

@@ -1,16 +1,47 @@
 import { z } from 'astro/zod';
+import yaml from 'js-yaml';
 
-export const HeadConfigSchema = () =>
+export const HeadConfigSchema = ({
+	source,
+}: {
+	/**
+	 * Depending on the content being validated, either a user's config or a page's frontmatter,
+	 * different error messages will be shown.
+	 */
+	source: 'config' | 'content';
+}) =>
 	z
 		.array(
-			z.object({
-				/** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
-				tag: z.enum(['title', 'base', 'link', 'style', 'meta', 'script', 'noscript', 'template']),
-				/** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
-				attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).optional(),
-				/** Content to place inside the tag (optional). */
-				content: z.string().optional(),
-			})
+			z
+				.object({
+					/** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
+					tag: z.enum(['title', 'base', 'link', 'style', 'meta', 'script', 'noscript', 'template']),
+					/** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
+					attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).optional(),
+					/** Content to place inside the tag (optional). */
+					content: z.string().optional(),
+				})
+				.superRefine((config, ctx) => {
+					if (config.tag !== 'meta' || config.content === undefined) return;
+					const { content, ...rest } = config;
+					const correctTag = {
+						...rest,
+						attrs: { ...(config.attrs ?? { name: 'identifier' }), content: config.content },
+					};
+					const code =
+						source === 'config' ? JSON.stringify(correctTag, null, 2) : yaml.dump([correctTag]);
+					ctx.addIssue({
+						code: 'custom',
+						message:
+							`The \`head\` configuration includes a \`meta\` tag with \`content\` which is invalid HTML.\n` +
+							`You should instead use a \`content\` attribute ` +
+							(Object.keys(rest.attrs ?? {}).length === 0
+								? 'with an additional attribute such as `name`, `property`, or `http-equiv` to identify the kind of metadata it represents '
+								: '') +
+							`in the \`attrs\` object:\n\n` +
+							code,
+					});
+				})
 		)
 		.default([]);
 

package/schemas/i18n.ts

@@ -1,6 +1,6 @@
 import { z } from 'astro/zod';
 
-interface i18nSchemaOpts<T extends z.AnyZodObject = z.ZodObject<{}>> {
+interface i18nSchemaOpts<T extends z.AnyZodObject = z.SomeZodObject> {
 	/**
 	 * Extend Starlight’s i18n schema with additional fields.
 	 *
@@ -41,7 +41,7 @@ type ExtendedSchema<T extends z.AnyZodObject> = T extends z.AnyZodObject
 	: DefaultI18nSchema;
 
 /** Content collection schema for Starlight’s optional `i18n` collection. */
-export function i18nSchema<T extends z.AnyZodObject = z.ZodObject<{}>>({
+export function i18nSchema<T extends z.AnyZodObject = z.SomeZodObject>({
 	extend = z.object({}) as T,
 }: i18nSchemaOpts<T> = {}): ExtendedSchema<T> {
 	return defaultI18nSchema().merge(extend).passthrough() as ExtendedSchema<T>;

package/style/markdown.css

@@ -2,7 +2,15 @@
 	.sl-markdown-content
 		:not(a, strong, em, del, span, input, code, br)
 		+ :not(a, strong, em, del, span, input, code, br, :where(.not-content *)) {
-		margin-top: 1rem;
+		margin-top: var(--sl-content-gap-y);
+	}
+
+	/* Vertical spacing between Markdown content blocks and UI Framework components using client directives. */
+	.sl-markdown-content
+		:not(a, strong, em, del, span, input, code, br)
+		+ :is(astro-island, astro-slot)
+		> :not(a, strong, em, del, span, input, code, br, :where(.not-content *)):first-child {
+		margin-top: var(--sl-content-gap-y);
 	}
 
 	/* Headings after non-headings have more spacing. */

package/style/props.css

@@ -101,6 +101,7 @@
 		--sl-sidebar-pad-x: 1rem;
 		--sl-content-width: 45rem;
 		--sl-content-pad-x: 1rem;
+		--sl-content-gap-y: 1rem;
 		--sl-main-pad: 0 0 3vh 0;
 		--sl-menu-button-size: 2rem;
 		--sl-nav-gap: var(--sl-content-pad-x);

package/translations/de.json

@@ -15,7 +15,7 @@
   "tableOfContents.overview": "Überblick",
   "i18n.untranslatedContent": "Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.",
   "page.editLink": "Seite bearbeiten",
-  "page.lastUpdated": "Zuletzt bearbeitet:",
+  "page.lastUpdated": "Zuletzt aktualisiert:",
   "page.previousLink": "Vorherige Seite",
   "page.nextLink": "Nächste Seite",
   "page.draft": "Dieser Inhalt ist ein Entwurf und wird nicht in den Produktions-Builds enthalten sein.",

package/user-components/Tabs.astro

@@ -115,13 +115,15 @@ if (isSynced) {
 		}
 
 		.tab {
+			display: flex;
 			margin-bottom: -2px;
 		}
 		.tab > [role='tab'] {
 			display: flex;
 			align-items: center;
 			gap: 0.5rem;
-			padding: 0 1.25rem;
+			line-height: var(--sl-line-height-headings);
+			padding: 0.275rem 1.25rem;
 			text-decoration: none;
 			border-bottom: 2px solid var(--sl-color-gray-5);
 			color: var(--sl-color-gray-3);

package/utils/collection.ts

@@ -1,5 +1,4 @@
-const collectionNames = ['docs', 'i18n'] as const;
-export type StarlightCollection = (typeof collectionNames)[number];
+export type StarlightCollection = 'docs' | 'i18n';
 
 /**
  * We still rely on the content collection folder structure to be fixed for now:

package/utils/createTranslationSystem.ts

@@ -12,7 +12,7 @@ import type { UserI18nKeys, UserI18nSchema } from './translations';
  */
 export const I18nextNamespace = 'starlight' as const;
 
-export function createTranslationSystem<T extends i18nSchemaOutput>(
+export async function createTranslationSystem<T extends i18nSchemaOutput>(
 	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>,
 	userTranslations: Record<string, T>,
 	pluginTranslations: Record<string, T> = {}
@@ -42,7 +42,7 @@ export function createTranslationSystem<T extends i18nSchemaOutput>(
 	}
 
 	const i18n = i18next.createInstance();
-	i18n.init({
+	await i18n.init({
 		resources: translations,
 		fallbackLng:
 			config.defaultLocale.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang,
@@ -72,7 +72,7 @@ export function createTranslationSystem<T extends i18nSchemaOutput>(
 		lang ??= config.defaultLocale?.lang || BuiltInDefaultLocale.lang;
 
 		const t = i18n.getFixedT(lang, I18nextNamespace) as I18nT;
-		t.all = () => i18n.getResourceBundle(lang, I18nextNamespace);
+		t.all = () => i18n.getResourceBundle(lang, I18nextNamespace) as ReturnType<I18nT['all']>;
 		t.exists = (key, options) => i18n.exists(key, { lng: lang, ns: I18nextNamespace, ...options });
 		t.dir = (dirLang = lang) => i18n.dir(dirLang);
 

package/utils/error-map.ts

@@ -25,7 +25,7 @@ export function parseWithFriendlyErrors<T extends z.Schema>(
 	input: z.input<T>,
 	message: string
 ): z.output<T> {
-	return processParsedData(schema.safeParse(input, { errorMap }), message);
+	return processParsedData<T>(schema.safeParse(input, { errorMap }), message);
 }
 
 /**
@@ -42,10 +42,13 @@ export async function parseAsyncWithFriendlyErrors<T extends z.Schema>(
 	input: z.input<T>,
 	message: string
 ): Promise<z.output<T>> {
-	return processParsedData(await schema.safeParseAsync(input, { errorMap }), message);
+	return processParsedData<T>(await schema.safeParseAsync(input, { errorMap }), message);
 }
 
-function processParsedData(parsedData: z.SafeParseReturnType<any, any>, message: string) {
+function processParsedData<T extends z.Schema>(
+	parsedData: z.SafeParseReturnType<T, T>,
+	message: string
+) {
 	if (!parsedData.success) {
 		throw new AstroError(message, parsedData.error.issues.map((i) => i.message).join('\n'));
 	}
@@ -60,7 +63,7 @@ const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 		// raise a single error when `key` does not match:
 		// > Did not match union.
 		// > key: Expected `'tutorial' | 'blog'`, received 'foo'
-		let typeOrLiteralErrByPath: Map<string, TypeOrLiteralErrByPathEntry> = new Map();
+		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);
@@ -69,7 +72,7 @@ const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 				} else {
 					typeOrLiteralErrByPath.set(flattenedErrorPath, {
 						code: unionError.code,
-						received: (unionError as any).received,
+						received: unionError.received,
 						expected: [unionError.expected],
 					});
 				}
@@ -130,7 +133,7 @@ const errorMap: z.ZodErrorMap = (baseError, ctx) => {
 				baseErrorPath,
 				getTypeOrLiteralMsg({
 					code: baseError.code,
-					received: (baseError as any).received,
+					received: baseError.received,
 					expected: [baseError.expected],
 				})
 			),

package/utils/head.ts

@@ -7,7 +7,7 @@ import { fileWithBase } from './base';
 import { formatCanonical } from './canonical';
 import { localizedUrl } from './localizedUrl';
 
-const HeadSchema = HeadConfigSchema();
+const HeadSchema = HeadConfigSchema({ source: 'content' });
 
 /** Get the head for the current page. */
 export function getHead(

package/utils/i18n.ts

@@ -169,7 +169,7 @@ function getLocaleInfo(lang: string) {
 			label: label[0]?.toLocaleUpperCase(locale) + label.slice(1),
 			dir: getLocaleDir(locale),
 		};
-	} catch (error) {
+	} catch {
 		throw new AstroError(
 			`Failed to get locale informations for the '${lang}' locale.`,
 			'Make sure to provide a valid BCP-47 tags (e.g. en, ar, or zh-CN).'
@@ -184,9 +184,11 @@ function getLocaleInfo(lang: string) {
 function getLocaleDir(locale: Intl.Locale): 'ltr' | 'rtl' {
 	if ('textInfo' in locale) {
 		// @ts-expect-error - `textInfo` is not typed but is available in v8 based environments.
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-return
 		return locale.textInfo.direction;
 	} else if ('getTextInfo' in locale) {
 		// @ts-expect-error - `getTextInfo` is not typed but is available in some non-v8 based environments.
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access
 		return locale.getTextInfo().direction;
 	}
 	// Firefox does not support `textInfo` or `getTextInfo` yet so we fallback to a well-known list

package/utils/navigation.ts

@@ -254,7 +254,7 @@ function treeify(routes: Route[], locale: string | undefined, baseDir: string):
 				const isLeaf = index === parts.length - 1;
 
 				// Handle directory index pages by renaming them to `index`
-				if (isLeaf && currentNode.hasOwnProperty(part)) {
+				if (isLeaf && Object.hasOwn(currentNode, part)) {
 					currentNode = currentNode[part] as Dir;
 					part = 'index';
 				}

package/utils/plugins.ts

@@ -52,14 +52,14 @@ export async function runPlugins(
 					// Merge the translations injected by the plugin.
 					for (const [locale, localeTranslations] of Object.entries(translations)) {
 						pluginTranslations[locale] ??= {};
-						Object.assign(pluginTranslations[locale]!, localeTranslations);
+						Object.assign(pluginTranslations[locale], localeTranslations);
 					}
 				},
 			});
 		}
 	}
 
-	const useTranslations = createTranslationSystemFromFs(
+	const useTranslations = await createTranslationSystemFromFs(
 		starlightConfig,
 		context.config,
 		pluginTranslations
@@ -319,7 +319,9 @@ const configSetupHookSchema = z
 				 *	}
 				 * }
 				 */
-				useTranslations: z.any() as z.Schema<ReturnType<typeof createTranslationSystemFromFs>>,
+				useTranslations: z.any() as z.Schema<
+					Awaited<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
@@ -436,7 +438,7 @@ 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;
+> = HookFn extends (...args: any[]) => unknown ? Parameters<HookFn>[0] : never;
 
 export type StarlightUserConfigWithPlugins = StarlightUserConfig & {
 	/**

package/utils/routing/data.ts

@@ -32,11 +32,11 @@ export async function getRoute(context: APIContext): Promise<Route> {
 	);
 }
 
-export async function useRouteData(
+export function useRouteData(
 	context: APIContext,
 	route: Route,
 	{ Content, headings }: RenderResult
-): Promise<StarlightRouteData> {
+): StarlightRouteData {
 	const routeData = generateRouteData({ props: { ...route, headings }, context });
 	return { ...routeData, Content };
 }
@@ -118,7 +118,7 @@ function getEditUrl({ entry }: PageProps): URL | undefined {
 export function getSiteTitle(lang: string): string {
 	const defaultLang = config.defaultLocale.lang as string;
 	if (lang && config.title[lang]) {
-		return config.title[lang] as string;
+		return config.title[lang];
 	}
 	return config.title[defaultLang] as string;
 }

package/utils/starlight-page.ts

@@ -187,12 +187,12 @@ async function getStarlightPageFrontmatter(frontmatter: StarlightPageFrontmatter
 			// well as containing the metadata properties and this ensures we handle those correctly.
 			z.custom(
 				(value) =>
-					value &&
-					(typeof value === 'function' || typeof value === 'object') &&
-					'src' in value &&
-					'width' in value &&
-					'height' in value &&
-					'format' in value,
+					(value &&
+						(typeof value === 'function' || typeof value === 'object') &&
+						'src' in value &&
+						'width' in value &&
+						'height' in value &&
+						'format' in value) as ReturnType<ImageFunction>,
 				'Invalid image passed to `<StarlightPage>` component. Expected imported `ImageMetadata` object.'
 			)) as ImageFunction,
 	});

package/utils/translations-fs.ts

@@ -16,13 +16,13 @@ const contentCollectionFileExtensions = ['.json', '.yaml', '.yml'];
  *
  * @see [`./translations.ts`](./translations.ts)
  */
-export function createTranslationSystemFromFs<T extends i18nSchemaOutput>(
+export async function createTranslationSystemFromFs<T extends i18nSchemaOutput>(
 	opts: Pick<StarlightConfig, 'defaultLocale' | 'locales'>,
 	{ srcDir }: Pick<AstroConfig, 'srcDir'>,
 	pluginTranslations: Record<string, T> = {}
 ) {
 	/** All translation data from the i18n collection, keyed by `id`, which matches locale. */
-	let userTranslations: Record<string, i18nSchemaOutput> = {};
+	const userTranslations: Record<string, i18nSchemaOutput> = {};
 	try {
 		const i18nDir = new URL('content/i18n/', srcDir);
 		// Load the user’s i18n directory
@@ -34,11 +34,12 @@ export function createTranslationSystemFromFs<T extends i18nSchemaOutput>(
 			const id = filePath.name;
 			const url = new URL(filePath.base, i18nDir);
 			const content = fs.readFileSync(new URL(file, i18nDir), 'utf-8');
-			const data =
+			const data = (
 				filePath.ext === '.json'
 					? JSON.parse(content)
-					: yaml.load(content, { filename: fileURLToPath(url) });
-			userTranslations[id] = data as i18nSchemaOutput;
+					: yaml.load(content, { filename: fileURLToPath(url) })
+			) as i18nSchemaOutput;
+			userTranslations[id] = data;
 		}
 	} catch (e: unknown) {
 		if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {

package/utils/translations.ts

@@ -8,6 +8,7 @@ import type { RemoveIndexSignature } from './types';
 import { getCollectionPathFromRoot } from './collection';
 import { stripExtension, stripLeadingSlash } from './path';
 
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore - This may be a type error in projects without an i18n collection and running
 // `tsc --noEmit` in their project. Note that it is not possible to inline this type in
 // `UserI18nSchema` because this would break types for users having multiple data collections.
@@ -28,6 +29,7 @@ async function loadTranslations() {
 	const warn = console.warn;
 	console.warn = () => {};
 	const userTranslations: Record<string, UserI18nSchema> = Object.fromEntries(
+		// 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 =
@@ -49,7 +51,7 @@ async function loadTranslations() {
  * const t = useTranslations('en');
  * const label = t('search.label'); // => 'Search'
  */
-export const useTranslations = createTranslationSystem(
+export const useTranslations = await createTranslationSystem(
 	config,
 	await loadTranslations(),
 	pluginTranslations

package/utils/user-config.ts

@@ -149,7 +149,7 @@ const UserConfigSchema = z.object({
 	 *  ],
 	 * })
 	 */
-	head: HeadConfigSchema(),
+	head: HeadConfigSchema({ source: 'config' }),
 
 	/**
 	 * Provide CSS files to customize the look and feel of your Starlight site.